Core client

PCE Interface

PolicyComputeEngine

The PolicyComputeEngine object provides the core interface for interacting with PCE API endpoints.

class illumio.PolicyComputeEngine

The REST client core for the Illumio Policy Compute Engine.

Contains request logic for API calls and handles the HTTP(S) connection to the PCE.

Usage:

>>> import illumio
>>> pce = illumio.PolicyComputeEngine('pce.company.com', port=8443, org_id=12)
>>> pce.set_credentials('api_key', 'api_secret')
>>> workloads = pce.workloads.get(
...     params={
...         'managed': True,
...         'enforcement_mode': 'visibility_only'
...     }
... )
>>> workloads
[
    Workload(href='/orgs/12/workloads/c754a713-2bde-4427-af1f-bff145be509b', ...),
    ...
]

Parameters:

• url (str) – PCE URL. May include http:// or https:// as the scheme.

• port (str, optional) – PCE http(s) port. Defaults to ‘443’.

• version (str, optional) – The PCE API version to use. Defaults to ‘v2’.

• org_id (str, optional) – The PCE organization ID. Defaults to ‘1’.

• retry_count (int, optional) – total number of retries for the session’s retry adapter (Retry(total=retry_count)). Defaults to 5. Retries use backoff_factor=2 and cover HTTP 429/500/502/503/504, honoring the PCE’s Retry-After header. backoff_factor and the status list are not otherwise configurable here; to change them, mount your own adapter on self._session. On sustained rate limiting (HTTP 429) the retries are eventually exhausted and an IllumioApiException is raised — reduce the request rate rather than only increasing this value.

• request_timeout (int, optional) – HTTP request timeout in seconds. Defaults to 30.

base_url

DEPRECATED in v1.0.3. The base URL for API calls to the PCE. Has the form http[s]://<DOMAIN_NAME>:<PORT>/api/<API_VERSION>

include_org

flag denoting whether to prepend the orgs subpath to request endpoints by default. Defaults to True.

org_id

the PCE organization ID.

set_credentials(username, password)

Sets username and password values to authenticate with the PCE.

The provided credentials can be either user credentials or an API key/secret pair.

Parameters:

• username (str) – username or API key.

• password (str) – password or API secret.

Return type:

None

set_proxies(http_proxy=None, https_proxy=None)

Sets HTTP proxies to use when connecting to the PCE.

Parameters:

• http_proxy (str, optional) – HTTP proxy URI. Defaults to None.

• https_proxy (str, optional) – HTTPS proxy URI. Defaults to None.

Return type:

None

set_timeout(timeout)

Sets the HTTP request timeout for PCE connections.

Parameters:

timeout (int) – the new request timeout in seconds.

Return type:

None

set_tls_settings(verify=True, cert=None)

Sets TLS settings for PCE connections.

Parameters:

• verify (Union[bool, str], optional) – set TLS verification. A value of True or False will enable/disable verification respectively. A string value with a path to a CA bundle can also be provided. Defaults to True.

• cert (Union[str, tuple], optional) – set client-side certificate paths. The value can be a string with a path to a PEM containing both the certificate and private key, or a tuple of strings with paths to both files. Defaults to None.

get(endpoint, **kwargs)

Makes a GET call to a given PCE endpoint.

Additional keyword arguments are passed to the requests.Request object.

Parameters:

endpoint (str) – the PCE endpoint to call.

Returns:

the Response object returned from a successful request.

Return type:

requests.Response

post(endpoint, **kwargs)

Makes a POST call to a given PCE endpoint.

Appends ‘Content-Type: application/json’ to the request headers by default. Additional keyword arguments are passed to the requests.Request object.

Parameters:

endpoint (str) – the PCE endpoint to call.

Returns:

the Response object returned from a successful request.

Return type:

requests.Response

put(endpoint, **kwargs)

Makes a PUT call to a given PCE endpoint.

Appends ‘Content-Type: application/json’ to the request headers by default. Additional keyword arguments are passed to the requests.Request object.

Parameters:

endpoint (str) – the PCE endpoint to call.

Returns:

the Response object returned from a successful request.

Return type:

requests.Response

delete(endpoint, **kwargs)

Makes a DELETE call to a given PCE endpoint.

Additional keyword arguments are passed to the requests.Request object.

