Rule-Based Label Mapping
New APIs for managing the new feature, Rule-based label mapping, are the following:
Label Mapping API Methods
Functionality | HTTP | URI |
---|---|---|
Returns the collection of label mapping rules. |
|
|
Creates a new label-mapping rule. |
|
|
Deletes multiple label mapping rules |
|
|
Gets the instance of a single label-mapping rule. |
|
|
Updates the instance of a single rule. |
|
|
Deletes the specified label-mapping rule. |
|
|
Reorders label-mapping rules. |
|
|
This asynchronous API runs a set of label-mapping rules on a set of workloads. |
|
|
Gets the status of the async job to run the rules. |
|
|
Downloads the results of the run rules job. |
|
|
Assign labels from the results of the label-mapping rules run the job. |
|
|
Bulk label update |
|
|
Bulk label update
If an organization has 500 rules defined, the UI must make up to 500 individual calls in an enable/disable rules operation.
This issue is resolved using the "bulk update" endpoint, which was chosen instead of a "bulk enable/disable" API because it provides additional flexibility to support future use cases.
label_mapping_rule_label_assignments.schema.json
The property label_assignment
was deleted and replaced with a reference to label_mapping_rule_label_assignments.schema.json
for the following APIs:
label_mapping_rules_post
label_mapping_rules_get
label_mapping_rules_put
Rule-Based Label Mapping Reference
This topic covers examples and schemas for rule-based label mapping.
Label Mapping Rule Expression Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"anyOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"property",
"operator",
"values"
],
"properties": {
"property": {
"description": "The workload property to compare. (hostname, ip_address etc.)",
"type": "string",
"enum": [
"hostname",
"ip_address",
"os",
"process",
"port"
]
},
"operator": {
"description": "operator for the condition (starts_with, contains, equals, ends_with, is_in, regex)",
"type": "string",
"enum": [
"starts_with",
"ends_with",
"contains",
"equals",
"is_in",
"regex"
]
},
"values": {
"description": "Value to use in comparison",
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"port": {
"description": "Port Number (integer 0-65535). Also the starting port when specifying a range.",
"type": "integer",
"minimum": 0,
"maximum": 65535
},
"to_port": {
"description": "High end of port range inclusive if specifying a range. If not specifying a range then don't include this.",
"type": "integer",
"minimum": 0,
"maximum": 65535
},
"proto": {
"description": "protocol number",
"type": "integer"
}
}
}
]
}
}
}
},
{
"type": "object",
"required": [
"logical_operator",
"child_expressions"
],
"properties": {
"logical_operator": {
"description": "logical operator for the child expressions",
"type": "string",
"enum": [
"and",
"or",
"not"
]
},
"child_expressions": {
"type": "array",
"items": {
"$ref": "#"
}
}
}
}
]
}
In release 25.3, this schema has a new operator: regex
. It was added to the existing list of supported operators in APIs (request and response) .
For Hostname, OS, and Process, these are the 'regex' operator examples:
Hostname regex '^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\\.illumio\\.com$' #will match any hostname under the illumio.com domain Hostname regex '/^(?=.*?(pc|fileserver|notebook))(?=.*?\d)[a-z\d-]+$/' #will match something like fileserver-win2019 OS regex '*win*' #will match with anything that has win in it OS regex '/\b(lin|centos|ubuntu|redhat)\b/i' #will match Linux, linux, Centos-3.7.0 , ubuntu-x86_64-xenial Process regex '^/.*/chshell$' #will match /user/bin/chshell. regex uses the ^ and $ anchors to match the beginning and end of the string Process regex ''
For IP Address 'regex'
IP Address regex '^(192\.168)\.([01]?[0-9]?[0-9]|2([0-4][0-9]|5[0-5]))\. ([01]?[0-9]?[0-9]|2([0-4][0-9]|5[0-5]))$' #will match IP addresses in the range of 192.168.0.0 - 192.168.255.255: IP Address regex '^(\\d{1,3}\\.){3}\\d{1,3}$' will match any IP address in the format xxx.xxx.xxx.xxx
To learn more about using regex, see Add Labeling Rule in Security Policy Guide.
Examples
Example response for GET /api/v2/orgs/:xorg_id/label_mapping_rules
[ { "href": "/orgs/1/label_mapping_rules/48ed8903-878e-4010-859a-63d19be797c3", "enabled": true, "position": 40, "created_at": "2024-04-24T06:54:00.530Z", "updated_at": "2024-04-24T06:54:00.535Z", "expression": { "property": "hostname", "values": [ "this" ], "operator": "starts_with" }, "created_by": { "href": "/users/2" }, "updated_by": { "href": "/users/2" }, "label_assignments": [ { "label": { "href": "/orgs/1/labels/24" } }, { "label": { "href": "/orgs/1/labels/11" } }, { "label": { "href": "/orgs/1/labels/20" } } ] }, { "href": "/orgs/1/label_mapping_rules/d1479032-f7cb-479f-87bd-1bc7bd816a74", "enabled": true, "position": 41, "created_at": "2024-04-26T18:18:10.238Z", "updated_at": "2024-04-26T18:18:10.256Z", "expression": { "property": "hostname", "values": [ "perf-workload-1" ], "operator": "equals" }, "created_by": { "href": "/users/1" }, "updated_by": { "href": "/users/1" }, "label_assignments": [ { "label": { "href": "/orgs/1/labels/9" } } ] }, { "href": "/orgs/1/label_mapping_rules/d4ddb653-56e9-4150-a93e-8a734c510c03", "enabled": true, "position": 43, "created_at": "2024-04-28T00:05:38.146Z", "updated_at": "2024-04-28T00:05:38.150Z", "expression": { "property": "hostname", "values": [ "perf-workload-2" ], "operator": "equals" }, "created_by": { "href": "/users/2" }, "updated_by": { "href": "/users/2" }, "label_assignments": [ { "label": { "href": "/orgs/1/labels/7" } } ] } ]
Example Request for POST /api/v2/orgs/:xorg_id/label_mapping_rules
{ "expression": { "logical_operator": "and", "child_expressions": [ { "property": "os", "operator": "equals", "values": ["linux"] }, { "property": "process", "operator": "contains", "values": ["mysql"] } ] }, "label_assignments": [ { "label": { "key": 'os', "value": 'Linux' } }, { "label": { "key": 'role', "value": 'Database' } } ] } }
Example Response for POST /api/v2/orgs/:xorg_id/label_mapping_rules
{ "href": "/orgs/1/label_mapping_rules/4512e359-bda3-49d1-8f9e-b9a03357e4ee", "enabled": true, "position": 2, "created_at": "2024-04-18T23:45:49.237Z", "updated_at": "2024-04-18T23:45:49.290Z", "expression": { "property": "os", "operator": "contains", "values": [ "windows" ] }, "created_by": { "href": "/users/1" }, "updated_by": { "href": "/users/1" }, "label_assignments": [ { "label": { "key": "os", "value": "Windows" } } ] }
Example Request to Enable Multiple Rules
[ { "href": "/orgs/1/label_mapping_rules/84e19944-2ae1-4985-9ace-ca2e109da80e", "enabled": true }, { "href": "/orgs/1/label_mapping_rules/15c3711c-3821-4719-8c10-a3e89966b66e", "enabled": true } ]
Example Request to Disable Multiple Rules
[ { "href": "/orgs/1/label_mapping_rules/84e19944-2ae1-4985-9ace-ca2e109da80e", "enabled": false }, { "href": "/orgs/1/label_mapping_rules/15c3711c-3821-4719-8c10-a3e89966b66e", "enabled": false } ]
Example Request to Update Multiple Rules
[ { "href": "/orgs/1/label_mapping_rules/84e19944-2ae1-4985-9ace-ca2e109da80e", "expression": { "property": "hostname", "operator": "equals", "values": [ "foo" ] }, "label_assignments": [ { "label": { "href": "/orgs/1/labels/46" } } ] }, { "href": "/orgs/1/label_mapping_rules/15c3711c-3821-4719-8c10-a3e89966b66e", "expression": { "logical_operator": "and", "child_expressions": [ { "values": [ "/usr/bin/node" ], "operator": "equals", "property": "process" }, { "values": [ { "port": 3000, "proto": 6 } ], "operator": "equals", "property": "port" } ] }, "label_assignments": [ { "label": { "href": "/orgs/1/labels/44" } } ] } ]