Skip to main content

REST APIs for 22.2

Policy Update Mode

This Public Experimental API controls when policy updates are applied to workloads.

Overview of Policy Update Mode

The PCE has two policy update options:

  • Adaptive: Apply policy changes as soon as you provision.

  • Static: Apply policy changes at a later time, such as during a scheduled maintenance window.

By default, the PCE policy update mode is set to Adaptive, but you can configure Static policy update mode for certain sets of workloads identified by scopes. Workloads that share the same labels configured for static policy update scope receive policy changes from the PCE, but those changes will not be applied until a user or an orchestration system instructs the PCE to apply those changes.

Configuring static policy update mode requires defining a scope that contains one or more environment, application, or location labels and role labels. If a label type is not defined in the scope, that label type is interpreted as All. For example, if the policy update scope is

Application = Checking, Location = China,

the PCE interprets the scope as

Application = Checking, Location = China, Environment = All.

Methods

Functionality

HTTP

URI

Get the current policy update mode for your organization

GET

[api_version][org_href]/sec_policy/draft/firewall_settings

Change the policy update mode for your

organization

PUT

[api_version][org_href]/sec_policy/draft/firewall_settings

Policy Update Parameters

The current firewall_settings resource specifies a combination of IPsec / IKE authentication method (PSK or certificate) for SecureConnect and Machine Authentication.

Parameter

Description

Type

Required

update_type

Type of update

String

Yes

static_policy_scopes

Scopes that have static policy application mode

No

ike_authentication_type

IKE authentication method for Secure Connect and Machine Auth connections:

psk certificate

String

No

firewall_coexistence

The current firewall coexistence mode settings

Array

Null

No

containers_inherit_host_policy_scopes

Workloads that match the scope will apply the

policy it receives both to itself and the containers hosted

blocked_connection_reject_scopes

Scopes whose blocked connection action will

be reject

Array

No

created_at

Time stamp when these firewall settings were first created

String

date/time

updated_at

Time stamp when these firewall settings were last updated

String

date/time

deleted_at

Time stamp when these firewall settings were deleted

String

date/time

created_by

Who created the policy.

Required property: href

Object

updated_by

Who updated the policy.

Required property: href

Object

deleted_by

Who deleted the policy.

Required property: href

Object

Get Policy Update Mode

You can use this method to get the current policy update mode settings for your organization, which is part of your PCE security settings. This method contains a variable (:pversion) that can be used to return the security settings with active (currently provisioned) or draft state for your organization.

URI To Get Policy Update Mode

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

Draft or Active Policy Update Mode

Variable

Description

:pversion

Allows you to get:

  • active: The currently provisioned security settings, including policy update mode

  • draft: The draft state of any changed security settings that have not yet been provisioned, including policy update mode

Curl Command Get Active Policy Update Mode

This curl example gets the active (currently provisioned) security settings for your organization, which includes the policy update mode settings.

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

Response Body

The static_policy_scopes property in the response (in blue ) indicates that two static scopes have been configured for policy update.

Each scope is defined as a JSON array of labels, which includes an Application, Environment, and a Location label. The labels in the scope are identified by their HREFs.

{
    "href": "/orgs/7/sec_policy/active/firewall_settings",
    "created_at": "2015-10-23T22:01:01.151Z",
    "updated_at": "2017-09-02T19:08:55.623Z",
    "deleted_at": null,
    "created_by": { "href": "/users/0"  },
    "updated_by": { "href": "/users/14" },
    "deleted_by": null,    
    "update_type": null,
    "allow_dhcp_client": true,
    "log_dropped_multicast": true,
    "log_dropped_broadcast": false,
    "allow_traceroute": true,
    "allow_ipv6": true,
    "allow_igmp": false,
    "track_flow": true,
    "system_rule_log_flow": false,
    "allow_path_mtu_discovery": true,
    "network_detection_mode": "single_private_brn",
    "static_policy_scopes": [
      [
        { "label": { "href": "/orgs/7/labels/83" } },
        { "label": { "href": "/orgs/7/labels/86" } },
        { "label": { "href": "/orgs/7/labels/94" } }
      ],
      [
        { "label": { "href": "/orgs/7/labels/82"  } },
        { "label": { "href": "/orgs/7/labels/100" } },
        { "label": { "href": "/orgs/7/labels/89"  } },
        { "label": { "href": "/orgs/7/labels/94"  } }
      ]
    ],
      "secure_connect_certs": {
      "default_issuer_name_match": "test",
      "scoped_certificates": []
    }
}
Change Policy Update Mode

The Change Policy Update Mode sets your organization's draft policy update mode, which might include adding or removing a policy scope.

The draft state of your policy update mode can be modified, but not the currently active (provisioned) version. First, change to the draft policy update mode, and then provision those changes.

URI To Change Policy Update Mode

PUT [api_version][org_href]/sec_policy/draft/firewall_settings

Request Properties

Property

Description

Type

Required

static_policy_scopes

A set of up to four labels, one or more of the type Application, Environment, Role, and Location.

Each label in the policy scope is identified by its HREF, nested in a JSON array.

Before updating the organization policy update mode, make sure you have the exact set of labels you want to use and their HREFs.

JSON

array of strings

Yes

Request Body

This example shows the request body for two policy update scopes. The first has a single label scope, and the second scope has a set of three labels.

{ 
  "static_policy_scopes": [
    [ 
      { "label": { "href": "/orgs/1/labels/8" } }
    ],
    [
      { "label": { "href": "/orgs/1/labels/2"  } },
      { "label": { "href": "/orgs/1/labels/8"  } },
      { "label": { "href": "/orgs/1/labels/11" } }
    ]
  ]
}

Curl Command to Update Policy Update Mode

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/7/firewall_settings -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"static_policy_scopes":[[{"label":{"href":"/orgs/1/labels/8"}}],[{"label":{"href":"/orgs/1/labels/2"}},{"label":{"href":"/orgs/1/labels/8"}},{"label":{"href":"/orgs/1/labels/11"}}]]}'

Response

The response for a successful change to your policy update mode is an HTTP 204 No Content Operation. No data is returned.

Remove all Static Policy Scopes

To remove all static policy scopes, pass an empty JSON array:

PUT [api_version][org_href]/sec_policy/draft/firewall_settings { "static_policy_scopes": [] }

Note

When all static policy scopes are removed, the policy update mode is set to Adaptive.

Curl Command to Remove Static Policy Scopes

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/7/firewall_settings -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"static_policy_scopes":[]}'