Parameters:

endpoint (str) – the PCE endpoint to call.

Returns:

the Response object returned from a successful request.

Return type:

requests.Response

get_collection(endpoint, **kwargs)

Uses the PCE’s asynchronous job logic to retrieve a collection of objects.

NOTE: for large collections (surpassing 10,000 objects), this function will be extremely slow - it is recommended that callers use query filters or the max_results parameter to limit the number of results in the collection.

Parameters:

endpoint (str) – the PCE endpoint to call.

Raises:

IllumioApiException – if an error message (>399) status code is returned.

Returns:

the Response object returned from a successful request.

Return type:

requests.Response

must_connect(**kwargs)

Checks the connection to the PCE.

Additional keyword arguments are passed to the requests call.

Raises:

IllumioApiException – if the connection fails.

Return type:

None

check_connection(**kwargs)

Checks the connection to the PCE.

Additional keyword arguments are passed to the requests call.

Returns:

True if the call is successful, otherwise False.

Return type:

bool

get_default_ip_list(**kwargs)

Retrieves the “Any (0.0.0.0/0 and ::/0)” default global IP list.

Returns:

decoded object representing the default global IP list.

Return type:

IPList

get_default_service(**kwargs)

Retrieves the “All Services” default global Service.

Returns:

decoded object representing the default global Service.

Return type:

Service

generate_pairing_key(pairing_profile_href, **kwargs)

Generates a pairing key using a pairing profile.

Parameters:

pairing_profile_href (str) – the HREF of the pairing profile to use.

Returns:

the pairing key value.

Return type:

str

get_traffic_flows(traffic_query, **kwargs)

DEPRECATED (v1.0.0). Use get_traffic_flows_async instead.

Retrieves Explorer traffic flows using the provided query.

NOTE: this function is deprecated in the Illumio REST API, and is only provided for compatibility. The Illumio Explorer REST API documentation recommends using the async traffic flow query instead, provided here as PolicyComputeEngine.get_traffic_flows_async.

See https://docs.illumio.com/core/21.5/Content/Guides/rest-api/visualization/explorer.htm#TrafficAnalysisQueries for details on traffic query parameters.

Parameters:

traffic_query (TrafficQuery) – TrafficQuery object representing the query parameters.

Returns:

list of TrafficFlow objects found using the

provided query.

Return type:

List[TrafficFlow]

get_traffic_flows_async(query_name, traffic_query, **kwargs)

Retrieves Explorer traffic flows using the provided query.

See https://docs.illumio.com/core/21.5/Content/Guides/rest-api/visualization/explorer.htm#AsynchronousQueriesforTrafficFlows for details on async traffic query parameters.

Usage:

>>> traffic_query = TrafficQuery.build(
...     start_date="2022-02-01T00:00:00Z",
...     end_date="2022-03-01T00:00:00Z",
...     include_services=[
...         {'port': 3389, 'proto': 'tcp'}
...     ],
...     policy_decisions=['potentially_blocked', 'unknown']
... )
>>> traffic_query
TrafficQuery(
    start_date='2022-02-01T00:00:00Z',
    end_date='2022-03-01T00:00:00Z',
    sources=TrafficQueryFilterBlock(
        include=[],
        exclude=[]
    ),
    destinations=TrafficQueryFilterBlock(
        include=[],
        exclude=[]
    ),
    services=TrafficQueryServiceBlock(
        include=[
            ServicePort(
                port=3389,
                proto=6,
                ...
            )
        ],
        exclude=[]
    ),
    policy_decisions=[
        'potentially_blocked',
        'unknown'
    ],
    ...
)
>>> traffic_flows = pce.get_traffic_flows_async(
...     query_name='rdp-traffic-feb-22',
...     traffic_query=traffic_query
... )
>>> traffic_flows
[
    TrafficFlow(
        src=TrafficNode(
            ip='10.0.9.14',
            "ip_lists": [
                {
                    "name": "IPL-INTERNAL",
                    "href": "/orgs/1/sec_policy/active/ip_lists/5",
                    ...
                }
            ],
            ...
        ),
        dst=TrafficNode(
            ip='10.0.6.63',
            workload=Workload(
                href='/orgs/1/workloads/6567900a-b49f-43cc-93a7-c892da39aad1',
                name='WIN-JUMPBOX',
                ...
            ),
            ...
        ),
        service=ServicePort(port=3389, proto=6),
        num_connections=44,
        state='closed',
        timestamp_range=TimestampRange(
            first_detected='2022-02-19T09:50:17Z',
            last_detected='2022-02-19T10:12:36Z'
        ),
        policy_decision='potentially_blocked',
        flow_direction='inbound',
        ...
    ),
    ...
]

