Utilities¶

Contains global constants, helper functions, and internal structures.

Constants¶

illumio.util.constants.ACTIVE = 'active'¶: Active policy version path literal.

illumio.util.constants.DRAFT = 'draft'¶: Draft policy version path literal.

illumio.util.constants.AMS = 'ams'¶: Used in rules and enforcement boundaries to denote that all workloads should be affected.

illumio.util.constants.RESOLVE_AS_WORKLOADS = 'workloads'¶: Used in resolve_labels_as block in rule creation to denote that workloads matching the rule scope should be affected.

illumio.util.constants.RESOLVE_AS_VIRTUAL_SERVICES = 'virtual_services'¶: Used in resolve_labels_as block in rule creation to denote that virtual services matching the rule scope should be affected.

illumio.util.constants.ANY_IP_LIST_NAME = 'Any (0.0.0.0/0 and ::/0)'¶: Name of the default global IP list.

illumio.util.constants.ALL_SERVICES_NAME = 'All Services'¶: Name of the default global Service.

illumio.util.constants.PORT_MAX = 65535¶: Max port number.

illumio.util.constants.ICMP_CODE_MAX = 15¶: Max value for the ICMP header Code field. See https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml#icmp-parameters-codes

illumio.util.constants.ICMP_TYPE_MAX = 255¶: Max value for the ICMP header Type field. See https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml#icmp-parameters-types

illumio.util.constants.BULK_CHANGE_LIMIT = 1000¶: Upper limit on the number of objects that can be sent to PCE bulk change endpoints in a single request.

enum illumio.util.constants.EnforcementMode(value)[source]¶

Workload enforcement mode enumeration.

Member Type:: str

Valid values are as follows:

IDLE = <EnforcementMode.IDLE: 'idle'>¶

VISIBILITY_ONLY = <EnforcementMode.VISIBILITY_ONLY: 'visibility_only'>¶

FULL = <EnforcementMode.FULL: 'full'>¶

SELECTIVE = <EnforcementMode.SELECTIVE: 'selective'>¶

enum illumio.util.constants.LinkState(value)[source]¶

Network interface link state enumeration.

Member Type:: str

Valid values are as follows:

UP = <LinkState.UP: 'up'>¶

DOWN = <LinkState.DOWN: 'down'>¶

UNKNOWN = <LinkState.UNKNOWN: 'unknown'>¶

enum illumio.util.constants.VisibilityLevel(value)[source]¶

Workload visibility level enumeration.

Member Type:: str

Valid values are as follows:

FLOW_FULL_DETAIL = <VisibilityLevel.FLOW_FULL_DETAIL: 'flow_full_detail'>¶

FLOW_SUMMARY = <VisibilityLevel.FLOW_SUMMARY: 'flow_summary'>¶

FLOW_DROPS = <VisibilityLevel.FLOW_DROPS: 'flow_drops'>¶

FLOW_OFF = <VisibilityLevel.FLOW_OFF: 'flow_off'>¶

ENHANCED_DATA_COLLECTION = <VisibilityLevel.ENHANCED_DATA_COLLECTION: 'enhanced_data_collection'>¶

enum illumio.util.constants.Transmission(value)[source]¶

Traffic flow transmission enumeration.

Member Type:: str

Valid values are as follows:

BROADCAST = <Transmission.BROADCAST: 'broadcast'>¶

MULTICAST = <Transmission.MULTICAST: 'multicast'>¶

UNICAST = <Transmission.UNICAST: 'unicast'>¶

enum illumio.util.constants.FlowDirection(value)[source]¶

Traffic flow direction enumeration.

Member Type:: str

Valid values are as follows:

INBOUND = <FlowDirection.INBOUND: 'inbound'>¶

OUTBOUND = <FlowDirection.OUTBOUND: 'outbound'>¶

enum illumio.util.constants.TrafficState(value)[source]¶

Traffic flow state enumeration.

Member Type:: str

Valid values are as follows:

ACTIVE = <TrafficState.ACTIVE: 'active'>¶

CLOSED = <TrafficState.CLOSED: 'closed'>¶

TIMED_OUT = <TrafficState.TIMED_OUT: 'timed out'>¶

SNAPSHOT = <TrafficState.SNAPSHOT: 'snapshot'>¶

NEW = <TrafficState.NEW: 'new'>¶

UNKNOWN = <TrafficState.UNKNOWN: 'unknown'>¶

INCOMPLETE = <TrafficState.INCOMPLETE: 'incomplete'>¶

enum illumio.util.constants.ApplyTo(value)[source]¶

Virtual service apply to value enumeration.

Member Type:: str

Valid values are as follows:

HOST_ONLY = <ApplyTo.HOST_ONLY: 'host_only'>¶

INTERNAL_BRIDGE_NETWORK = <ApplyTo.INTERNAL_BRIDGE_NETWORK: 'internal_bridge_network'>¶

enum illumio.util.constants.VENType(value)[source]¶

VEN type enumeration.

Member Type:: str

Valid values are as follows:

SERVER = <VENType.SERVER: 'server'>¶

ENDPOINT = <VENType.ENDPOINT: 'endpoint'>¶

CONTAINERIZED = <VENType.CONTAINERIZED: 'containerized'>¶

enum illumio.util.constants.ChangeType(value)[source]¶

Resource event change type enumeration.

Member Type:: str

Valid values are as follows:

CREATE = <ChangeType.CREATE: 'create'>¶

UPDATE = <ChangeType.UPDATE: 'update'>¶

DELETE = <ChangeType.DELETE: 'delete'>¶

enum illumio.util.constants.EventSeverity(value)[source]¶

Event severity enumeration.

Member Type:: str

Valid values are as follows:

EMERGENCY = <EventSeverity.EMERGENCY: 'emerg'>¶

ALERT = <EventSeverity.ALERT: 'alert'>¶

CRITICAL = <EventSeverity.CRITICAL: 'crit'>¶

ERROR = <EventSeverity.ERROR: 'err'>¶

WARNING = <EventSeverity.WARNING: 'warning'>¶

NOTICE = <EventSeverity.NOTICE: 'notice'>¶

INFO = <EventSeverity.INFO: 'info'>¶

DEBUG = <EventSeverity.DEBUG: 'debug'>¶

enum illumio.util.constants.EventStatus(value)[source]¶

Event status enumeration.

Member Type:: str

Valid values are as follows:

SUCCESS = <EventStatus.SUCCESS: 'success'>¶

FAILURE = <EventStatus.FAILURE: 'failure'>¶

Helper Functions¶

illumio.util.functions.convert_active_href_to_draft(href)[source]¶

Given an HREF string, converts policy version to draft.

If a draft HREF is provided, this function has no effect.

Parameters:: href (str) – PCE object HREF.
Returns:: draft policy version HREF.
Return type:: str

illumio.util.functions.convert_draft_href_to_active(href)[source]¶

Given an HREF string, converts policy version to active.

If an active HREF is provided, this function has no effect.

Parameters:: href (str) – PCE object HREF.
Returns:: active policy version HREF.
Return type:: str

illumio.util.functions.convert_protocol(protocol)[source]¶

Given a protocol name, returns the integer ID of that protocol.

Usage:

>>> convert_protocol('tcp')
6

Parameters:: protocol (str) – case-insensitive protocol string, e.g. ‘tcp’, ‘UDP’
Raises:: IllumioException – if an invalid protocol name is provided.
Returns:: the integer ID of the given protocol, e.g. 17 for ‘udp’
Return type:: int

illumio.util.functions.deprecated(deprecated_in, message=None)[source]¶: Deprecation decorator, adapted from https://stackoverflow.com/a/30253848 Will emit a warning when the decorated function is called.

illumio.util.functions.ignore_empty_keys(o)[source]¶

Removes keys with None-type values from the provided dict.

Used for JSON encoding to avoid schema errors due to empty or invalid parameters.

Parameters:: o (dict)

illumio.util.functions.parse_url(url)[source]¶

Parses given URL into its scheme and hostname, stripping port and path.

Parameters:: url (str) – URL to parse.
Returns:: parsed (scheme, hostname)
Return type:: tuple

illumio.util.functions.pce_api(name, endpoint=None, is_sec_policy=False, is_global=False)[source]¶

Decorates an IllumioObject subclass to denote it as a PCE API object type.

This registers the type in the PCE_APIS mapping used to determine whether a given name corresponds to an API-accessible type.

We can then leverage __getattr__ to instantiate a generic API interface for any registered type (with some caveats, see the _PCEObjectAPI documentation).

By default, registers the endpoint as /{name}, but the endpoint can also be specified in the decorator function call.

For example:

@pce_api('labels', endpoint='/labels')
class Label(IllumioObject):
    ...

# the 'labels' name is registered, so we can call /labels
# endpoints through the _PCEObjectAPI interface
pce = PolicyComputeEngine(...)
labels = pce.labels.get()

Parameters:

name (str) – the name of the API, used as a PolicyComputeEngine attribute name to generate the API interface.
endpoint (str, optional) – the endpoint path. Defaults to /{name}.
is_sec_policy (bool, optional) – whether the object reflects a security policy API with the sec_policy/{pversion} prefix. Defaults to False.
is_global (bool, optional) – whether the object reflects a global API, such as /health or /users. These APIs operate on the entire PCE rather than a single tenant, and don’t need the /orgs/{org_id} prefix. Defaults to False.

illumio.util.jsonutils.href_from(reference)[source]¶

Attempts to parse HREF value from a provided source.

Parameters:: reference (Union[Reference, dict, str]) – source reference. If a string value is passed, it is returned unchanged. The href field is returned from a Reference object or subclass instance, and the 'href' key is returned from a provided dictionary.
Raises:: IllumioException – if an invalid reference type is provided, or if the href value is null or falsy.

Base Classes¶

class illumio.util.jsonutils.JsonObject[source]¶

Base dataclass for all derived PCE objects.

Provides custom encoding, decoding, and type validation to and from JSON.

class illumio.util.jsonutils.IllumioObject[source]¶

Base class for most PCE objects.

Parameters:

name (str, optional) – object name.
description (str, optional) – object description.
external_data_set (str, optional) – unique namespace identifier for an external source creating PCE objects. If set, external_data_reference must also be provided.
external_data_reference (str, optional) – unique identifier within the external_data_set. If set, external_data_set must also be provided. external_data_set + external_data_reference must be globally unique.
caps (List[str], optional) – defines the requesting user’s capabilities/permissions on the object.

class illumio.util.jsonutils.Reference[source]¶

Simplest PCE object type, containing only an HREF.

Used in most API schema to refer to other PCE objects.

Parameters:: href (str, optional) – PCE object HREF.