Skip to main content

REST API Developer Guide 22.2

Rulesets

This Public Stable API gets, creates, updates, and deletes rulesets. Rulesets contain rules and scopes, which define where the rules apply.

Ruleset API Methods

Functionality

HTTP

URI

Get a collection of rulesets

GET

[api_version][org_href]/sec_policy/pversion/rule_sets

Get a specified ruleset

GET

[api_version][ruleset_href]

Create a ruleset

POST

[api_version][org_href]/sec_policy/draft/rule_sets

Update a specified ruleset

PUT

[api_version][ruleset_href]

Delete a specified ruleset

DELETE

[api_version][ruleset_href]

Active vs. Draft
Ruleset Components

Rulesets are the core of the Illumio Core policy model, and consist of the following elements:

  • Scopes: Sets of labels (application, environment, and location) that define the boundaries of the rules in a ruleset. If the workloads specified in the rules share the same labels in a ruleset scope, then those workloads and their communications are governed by the rules of the ruleset.

    A scope can contain zero or more application, environment, and location labels. A scope can also contain one or more label groups.

    If the scope is an empty array ([]), then the scope includes all applications, environments, and locations.

    If one of the label types is not specified, then all instances of that type are permitted. For example, if application labels are omitted but environment and location labels are present, then all applications are within the scope.

    A label type cannot be used in a rule unless the scope for the label type is “All.” For example, to use a location label, the scope would have to be an empty array ([]), or if there is an application label and an environment label in the scope, the location label cannot be defined in the scope.

    A ruleset is not limited to a single scope. A rule can contain multiple scopes depending on the needs of the security policy.

    Important

    Role labels are not used in scopes, but can be used in rules. Never use a role label in a scope.

  • Rules: A security rule consisting one or more providers (provides a service over a port and protocol), one or more consumers (consumes the service offered by the provider), and one or more services. A provider or consumer can be an individual workload, a role label that represents multiple workloads, IP lists, and so on.

Example Ruleset Scope

Each label in a scope is identified by its HREF. For example, this is the JSON representation of a single ruleset scope with three labels.

Each label must have a different key (role, app, loc, or env). Duplicate label keys are allowed in a scope only if they are in a label group.

{
  "scopes": [
    [
      {"label": {"href": "/orgs/7/labels/105"}},
      {"label": {"href": "/orgs/7/labels/88"}},
      {"label": {"href": "/orgs/7/labels/98"}}
    ]
  ]
}
Ruleset Rules

Ruleset rules define the allowed communication between workloads, or between workloads and IP lists.

Get Rulesets

This method gets all of the rulesets in your organization. This method gets those rulesets that are in the “draft” policy state, which means the current state of rulesets that have not been provisioned.

By default, the maximum number returned on a GET collection of rulesets is 500.

Note

To return more than 500 rulesets, use an Asynchronous GET Collection.

URI to Get a Collection of Rulesets

pversion: Contains provisionable objects, which exist in either a draft (not provisioned) or active (provisioned) state. .

GET [api_version][org_href]/sec_policy/draft/rule_sets

URI to Get an Individual Ruleset

GET [api_version][ruleset_href]

Query Parameters

You can use the following query parameters to restrict the results of the query to get a collection of rulesets.

Parameter

Description

Type

Required

org_id

Organization

Integer

Yes

pversion

Security Policy version

String

Yes

name

Name of the rulesets to filter. This parameter supports partial matches.

String

No

external_data_reference

A unique identifier within the external data source. For example, if ruleset information is stored in an external database.

String

No

external_data_set

The data source from which the resource originates. For example, if ruleset information is stored in an external database.

String

No

labels

List of lists of label URIs, encoded as a JSON string

String

No

max_results

Maximum number of Rule Sets to return

Integer

Noi

Parameter

Description

Type

Required

org_id

Organization

Integer

Yes

pversion

Security Policy version

String

Yes

name

Name of the rulesets to filter. This parameter supports partial matches.

String

No

external_data_reference

A unique identifier within the external data source. For example, if ruleset information is stored in an external database.

String

No

external_data_set

The data source from which the resource originates. For example, if ruleset information is stored in an external database.

String

No

labels

List of lists of label URIs, encoded as a JSON string

String

No

Curl Command to Get Rulesets

To get all active rulesets in the current security policy, use active instead of draft.

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/3/sec_policy/draft/rule_sets -H "Accept: application/json" -u $KEY:$TOKEN

Curl Command to Get a Ruleset

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/3/sec_policy/draft/rule_sets/90 -H "Accept: application/json" -u $KEY:$TOKEN

Response

The following response shows an example of rulesets that are returned from a get collection of rulesets. Each ruleset is defined as an HREF (the first property of the ruleset in the response). Use the HREF of a ruleset to get, update, or delete an individual ruleset.