Parameters:

• query_name (str) – name for the async query job.

• traffic_query (TrafficQuery) – TrafficQuery object representing the query parameters.

Raises:

IllumioApiException – if there is an error retrieving the async job results.

Returns:

list of TrafficFlow objects found using the

provided query.

Return type:

List[TrafficFlow]

provision_policy_changes(change_description, hrefs, **kwargs)

Provisions policy changes for draft objects with the given HREFs.

Usage:

>>> rule_set = pce.rule_sets.create(
...     RuleSet(name='RS-RINGFENCE')
... )
>>> changeset = pce.provision_policy_changes(
...     change_description='Provision ring-fence rule set',
...     hrefs=[rule_set.href]
... )
>>> changeset
PolicyVersion(
    href='/orgs/1/sec_policy/110',
    commit_message='Provision ring-fence rule set',
    version=110,
    workloads_affected=0,
    object_counts=PolicyObjectCounts(
        label_groups=17,
        services=8,
        ...
    )
)

Parameters:

• change_description (str) – the policy change description.

• hrefs (List[str]) – the HREFs of the draft policy objects to provision.

Raises:

IllumioException – if an invalid HREF is provided.

Returns:

the decoded policy version object including the changeset.

Return type:

PolicyVersion

get_pending_policy_changes(**kwargs)

Retrieves pending (unprovisioned) policy changes.

Returns:

list of pending policy change objects.

Return type:

list

discard_pending_policy_changes(**kwargs)

Discards all pending (unprovisioned) policy changes.

Return type:

None

get_policy_dependencies(hrefs, policy_version='draft', **kwargs)

Gets dependencies for the given policy object HREFs.

Parameters:

• hrefs (List[str]) – list of HREFs to check dependencies for.

• policy_version (str) – ‘draft’ or ‘active’.

Returns:

dependency objects.

Return type:

list

get_modified_policy_objects(policy_version='draft', **kwargs)

Gets policy objects modified since last provisioning.

Parameters:

policy_version (str) – ‘draft’ or ‘active’.

Returns:

modified object records.

Return type:

list

check_policy(policy_version='draft', **kwargs)

Runs a policy check on the given policy version.

Parameters:

policy_version (str) – ‘draft’ or ‘active’.

Returns:

policy check result.

Return type:

PolicyCheck

get_policy_allow(policy_version='active', **kwargs)

Gets the allowed policy for the given version.

Parameters:

policy_version (str) – ‘draft’ or ‘active’.

Returns:

allowed policy data.

Return type:

dict

analyze_policy_impact(hrefs, **kwargs)

Analyzes the impact of provisioning the given policy objects.

Parameters:

hrefs (List[str]) – HREFs of policy objects to analyze.

Returns:

impact analysis result.

Return type:

dict

restore_policy(policy_version='draft', **kwargs)

Restores the given policy version.

Parameters:

policy_version (str) – the policy version to restore.

Returns:

restore result.

Return type:

dict

bulk_delete_policy_objects(hrefs, **kwargs)

Bulk deletes security policy objects.

Parameters:

hrefs (List[str]) – HREFs of policy objects to delete.

Return type:

None

search_rules(query, policy_version='draft', **kwargs)

Searches for rules matching the given query.

Parameters:

• query (dict) – search criteria.

• policy_version (str) – ‘draft’ or ‘active’.

Returns:

matching rule objects.

Return type:

list

create_service_account_api_key(sa_href, **kwargs)

Creates an API key for a service account.

Parameters:

sa_href (str) – HREF of the service account.

Returns:

created API key data including key_id and secret.

Return type:

dict

delete_service_account_api_key(sa_href, key_id, **kwargs)

Deletes an API key for a service account.

Parameters:

• sa_href (str) – HREF of the service account.

• key_id (str) – ID of the API key to delete.

Return type:

None

