Skip to main content

REST APIs for 24.2.20 and 24.2.10

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/rule_sets

Get a specified ruleset.

GET

[api_version[org_href]/sec_policy/rule_sets/ rule_set_id]

Create a ruleset.

POST

[api_version][org_href]/sec_policy/rule_sets

Update a specified ruleset.

PUT

[api_version][org_href]/sec_policy/rule_sets/rule_set_id]

Delete a specified ruleset.

DELETE

[api_version][org_href]/sec_policy/rule_sets/rule_set_id]

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, all instances of that type are permitted. For example, all applications are within the scope if application labels are omitted but environment and location labels are present.

    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 security policy's needs.

    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 of one or more providers (provides a service over a port and protocol), one or more consumers (consumes the service offered by the Source), and one or more services. A Source or Destination can be an individual workload, a role label representing multiple workloads, IP lists, etc.

Example Ruleset Scope

Each label in a scope is identified by its HREF. 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

Note

The common schema consuming_security_principals has been replaced by two other APIs: consuming_security_principals_get and consuming_security_principals_put

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

For information, see Rules.

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 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/:pversion/rule_sets

URI to Get an Individual Ruleset

[api_version[org_href]/sec_policy/rule_sets/rule_set_id]
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]
Update a Ruleset

You need the HREF of the ruleset you want to update to update an individual ruleset, 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

PUT /api/v2/orgs/1/sec_policy/draft/rule_sets/123/sec_rules.

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]
See also: