Azion CLI rules-engine

Azion CLI commands that create, list, describe, update, order, and delete the Rules Engine rules of an application, with every flag and default.

Last updated

View as Markdown Agent setup

The Azion CLI rules-engine commands create, list, describe, update, order, and delete the rules of an application’s Rules Engine. A rule holds criteria that a request or a response must match and the behaviors it then applies. Every rule belongs to one phase, request or response, and each command takes that phase with --phase. The options every command accepts, such as --format, --out, and -y, are on Global options.

Create

azion create rules-engine creates a rule in one phase of an application, from a JSON file:

azion create rules-engine [flags]
FlagShortTypeDefaultDescription
--application-id—int—ID of the application that runs the rule.
--file—string—Required. Path to a JSON file with the attributes of the rule. Use - to read the JSON from standard input. Without it, the command asks for the path.
--phase—string—Phase of the rule, request or response.

A --phase value other than request or response is refused with Error: Invalid phase value provided. The value must be 'request' or 'response'.

This file describes a rule that delivers every request whose URI starts with /static:

JSON
01{
02 "name": "my-rule",
03 "active": true,
04 "criteria": [
05 [
06 {
07 "variable": "${uri}",
08 "operator": "starts_with",
09 "conditional": "if",
10 "argument": "/static"
11 }
12 ]
13 ],
14 "behaviors": [
15 {
16 "type": "deliver"
17 }
18 ]
19}

This command creates the rule in the request phase of the application with ID 1234567890:

azion create rules-engine --application-id 1234567890 --phase request --file rule-create.json

The command prints the ID of the rule:

Created Rules Engine with ID 123456

List

azion list rules-engine lists the rules of one phase of an application, 50 to a page:

azion list rules-engine [flags]
FlagShortTypeDefaultDescription
--application-id—int—ID of the application whose rules to list.
--details———Adds the ORDER, PHASE, and ACTIVE columns to the ID and NAME columns.
--filter—string—Name to filter the list by.
--order-by—string—Field to sort the list by.
--page—int1Number of the page to return.
--page-size—int50Number of rules on each page.
--phase—string"request"Required. Phase of the rules to list, request or response. Without it, the command asks for the phase instead of taking the default.

This command lists the rules in the request phase of the application with ID 1234567890:

azion list rules-engine --application-id 1234567890 --phase request

The command prints one row per rule:

Text
01ID NAME
02123456 my-rule
03123457 my-rule-2

Describe

azion describe rules-engine prints the criteria, the behaviors, and the position of one rule:

azion describe rules-engine [flags]
FlagShortTypeDefaultDescription
--application-id—int—ID of the application that runs the rule.
--phase—string—Phase of the rule, request or response. In the other phase, the rule is not found.
--rule-id—int—ID of the rule to describe.

A rule described in the wrong phase fails with Error: Failed to describe the rule in Rules Engine: The given ID or API's endpoint doesn't exist or isn't available.

This command describes the rule with ID 123456 in the request phase:

azion describe rules-engine --application-id 1234567890 --rule-id 123456 --phase request

The command prints the attributes of the rule:

Text
01Rules Engine ID: 123456
02Name: my-rule
03Active: true
04Criteria: [[{"argument":"/static","conditional":"if","operator":"starts_with","variable":"${uri}"}]]
05Behaviours: [{"type":"deliver"}]
06Description:
07Order: 0

With --format json, the command prints the full object: active, behaviors, created_at, criteria, description, id, last_editor, last_modified, name, and order. With --out and a file path, the command writes the same JSON to that file, with or without --format json.

Update

azion update rules-engine changes the attributes of a rule from a JSON file:

azion update rules-engine [flags]
FlagShortTypeDefaultDescription
--application-id—int—Required. ID of the application that runs the rule.
--file—string—Required. Path to a JSON file with the attributes to change. Use - to read the JSON from standard input. Without it, the command asks for the path.
--phase—string—Required. Phase of the rule, request or response.
--rule-id—int—Required. ID of the rule to update.

The update is partial. Keys that the file leaves out keep their values, so a file without criteria or behaviors keeps the ones the rule has.

This file renames the rule, turns it off, and adds a description:

JSON
01{
02 "name": "my-rule-updated",
03 "active": false,
04 "description": "Delivers static files"
05}

This command applies the file to the rule with ID 123456:

azion update rules-engine --application-id 1234567890 --rule-id 123456 --phase request --file rule-update.json

The command prints the ID of the updated rule:

Updated Rules Engine with ID 123456

Order rules

azion update rules-engine-order sets the order in which the rules of one phase run, from a list of rule IDs:

azion update rules-engine-order [flags]
FlagShortTypeDefaultDescription
--application-id—int—ID of the application that runs the rules.
--phase—string—Phase of the rules, request or response.
--rule-ids—string—Rule IDs in the order they run, separated by commas, such as 123,456,789.

The list must name every rule. With one of two rules left out, the command fails with this error:

Error: Failed to order the rules in Rules Engine: ["When ordering you should provide the order for all rules."]. Check your settings and try again. If the error persists, contact Azion support.

This command moves the rule with ID 123457 ahead of the rule with ID 123456:

azion update rules-engine-order --application-id 1234567890 --phase request --rule-ids "123457,123456"

The command confirms the new order:

Ordered Rules Engine of Application with ID 1234567890

A list with --details then shows the new position of each rule in the ORDER column, starting at 0:

azion list rules-engine --application-id 1234567890 --phase request --details
Text
01ID NAME ORDER PHASE ACTIVE
02123457 my-rule-2 0 request 0x2e0067998a09
03123456 my-rule 1 request 0x2e0067998dc8

Delete

azion delete rules-engine deletes a rule:

azion delete rules-engine [flags]
FlagShortTypeDefaultDescription
--application-id—int—ID of the application that runs the rule.
--phase—string"request"Required. Phase of the rule, request or response. Without it, the command asks for the phase, even with -y.
--rule-id—int—ID of the rule to delete.

This command deletes the rule with ID 123457 from the request phase:

azion delete rules-engine --application-id 1234567890 --phase request --rule-id 123457 -y

The command confirms the deletion:

Rule Engine 123457 was successfully deleted

Use a JSON file

azion create rules-engine and azion update rules-engine read the attributes of a rule only from a JSON file, passed with --file. Use - in place of the path to read the JSON from standard input. The file takes these keys:

KeyTypeDescription
namestringName of the rule.
activebooleanTurns the rule on (true) or off (false).
descriptionstringDescription of the rule.
criteriaarrayGroups of conditions. Each condition is an object with variable, operator, conditional, and argument, such as ${uri}, starts_with, if, and /static.
behaviorsarrayBehaviors the rule applies, each an object with a type, such as deliver.

On create, the file carries the whole rule. On update, the file carries only the keys to change, and the rule keeps every other value. The rule ID, the application ID, and the phase go on the command line with their flags.

Global options

The options every command accepts, such as --format, --out, and -y.

Rules Engine

The criteria, behaviors, and phases a rule can use in an application.

Azion CLI application

The commands that create and manage the application whose ID every rule command takes.

Azion CLI firewall-rule

The commands that manage the rules of a firewall, which take their own order command.