get_user_api_keys(user_id, **kwargs)

Gets API keys for a user.

Parameters:

user_id (str) – user ID.

Returns:

API key objects.

Return type:

list

create_user_api_key(user_id, **kwargs)

Creates an API key for a user.

Parameters:

user_id (str) – user ID.

Returns:

created API key data.

Return type:

dict

delete_user_api_key(user_id, key_id, **kwargs)

Deletes an API key for a user.

Parameters:

• user_id (str) – user ID.

• key_id (str) – API key ID.

Return type:

None

get_org_api_keys(**kwargs)

Gets all API keys in the organization.

Returns:

API key objects.

Return type:

list

delete_org_api_key(key_id, **kwargs)

Deletes an API key in the organization.

Parameters:

key_id (str) – API key ID.

Return type:

None

verify_ldap_connection(ldap_href, **kwargs)

Verifies connectivity to an LDAP server.

Parameters:

ldap_href (str) – HREF of the LDAP config.

Returns:

verification result.

Return type:

dict

login_user(username, password, **kwargs)

Authenticates a user.

Parameters:

• username (str) – login username.

• password (str) – login password.

Returns:

authentication result with session token.

Return type:

dict

request_enforcement_instructions(device_href, **kwargs)

Requests enforcement instructions for a network device.

Parameters:

device_href (str) – HREF of the network device.

Returns:

enforcement instructions.

Return type:

dict

apply_enforcement_instructions(device_href, data, **kwargs)

Reports applied enforcement instructions for a network device.

Parameters:

• device_href (str) – HREF of the network device.

• data (dict) – applied enforcement data.

Returns:

response data.

Return type:

dict

multi_enforcement_instructions_request(data, **kwargs)

Requests enforcement instructions for multiple network devices.

Parameters:

data (dict) – request data.

Returns:

enforcement instructions.

Return type:

dict

multi_enforcement_instructions_applied(data, **kwargs)

Reports applied enforcement instructions for multiple network devices.

Parameters:

data (dict) – applied enforcement data.

Returns:

response data.

Return type:

dict

get_container_service_backends(cluster_href, **kwargs)

Gets service backends for a container cluster.

Parameters:

cluster_href (str) – HREF of the container cluster.

Returns:

service backend objects.

Return type:

list

download_report(report_href, **kwargs)

Downloads a completed report.

Parameters:

report_href (str) – HREF of the report.

Returns:

report file content.

Return type:

bytes

get_risk_summary(**kwargs)

Gets the risk summary report.

Returns:

risk summary data.

Return type:

dict

get_detected_core_services_summary(**kwargs)

Gets a summary of detected core services.

Returns:

core services summary.

Return type:

dict

unpair_vens(ven_hrefs, firewall_restore='default', **kwargs)

Unpairs VENs from the PCE.

Parameters:

• ven_hrefs (List[str]) – HREFs of VENs to unpair.

• firewall_restore (str) – firewall restore mode.

Returns:

unpair results.

Return type:

list

upgrade_vens(ven_hrefs, release, **kwargs)

Upgrades VENs to the specified release.

Parameters:

• ven_hrefs (List[str]) – HREFs of VENs to upgrade.

• release (str) – target release version.

Returns:

upgrade results.

Return type:

list

ven_remote_action(ven_hrefs, action, **kwargs)

Performs a remote action on VENs.

Parameters:

• ven_hrefs (List[str]) – HREFs of VENs to act on.

• action (str) – the remote action to perform.

Returns:

action results.

Return type:

list

ven_auth_recovery(ven_hrefs, **kwargs)

Initiates authentication recovery for VENs.

Parameters:

ven_hrefs (List[str]) – HREFs of VENs.

Returns:

recovery results.

Return type:

list

get_ven_statistics(ven_hrefs, **kwargs)

Gets statistics for VENs.

Parameters:

ven_hrefs (List[str]) – HREFs of VENs.

Returns:

VEN statistics.

Return type:

dict

get_workload_interfaces(workload_href, **kwargs)

Gets network interfaces for a workload.

Parameters:

workload_href (str) – HREF of the workload.

Returns:

interface objects.

Return type:

list

create_workload_interface(workload_href, interface, **kwargs)

Creates a network interface on a workload.

Parameters:

• workload_href (str) – HREF of the workload.

• interface (Any) – interface data.

Returns:

created interface.

Return type:

dict

delete_workload_interface(workload_href, iface_name, **kwargs)

Deletes a network interface from a workload.

Parameters:

• workload_href (str) – HREF of the workload.

• iface_name (str) – name of the interface.

Return type:

None

get_workload_risk_details(workload_href, **kwargs)

Gets risk details for a workload.

Parameters:

workload_href (str) – HREF of the workload.

Returns:

risk detail data.

Return type:

dict

unpair_workloads(workload_hrefs, firewall_restore='default', **kwargs)

Unpairs workloads from the PCE.

Parameters:

• workload_hrefs (List[str]) – HREFs of workloads to unpair.

• firewall_restore (str) – firewall restore mode.

Returns:

unpair results.

Return type:

list

bulk_import_workloads(data, **kwargs)

Bulk imports workloads.

Parameters:

data (list) – list of workload data to import.

Returns:

import results.

Return type:

list

get_label_group_all_labels(lg_href, **kwargs)

Gets all labels (recursively) in a label group.

Parameters:

lg_href (str) – HREF of the label group.

Returns:

label objects.

Return type:

list

get_label_group_member_of(lg_href, **kwargs)

Gets label groups that contain the given label group.

Parameters:

lg_href (str) – HREF of the label group.

Returns:

parent label group references.

Return type:

list

reorder_label_mapping_rule(rule_href, position, **kwargs)

Reorders a label mapping rule.

Parameters:

• rule_href (str) – HREF of the rule.

• position (int) – new position in the ordering.

Return type:

None

bulk_delete_label_mapping_rules(hrefs, **kwargs)

Bulk deletes label mapping rules.

Parameters:

hrefs (List[str]) – HREFs of rules to delete.

Return type:

None

bulk_update_label_mapping_rules(rules, **kwargs)

Bulk updates label mapping rules.

Parameters:

rules (list) – list of rule update objects.

Returns:

update results.

Return type:

list

run_label_mapping_rules(data, **kwargs)

Runs label mapping rules.

Parameters:

data (dict) – run parameters.

Returns:

job information.

Return type:

dict

get_label_mapping_job(job_uuid, **kwargs)

Gets the status of a label mapping job.

Parameters:

job_uuid (str) – UUID of the job.

Returns:

job status.

Return type:

dict

assign_label_mapping_labels(job_uuid, data, **kwargs)

Assigns labels from a completed label mapping job.

Parameters:

• job_uuid (str) – UUID of the completed job.

• data (dict) – assignment data.

Return type:

None

download_label_mapping_results(job_uuid, **kwargs)

Downloads label mapping results.

Parameters:

job_uuid (str) – UUID of the completed job.

Returns:

result file content.

Return type:

bytes

get_product_version(**kwargs)

Gets the PCE product version.

Returns:

product version information.

Return type:

dict

get_node_available(**kwargs)

Checks if the PCE node is available.

Returns:

node availability status.

Return type:

dict

get_supercluster_leader(**kwargs)

Gets the supercluster leader node.

Returns:

leader node information.

Return type:

dict

get_app_group_risk_summary(**kwargs)

Gets the app group risk summary.

Returns:

app group risk summary data.

Return type:

dict

get_app_group_risk_details(app_group_id, **kwargs)

Gets risk details for an app group.

Parameters:

app_group_id (str) – app group ID.

Returns:

risk detail data.

Return type:

dict

get_traffic_flow_db_metrics(**kwargs)

Gets traffic flow database metrics.

Returns:

database metrics.

Return type:

dict

get_async_queries(**kwargs)

Gets all async traffic flow queries.

Returns:

async query objects.

Return type:

list

delete_async_query(uuid, **kwargs)

Deletes an async traffic flow query.

Parameters:

uuid (str) – UUID of the query.

Return type:

None

download_async_query(uuid, **kwargs)

Downloads results of an async traffic flow query.

Parameters:

uuid (str) – UUID of the query.

Returns:

query result content.

Return type:

bytes

update_async_query_rules(uuid, data, **kwargs)

Updates rules for an async traffic flow query.

Parameters:

• uuid (str) – UUID of the query.

• data (dict) – rule update data.

Return type:

None