[
  {
    "href": "/orgs/1/sec_policy/draft/rule_sets/90",
    "created_at": "2019-05-11T21:55:22.930Z",
    "updated_at": "2019-06-14T18:08:59.134Z",
    "deleted_at": null,
    "created_by": {"href": "/users/1"},
    "updated_by": {"href": "/users/1"},
    "deleted_by": null,
    "name": "Rset",
    "description": "",
    "external_data_set": "",
    "external_data_reference": "",
    "enabled": true,
    "scopes": [
      [
        {"label": {"href": "/orgs/1/labels/11"}},
        {"label": {"href": "/orgs/1/labels/9"}},
        {"label": {"href": "/orgs/1/labels/18"}}
      ]
    ],
    "rules": [
      {
        "href": "/orgs/1/sec_policy/draft/rule_sets/90/
		sec_rules/111",
        "created_at": "2019-06-13T21:19:58.078Z",
        "updated_at": "2019-06-13T21:19:58.078Z",
        "deleted_at": null,
        "created_by": {"href": "/users/1"},
        "updated_by": {"href": "/users/1"},
        "deleted_by": null,
        "update_type": null,
        "description": null,
        "enabled": true,
        "providers": [
          {"label": {"href": "/orgs/1/labels/17"}}
        ],
        "consumers": [
          {"label": {"href": "/orgs/1/labels/1"}}
        ],
        "consuming_security_principals": [],
        "sec_connect": false,
        "stateless": false,
        "machine_auth": false,
        "unscoped_consumers": false,  
        "ingress_services": [],
        "resolve_labels_as": {
          "providers": ["virtual_services"],
          "consumers": ["workloads"]
        },
      } 
    ],
    "ip_tables_rules": [],
    "caps": ["write"]
  }
]
Create a Ruleset

This method creates an individual ruleset. The PCE web console supports up to 500 rules per ruleset.

Note

To write more than 500 rules for a particular ruleset, create additional rulesets, or use the Illumio Core REST API (rulesets with more than 500 rules are not fully displayed in the PCE web console).

URI to Create a Ruleset

POST [api_version][ruleset_href]

Required Properties for POST

Property

Description

Type

Required

name

Name of the new ruleset, which must be unique.

String

Yes

scopes

Indicate the boundaries of the rules in the ruleset by specifying a

set of one or more unique label scopes.

Each scope must include the label HREF

(for example, /orgs/1/labels/24).

  • app: Application label or label group

  • env: Environment label or label group

  • loc: Location label or label group

You can also use a label group for a ruleset scope, and each label

of the specific type (app, env, or loc) and all labels in each label

group are used for the ruleset scope.

To create a ruleset with scope=All/All/All, use an empty arrays

for pb and ub scopes.

Array

Yes

Request Body

This example illustrates the request body for creating a new ruleset with three scopes and two intra-scope rules.

{
  {
  "name": "Demo RS",
  "enabled": true,
  /* Two ruleset scopes, each with an application, 
     an environment, and a location label. To have more 
     than one type of label in a scope, use a label group 
     that contains only labels of that type. */

  "scopes":[
    [
      {"label": {"href": "/orgs/1/labels/24"}},
      {"label": {"href": "/orgs/1/labels/27"}},
      {"label": {"href": "/orgs/1/labels/21"}}
    ],
    [ 
      {"label": {"href": "/orgs/1/labels/15"}},
      {"label": {"href": "/orgs/1/labels/16"}},
      {"label": {"href": "/orgs/1/labels/17"}}
    ]
  ],
  "rules": [
  /* Label to label, intra-scope. */
    {
      "enabled": true,
      "providers": [{"label": {"href": "/orgs/1/labels/2"}}],
      "consumers": [{"label": {"href": "/orgs/1/labels/1"}}],
      "consuming_security_principals": [],
      "ingress_services": [{"href": "/orgs/1/sec_policy/draft/services/20"}],
      "resolve_labels_as": {
        "providers": ["workloads"],
        "consumers": ["workloads"]
      },
      "sec_connect": false,
      "unscoped_consumers": false
    },
    /* This illustrates a provider with multiple labels and an 
	IP list as a consumer.Note that both provider labels must be role 
	labels in this context, becausethe ruleset scope already has 	   	
       application, environment, and location labels. */
...........................................
}

Curl Command to Create Two Rules

curl -i -X POST https://pce.my-company.com/api/v2/orgs/2/sec_policy/draft/rule_sets -H "Content-Type:application/json"-u $KEY:$TOKEN -d '{"name":"Demo RS","enabled":true,"scopes":[[{"label":{"href":"/orgs/1/labels/24"}}], [{"label":{"href":"/orgs/1/labels/27"}}], [{"label":{"href":"/orgs/1/labels/21"}}]],"rules":[{"enabled":true,"providers":[{"label":{"href":"/orgs/1/labels/2"}}],"consumers":[{"label":{"href":"/orgs/1/labels/1"}}],"consuming_security_principals":[],"ingress_services":[{"proto": 6}],"resolve_labels_as":{"providers":["workloads"]"consumers":["workloads"]},"sec_connect":false,"unscoped_consumers":false}, {"enabled":true,"providers":[{"label":{"href":"/orgs/1/labels/3"}},{"label":{"href":"/orgs/1/labels/1"}}],"consumers":[{"ip_list":{"href":"/orgs/1/sec_policy/draft/ip_lists/1"}}],"consuming_security_principals":[],"ingress_services":[{"proto": 6}],"resolve_labels_as":{"providers":["workloads"],"consumers":["workloads"]},"sec_connect":false,"unscoped_consumers":false}]}'
Update a Ruleset

To update an individual ruleset, you need the HREF of the ruleset you want to update, which can be obtained when you get a collection or an individual ruleset.

If you want to add a single rule to an existing ruleset, use

POST /api/v1/orgs/1/sec_policy/draft/rule_sets/123/sec_rules.

All properties are optional:

URI to Update an Individual Ruleset

PUT [api_version][ruleset_href]

Request Body

The request body for updating a ruleset is the same as for creating a ruleset, only you have modified information in the JSON payload.

Delete a Ruleset

To delete an individual ruleset, you need the HREF of the ruleset you want to delete, which can be obtained when you get a collection of rulesets.

URI to Delete an Individual Ruleset

DELETE [api_version][ruleset_href]

Curl Command to Delete Ruleset

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/draft/rule_sets/179 -u $KEY:$TOKEN
See also: