Function instances for Firewall

A function instance binds one function to one firewall and holds the arguments that function receives on that firewall. The instance runs only when a rule in Rules Engine for Firewall names it in a Run Function behavior. For example, one firewall can hold two instances of Bot Manager Lite with different threshold values, and each rule runs the instance it names.

Instance fields

Each firewall holds its own function instances. Azion Console lists them in the firewall’s Functions Instances tab, where the Function button opens a drawer with three sections: General, Function, and Arguments. The API serves the same records under /v4/workspace/firewalls/<firewall-id>/functions, and Azion CLI under the firewall-instance noun. An instance carries nine fields: five that a request sets, and four that the platform sets and returns.

The Functions Instances list shows the columns Name, Function, Last Editor, and Last Modified. It has no status column, and Delete is its only row action.

The Function selector lists only the functions in the account whose execution_environment is firewall, and its Create Function footer creates one. The API refuses a function with any other environment, with Invalid edge function runtime. You should use a function designed for Edge Firewall. Functions from Azion Marketplace, such as Bot Manager Lite, Secure Token, and JWT, are firewall functions as well. A Marketplace function reaches the account through Azion Console, because neither Azion CLI nor the API has an install operation. Its record does not expose its source code.

An instance never changes the code of its function. It sets the name, the arguments, and whether the instance is active.

The Functions Instances tab appears only when Functions is enabled on the firewall. The switch is Functions in the firewall’s Main Settings tab, and modules.functions.enabled in the API. Functions is on when a firewall is created through the API, the CLI, or the Console create page. The Console create drawer is the exception, and starts Functions off.

An application holds the same object under a tab of the same name. An instance on a firewall runs its function before the request reaches the application, so the function can stop the request there. An instance on an application runs its function as part of serving the request. For more information, refer to Function instances.

Arguments

The arguments of an instance are the JSON value in its args field, and the function reads them each time the instance runs. They let one function behave differently in each instance: the code stays the same, and only the values change. In Azion Console, the Arguments section of the instance drawer edits them. When the selected function carries a non-empty azion_form, the section offers two modes: Form, the default, which builds a form from that schema, and JSON. Otherwise, the JSON editor appears alone.

The help text of the editor says that code reads an argument with event.args('arg_name'). For the code side of a firewall function, refer to Functions for Firewall.

An args object that sets four Bot Manager Lite arguments:

All four keys are among the arguments Bot Manager Lite ships defaults for. A key the function does not read is saved the same way, and the function ignores it.

Default arguments

A function record carries default_args, the argument values the function ships with, next to its azion_form. The command azion describe function --function-id <function-id> returns both. When an instance supplies no arguments, the function runs with its default_args. A key the instance sets takes the value the instance gives it.

The fallback happens at run time, not in the instance record. The record keeps only what it was sent, so an instance created with {} reads back {}, not the defaults of its function. For example, Bot Manager Lite ships a threshold of 30 in its default_args. An instance of it with args of {} shows no threshold, and runs at 30.

The eight default arguments of Bot Manager Lite are action, bad_fingerprint_list, disabled_rules, good_fingerprint_list, internal_logs, log_headers, log_tag, and threshold. For what each one does, refer to Arguments.

Argument validation

The platform checks args for two things only. Azion Console refuses content that does not parse, with Invalid JSON, and the API refuses a value larger than 100,000 bytes. The bound is decimal: a payload of 102,400 bytes is refused with Value size (in bytes) is too big. Maximum size allowed is 100000 bytes. For every bound a firewall applies, refer to Firewall limits.

Nothing checks the keys or the values against the function. The platform stores every key as sent, with its JSON type, including a key the function never reads, and the save succeeds. For example, a Bot Manager Lite instance with "thresold": 5 saves and reads back exactly as typed, and does not lower the threshold. No interface reports the misspelled key, so compare each key name with the documentation of the function before you save.

Run Function behavior

A function instance runs only when a firewall rule names it in a Run Function behavior. When a request matches the criteria of that rule, the platform runs the function with the arguments of the instance. The function runs on Azion’s distributed infrastructure, before the request reaches the application. What the client receives then depends on what the function does with the request.

In the API, the behavior is run_function, and its value attribute holds the id of the instance, never the ID of the function:

In Azion Console, choosing Run Function adds the Select a Function list. The list holds the active instances of this firewall rather than the functions of the account, and its Create Function Instance footer creates one. Each rule can hold one Run Function behavior, so one rule runs one instance.

The behavior requires Functions enabled on the firewall and access to Functions in the account. Without either, the Console shows Run Function - required Functions and does not let you select it.

A rule that runs one instance on every request, because ${request_uri} starts_with / matches every URI:

For the order a firewall runs its rules in, refer to How Firewall works.

API

Instance operations sit under https://api.azion.com/v4/workspace/firewalls/<firewall-id>/functions. Each call authenticates with a personal token in the header Authorization: Token [TOKEN VALUE], and a call with a body adds Content-Type: application/json.

In these paths, {function_id} takes the ID of the instance, not the ID of the function. Creating or deleting an instance answers 202. Reading one answers 200, with the record in data and no state key.

Create an instance of Bot Manager Lite with four arguments set, where <function-id> is the ID of the Bot Manager Lite function in your account:

The response answers 202, with a state of pending and the instance in data. This excerpt keeps id and the fields the call sent:

The platform stores azion_form as {} because the call sent none. The id in data is the value a Run Function behavior sends.

CLI

The firewall-instance noun of Azion CLI creates, lists, and reads instances.

The --args flag takes the path of a JSON file, not inline JSON. A file that sets three arguments:

Save it as args.json, then create the instance:

Read the instance back:

The arguments return with the keys, values, and JSON types the file sent. An excerpt of the record:

Errors

Azion CLI prints the message of the platform inside Error: failed to create the Firewall Function Instance: [...], or inside Error: failed to create the Firewall Rule: [...] for a rule. The table lists each message as it appears, with what causes it.

Related resources