get_ven_software_releases(**kwargs)

Gets available VEN software releases.

Returns:

VEN release objects.

Return type:

list

get_ven_software_release(release, **kwargs)

Gets a specific VEN software release.

Parameters:

release (str) – release version string.

Returns:

release details.

Return type:

dict

delete_ven_software_release(release, **kwargs)

Deletes a VEN software release.

Parameters:

release (str) – release version string.

Return type:

None

set_default_ven_release(release, **kwargs)

Sets the default VEN software release.

Parameters:

release (str) – release version string.

Return type:

None

get_ven_release_images(release, **kwargs)

Gets images for a VEN software release.

Parameters:

release (str) – release version string.

Returns:

image objects.

Return type:

list

PCE Object API

This internal class is used to represent API objects within the PCE, and provides a common CRUD interface for them.

class PolicyComputeEngine._PCEObjectAPI

Generic API for registered PCE objects.

Each registered API exposes CRUD operation functions through this common interface.

get_by_reference(reference, **kwargs)

Retrieves an object from the PCE using its HREF.

Usage:

>>> ip_list = pce.ip_lists.get_by_reference('/orgs/1/sec_policy/active/ip_lists/1')
>>> ip_list
IPList(
    name='Any (0.0.0.0/0 and ::/0)',
    ...
)

Parameters:

• href (str) – the HREF of the object to fetch.

• reference (str | Reference | dict)

Returns:

the object json, decoded to its python equivalent.

Return type:

Reference

get_by_name(name, policy_version='draft', **kwargs)

Retrieves the object from the PCE with the given name.

Parameters:

• name (str) – the exact name of the object to retrieve.

• policy_version (str)

Returns:

the decoded object, or None if an object with the

given name wasn’t found.

Return type:

Reference

get(policy_version='draft', parent=None, **kwargs)

Retrieves objects from the PCE based on the given parameters.

Keyword arguments to this function are passed to the requests.get call. See https://docs.illumio.com/core/21.5/API-Reference/index.html for details on filter parameters for collection queries.

Usage:

>>> virtual_services = pce.virtual_services.get(
...     policy_version='active',
...     params={
...         'name': 'VS-'
...     }
... )
>>> virtual_services
[
    VirtualService(
        href='/orgs/1/sec_policy/active/virtual_services/9177c75f-7b21-4bf0-8c16-2c47c1ca3252',
        name='VS-LAB-SERVICES'
        ...
    ),
    ...
]

Parameters:

• policy_version (str, optional) – if fetching security policy objects, specifies whether to fetch ‘draft’ or ‘active’ objects. Defaults to ‘draft’.

• parent (Union[str, Reference, dict], optional) – Reference to the object’s parent. Required for some object types, such as Security Rules which must be created as children of existing RuleSets.

Returns:

the returned list of decoded objects.

Return type:

List[Reference]

get_all(policy_version='draft', parent=None, **kwargs)

Retrieves all objects of a given type from the PCE.

This function makes two requests, using the X-Total-Count header in the response to set the max_results parameter on the follow-up request.

Parameters:

• policy_version (str, optional) – if fetching security policy objects, specifies whether to fetch ‘draft’ or ‘active’ objects. Defaults to ‘draft’.

• parent (Union[str, Reference, dict], optional) – Reference to the object’s parent. Required for some object types, such as Security Rules which must be created as children of existing RuleSets.

Returns:

the returned list of decoded objects.

Return type:

List[Reference]

get_async(policy_version='draft', parent=None, **kwargs)

Retrieves objects asynchronously from the PCE based on the given parameters.

Parameters:

• policy_version (str, optional) – if fetching security policy objects, specifies whether to fetch ‘draft’ or ‘active’ objects. Defaults to ‘draft’.

• parent (Union[str, Reference, dict], optional) – Reference to the object’s parent. Required for some object types, such as Security Rules which must be created as children of existing Rule Sets.

Returns:

the returned list of decoded objects.

Return type:

List[Reference]

create(body, parent=None, **kwargs)

Creates an object in the PCE.

See https://docs.illumio.com/core/21.5/API-Reference/index.html for details on POST body parameters when creating objects.

Usage:

