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_postlabel_mapping_rules_getlabel_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.xxxTo 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"
}
}
]
}
]