>>> from illumio.policyobjects import Label
>>> label = Label(key='role', value='R-DB')
>>> label = pce.labels.create(label)
>>> label
Label(
    'href': '/orgs/1/labels/14',
    'key': 'role',
    'value': 'R-DB
)

Parameters:

• body (Any) – the parameters for the newly created object.

• parent (Union[str, Reference, dict], optional) – Reference to the object’s parent. Required for some object types, such as Security Rules which must be created as children of existing RuleSets.

Returns:

the created object.

Return type:

Reference

update(reference, body, **kwargs)

Updates an object in the PCE.

Successful PUT requests return a 204 No Content response.

Usage:

>>> pairing_profiles = pce.pairing_profile.get_by_name('PP-Database')
>>> existing_profile = pairing_profiles[0]
>>> update = PairingProfile(
...     name='PP-DATABASE-VENS',
...     enabled=False  # disable this profile
... )
>>> pce.pairing_profile.update(existing_profile['href'], update)

Parameters:

• reference (Union[str, Reference, dict]) – the HREF of the pairing profile to update.

• body (Any) – the update data.

Return type:

None

delete(reference, **kwargs)

Deletes an object in the PCE.

Successful DELETE requests return a 204 No Content response.

Parameters:

reference (Union[str, Reference, dict]) – the HREF of the object to delete.

Return type:

None

bulk_create(objects_to_create, **kwargs)

Creates a set of objects in the PCE.

NOTE: Bulk creation can currently only be applied for Security Principals,

Virtual Services and Workloads.

Parameters:

objects_to_create (List[Reference]) – list of objects to update.

Returns:

a list containing HREFs of created objects

as well as any errors returned from the PCE. Has the following form:

>>> [
...     {
...         'href': {object_href},
...         'errors': [
...             {
...                 'token': {error_type},
...                 'message': {error_message}
...             }
...         ]
...     }
... ]

Return type:

List[dict]

bulk_update(objects_to_update, **kwargs)

Updates a set of objects in the PCE.

NOTE: Bulk updates can currently only be applied for Virtual Services and Workloads.

Parameters:

objects_to_update (List[Reference]) – list of objects to update.

Returns:

a list containing HREFs of updated objects

as well as any errors returned from the PCE. Has the following form:

>>> [
...     {
...         'href': {object_href},
...         'errors': [
...             {
...                 'token': {error_type},
...                 'message': {error_message}
...             }
...         ]
...     }
... ]

Return type:

List[dict]

bulk_delete(refs, **kwargs)

Deletes a set of objects in the PCE.

NOTE: Bulk updates can currently only be applied for Workloads.

Parameters:

refs (List[Union[str, Reference, dict]]) – list of references to objects to delete.

Returns:

a list containing any errors that occurred during

the bulk operation. Has the following form:

>>> [
...     {
...         'href': {object_href},
...         'errors': [
...             {
...                 'token': {error_type},
...                 'message': {error_message}
...             }
...         ]
...     }
... ]

Return type:

List[dict]

PolicyComputeEngine API Attributes

The PolicyComputeEngine class provides the following attributes:

access_restrictions
app_group_summary
auth_security_principals
authentication_settings
container_clusters
container_workload_profiles
core_service_types
deny_rules
detected_core_services
discovered_virtual_servers
enforcement_boundaries
event_settings
events
firewall_settings
ip_lists
jobs
kubernetes_workloads
label_dimensions
label_groups
label_mapping_rules
labels
ldap_configs
network_devices
network_endpoints
network_enforcement_nodes
optional_features
org_settings
pairing_profiles
password_policy
permissions
report_schedules
report_settings
report_templates
reports
roles
rule_sets
rules
saml_configs
security_principals
service_accounts
service_bindings
services
slbs
support_bundle_requests
syslog_destinations
system_events
traffic_collector_settings
trusted_proxy_ips
users
vens
virtual_servers
virtual_services
vulnerabilities
vulnerability_reports
workload_settings
workloads

Each represents a corresponding PCE API endpoint, implemented as a _PCEObjectAPI instance.

Exceptions

The library uses two exception types to capture errors returned from the API or encountered in other library functions.

exception illumio.IllumioException

Superclass for Illumio library exceptions.

exception illumio.IllumioApiException

Superclass for exceptions generated by the Illumio API code.

exception illumio.IllumioIntegerValidationException

Raised when invalid integer values are provided.