Skip to main content

REST APIs for 23.5

Container Clusters

The Illumio Core uses three groups of APIs to manage container clusters:

  • Container Cluster API (GET, POST, PUT, DELETE)

  • Container Cluster Workload Profiles API (GET, POST, PUT, DELETE)

  • Container Cluster Service Backend API (GET)

Container Cluster API

A container cluster object is used to store all the information about a Kubernetes cluster in the PCE by collecting telemetry from Kubelink. Each Kubernetes cluster maps to one container cluster object in the PCE.

Use these methods to get, create, update, or delete container clusters:

Functionality

HTTP

URI

Get the list of container clusters

GET

[api_version][org_href]/container_clusters

Get the specified container cluster

GET

[api_version][org_href]/container_clusters/:uuid

Create a container cluster

POST

[api_version][org_href]/container_clusters

Update the specified container cluster

PUT

[api_version][org_href]/container_clusters/:uuid

Delete the specified container cluster

DELETE

[api_version][org_href]/container_clusters/:uuid

Query Parameters for the GET Method

Use the following required and optional parameters:

Parameter

Description

Type

Required

href

URI of the container cluster.

String

Yes

name

User assigned name of the container cluster.

String

Yes

description

User-assigned description of the container cluster.

String

Yes

nodes

Array

No

machine_id

This parameter has the following property:

  • pod_subnet: The pod subnet

Object

String

Yes

manager_type

Manager of the container cluster (and version).

String

No

network_type

Type of network.

String

No

last_connected

Date-time format.

String

No

online

Online: true/false.

Boolean

No

errors

The object error_type has the following properties:

  • audit_event:

    • href

  • duplicate_ids

  • error_type

Array

Object

String

Array

String

String

No

kubelink_version

Kubelink software version.

String

No

pce_fqdn

PCE FQDN for this container cluster; used only in Supercluster.

String

No

cluster_mode

The new property cluster_mode was added in 23.5.10 to describe the cluster mode for container cluster:

String

Query Parameters for the POST and PUT Methods

Use the following parameters:

Parameter

Description

Type

Required

name

User-assigned name of the cluster

String

Yes

description

User-assigned description of the cluster

String

No

Curl Examples and Responses

Curl Command for GET

curl --request GET --url https://pce.my-company.com:8443/api/v2/orgs/1/container_clusters --header 'authorization: Basic YXBpXzE2YjBkYjI0MjJhZGNkYWU5OjA5ZmRjNjA4MDhiMzExZTc2Y2UyNzNmOWNiN2ZhMTA5OTdkMWNlMDAzZmMzOTQ1ZGMxYzEwZGzlmZjM='

Example Response for GET

[
  {
   "href":"/orgs/1/container_clusters/445bfa9b-4de4-4c09-9705-496eb04b190f", 
	"pce_fqdn":null,
	"name":"k8s2",
	"description":"",
	"manager_type":"Kubernetes v1.16.2", 
	"last_connected":"2019-10-28T22:48:31.228Z",
	"kubelink_version":"2.0.0-master.96e58b", 
	"online":true,
	"nodes":
       [
        {
	  "name":"node1",
	  "pod_subnet":"10.233.64.0/24"
	   },
	  {
	   "name":"node2",
	  "pod_subnet":"10.233.65.0/24"
          },
	 {
	  "name":"node3",
	  "pod_subnet":"10.233.66.0/24"
	  }
       ], 
	"errors":[]
	  },
 {
   "href":"/orgs/1/container_clusters/ad678193-8e2f-402b-a864-4947dcc0c6d7", 
	"pce_fqdn":null,
	"name":"Openshift 3.11",
	"description":"",
	"manager_type":"Openshift v3.11.43", 
	"last_connected":"2019-10-28T22:50:30.201Z",
	"kubelink_version":"1.0.0-master.a81280", 
	"online":true,
	"nodes":
  	  [
 	   {
	    "name":"ip-172-31-19-198.us-west-2.compute.internal", 
	    "pod_subnet":"10.128.0.0/23"
	    },
	   {
	    "name":"ip-172-31-20-168.us-west-2.compute.internal", 
	    "pod_subnet":"10.131.0.0/23"
	    },
	   {
	    "name":"ip-172-31-22-56.us-west-2.compute.internal", 
	    "pod_subnet":"10.130.0.0/23"
	    },
	   {
	    "name":"ip-172-31-27-241.us-west-2.compute.internal", 
	    "pod_subnet":"10.129.0.0/23"
	    }
	],
	"errors":[]
	   },
  {
   "href": "/orgs/1/container_clusters/bef57e90-97d4-4744-a129-5d35aa12b21b", 
	"pce_fqdn":null,
	"name":"k8s3 Cluster",
	"description":"Flannel Vx Lan", 
	"manager_type":"Kubernetes v1.13.2",
	"last_connected":"2019-10-28T22:47:59.122Z", 
	"kubelink_version":"EYE-60264",
	"online":true,
	"nodes":
	 [
	   {
	    "name":"k8s3master", 
	    "pod_subnet":"10.244.0.0/24"
	    },
          {	
	    "name":"k8s3minion1",
	    "pod_subnet":"10.244.2.0/24"
	    }, 
	   {
	    "name":"k8s3minion2",
	    "pod_subnet":"10.244.1.0/24"
	    }
	],
	"errors":[]
	  },
  {
   "href":"/orgs/1/container_clusters/d7d62400-7650-4407-ae9b-71803dbb1324",
	"pce_fqdn":null,
	"name":"k8s1 v4",
	"description":"",
	"manager_type":"Kubernetes v1.12.4", 
	"last_connected":"2019-10-24T23:58:55.795Z",
	"kubelink_version":"EYE-61567",
	"online":false,
	"nodes":
	  [
	   {
	    "name":"k8s1master",
	    "pod_subnet":"10.244.0.0/24"
	     }, 
	   {
	    "name":"k8s1minion1",
	    "pod_subnet":"10.244.2.0/24"
	    },
	   {
	    "name":"k8s1minion2",
	    "pod_subnet":"10.244.1.0/24"
	    }
	    ],
	 "errors":[]
	}
]

Curl Example for POST

curl --request POST --url https://pce.my-company.com:8443/api/v2/orgs/1/container_clusters --header 'authorization: Basic jI0MjJhZGNkYWU5OjA5ZmRjNjA4MDhiMzExZTc2Y2UyNzNmOWNiN2ZhMTA5OTdkMWNlMDAzZmMzOTQ1ZGMxYzEwZGJhZTg5NzlmZjM=' --header 'content-type: application/json' --data '{"name": "test","description": "test"}'

Curl Example for PUT

curl --request PUT --url https://pce.my-company.com:8443/api/v2/orgs/1/container_clusters/1b851d4b-f22d-47be-b744-f3c2dca490a0 --header 'authorization: Basic YXBpXzE2YjBkYjI0MjJhZGNkYWU5OjA5ZmRjNjA4MDhiMzExZTc2Y2UyNzNmOWNiN2ZhMTA5OTdkMWNlMDAzZmMzOTQ1ZGMxYzEwZGJhZTg5NzlmZjM=' --header 'content-type: application/json' --data '{"name": "test","description": "test"}'

Example Response for POST

{
	"href": "/orgs/1/container_clusters/1b851d4b-f22d-47be-b744-f3c2dca490a0",
		"pce_fqdn": null,
		"name": "test",
		"description": "test",
		"manager_type": null,
		"last_connected": null,
		"kubelink_version": null,
		"online": false,
		"nodes": [],
		"errors": [],
		"container_cluster_token": "1_0dfec0acb8e4bc53e052874874da0c24e7ac98da3b3954e3c9ea6f9860722e84"
}

Container Cluster Workload Profiles

When you install an Illumio VEN on a container cluster, all pods in the container cluster are unmanaged or not visible in the PCE. However, all namespaces that exist on the container clusters are reported by Kubelink and made visible via the Container Container Workload Profiles API.

Each container workload profile maps to a Kubernetes namespace and can be either managed or unmanaged. The default state for a profile is unmanaged.

Use these methods to get, create, update, or delete container cluster workload profiles:

Functionality

HTTP

URI

Get the list of container cluster workload profiles

GET

GET /orgs/:xorg_id/container_clusters/: container_cluster_id/container_workload_ profiles

Create container cluster workload profiles

POST

POST /orgs/:xorg_id/container_clusters/: container_cluster_id/container_workload_ profiles

Update the specified container cluster workload profile

PUT

PUT /orgs/:xorg_id/container_clusters/: container_cluster_id/container_workload_ profiles/:container_workload_profile_id

Supports the UI feature for bulk update of container workload profiles

PUT

PUT /orgs/:xorg_id/container_clusters/: container_cluster_id/container_workload_ profiles_update

Delete the specified container cluster workload profile

DELETE

DELETE /orgs/:xorg_id/container_clusters/: container_cluster_id/container_workload_ profiles/:container_workload_profile_id

Query Parameters for Container Workload Methods

Parameter

Description

Type

Required

org_id

Organization ID

Integer

Yes

container_cluster_id

Cluster UUID

String

Yes

assign_labels

(GET) List of lists of label URIs, encoded as a JSON string

(POST, PUT) Assigned labels

String

No

No

enforcement_mode

(GET) Filter by enforcement mode.

(PUT) workload enforcement mode

String

No

No

linked

Filter by linked container workload profiles.

Boolean

No

managed

Filter by managed state

Boolean

No

max_results

Maximum number of container workloads to return..

Integer

No

name

(GET) Name string to match. Supports partial matches.

(POST) A friendly name given to a profile if the namespace is not user friendly

String

No

YES

namespace

Namespace string to match. Supports partial matches.

String

No

visibility_level

Filter by visibility level

String

No

Response Properties for Container Workload Methods

Parameter

Description

Type

href

Container Workload Profile URI

String

enforcement_mode

Reference to common/workload_enforcement_mode.schema.json

managed

If the namespace is managed or not

Boolean

max_results

Maximum number of container workloads to return..

Integer

name

A friendly name given to a profile if the namespace is not user friendly

String, Null

namespace

Namespace name

String, Null

container_workload_profile_id

Container workload profile UUID

String

labels

Labels to assign to the workload that matches the namespace.

Reference to common/label_restrictions.schema.json

Curl Examples and Responses

Curl example for GET

curl --request GET --url https://pce.my-company.com:8443/api/v2/orgs/1/containermeters iun one table and verified with the Quick Reference._clusters/445bfa9b-4de4-4c09-9705-496eb04b190f/container_workload_profiles --header 'authorization: Basic NjA4MDhiMzExZTc2Y2UyNzNmOWNiN2ZhMTA5OTdkMWNlMDAzZmMzOTQ1ZGMxYzEwZGJhZTg5NzlmZjM=' --header 'content-type: application/json'

Curl Example for POST

curl --request POST --url https://pce.my-company.com:8443/api/v2/orgs/1/container_clusters/445bfa9b-4de4-4c09-9705-496eb04b190f/container_workload_profiles --header 'authorization: Basic A5ZmRjNjA4MDhiMzExZTc2Y2UyNzNmOWNiN2ZhMTA5OTdkMWNlMDAzZmMzOTQ1ZGMxYzEwZGJhZTg5NzlmZjM=' --header 'content-type: application/json' --data '{"name": "test","description": "test","assign_labels": [{"href": "/orgs/1/labels/1"}],"mode": "full","log_traffic": true}'

Curl Example for PUT

curl --request PUT --url https://pce.my-company.com:8443/api/v2/orgs/1/container_clusters/445bfa9b-4de4-4c09-9705-496eb04b190f/container_workload_profiles/219b49c3-3bb5-4fc0-9913-b76398105e35 --header 'authorization: Basic mRjNjA4MDhiMzExZTc2Y2UyNzNmOWNiN2ZhMTA5OTdkMWNlMDAzZmMzOTQ1ZGMxYzEwZGJhZTg5NzlmZjM=' --header 'content-type: application/json' --data '{"name": "test","description": "test","assign_labels": [{"href": "/orgs/1/labels/1"}],"mode": "full","log_traffic": true}'

Example Response for GET

[ 
    {
        "href": "/orgs/10/container_clusters/974aec34-e8e7-478d-9ca2-90ebb3642edc/container_workload_profiles/5454cc84-d6be-4e6c-ac62-465f9504fac0",
        "namespace": "openshift-host-network",
        "enforcement_mode": "visibility_only", 
        "visibility_level": "flow_summary",
        "managed": true, 
        "assign_labels": [
            {
                "href": "/orgs/10/labels/128"
            },
            {
                "href": "/orgs/10/labels/225"
            }
        ],
        "labels": [
            {
                "key": "loc",
                "assignment": {
                    "href": "/orgs/10/labels/128",
                     "value": "AWS"
                }
            },
            {
                "key": "env",
                "assignment": {    
                    "href": "/orgs/10/labels/225",
                    "value": "OCP4.6"
                }
        }
    ],
        "linked": true,   
        "created_at": "2021-08-25T18:11:52.665Z",
        "created_by": {
             "href": "/orgs/10/container_clusters/974aec34-e8e7-478d-9ca2-90ebb3642edc"
        },
        "updated_at": "2021-08-25T18:11:52.665Z",
        "updated_by": {
            "href": "/orgs/10/container_clusters/974aec34-e8e7-478d-9ca2-90ebb3642edc"
        }
    }

]
Examples for container_workload_profiles/update

Example Request

{
	"container_workload_profiles": [
	{
		"href": "url_to_some_container_workload_profile"
		},
		{
		"href": "url_to_other_container_workload_profile"
	}
	],
	"labels": [
	{
		"key": "role",
		"assignment": {
		"href": "url_to_label"
		}
	}
	],
	"enforcement_mode": 2,
		"visibility_level": "flow_summary",
		"managed": true
}

Example Response

  • For success: Response code 204; Response body: none

  • If an error occurred on any of the input records:

    • Response code 406;

    • Response body:

      [
	{
	"token": "input_validation_error",
	"message": "....., record_index=>1, ..., unmanaged_container_workload_profile_labels, ..." 
              # message contains index of failed record and specific error message
	}, 
	...
]

Label Restrictions

Kubernetes pods and services running in a namespace (Kubernetes) or project (OpenShift) must be labeled (RAEL) to be included in policy within Illumio Core. The container workload profile defines how labels will be assigned to pods and services within a namespace.

Illumio labels can be statically assigned from the PCE or defined in the Kubernetes manifest files using annotations. For each label key (RAEL), the PCE administrator can define four options:

  1. No label will be assigned.

  2. One label will be assigned from PCE.

  3. A restricted list of labels can be assigned from Kubernetes using annotations. Label restrictions prevent misuse of Illumio labels by the people managing the Kubernetes platform and makes sure the labels inherit the policy they should be receiving.

  4. Any label can be assigned from Kubernetes.

You can set role labels for the following APIs:

  • PUT /api/v2/orgs/:xorg_id/container_clusters/<:cluster_id>/container_workload_profiles

  • POST /api/v2/orgs/:xorg_id/container_clusters/<:cluster_id>/container_workload_profiles

Examples

Set an empty Role label

{	
	"labels": [
		{"key": "role", "assign": {} }
	]
}

Set a Location label

PUT /api/v2/orgs/1/container_clusters/65d1f197-938a-49ef-9343-6f55ec76fd90/container_workload_profiles/afe4661a-03ef-462f-ada6-ce7334aa9704

{
	"labels": [
		{ "key": "loc", "restriction": {"href": "/orgs/1/labels/221"} }
	]
}

Set an allow list for the Environment label

Allow a list of Environment labels to be assigned using Kubernetes:

PUT /api/v2/orgs/1/container_clusters/65d1f197-938a-49ef-9343-6f55ec76fd90/container_workload_profiles/afe4661a-03ef-462f-ada6-ce7334aa9704

{
	"labels": [ 
		{ "key": "env", "restriction": [{"href": "/orgs/1/labels/176"}, {"href": "/orgs/1/labels/302"}, {"href": "/orgs/1/labels/303"}] }
	]
}

Allow any value for the Application label

PUT /api/v2/orgs/1/container_clusters/65d1f197-938a-49ef-9343-6f55ec76fd90/container_workload_profiles/afe4661a-03ef-462f-ada6-ce7334aa9704

{
	"labels": [
		{ "key": "app", "restriction": [] }
	]
}

Multiple ways to assign or allow labels used together in one Container Workload Profile

PUT /api/v2/orgs/1/container_clusters/65d1f197-938a-49ef-9343-6f55ec76fd90/container_workload_profiles/afe4661a-03ef-462f-ada6-ce7334aa9704

{ 
	"labels": [ 
		{"key": "role", "assign": {} },
		{"key": "app", "restriction": [] },
		{"key": "env", "restriction": [{"href": "/orgs/1/labels/176"}, {"href": "/orgs/1/labels/302"}, {"href": "/orgs/1/labels/303"}] },
		{"key": "loc", "assign": {"href": "/orgs/1/labels/221"} }
	]
}

Result for the above example:

  • role: No label will be set; it is an explicit statement (you don't want a role label to be assigned).

  • app: Any value can be set in the annotations for the app label key (provided the value exists in PCE).

  • env: Only the values specified in the allowlist can be set in the annotations for the env label key.

  • loc: The value of the loc label key is assigned to the value defined in the payload.

Label Assignment Configuration

To clear the label assignment option and go back to the default option (any labels passed at runtime using Kubernetes annotations will be allowed), 2 options:

Option 1: explicit statement

{
	"labels": [
		{ "key": "role", "restriction": [] }
	]
}

Option 2: empty payload

{
	"labels": []
}
Backend Services Associated with Container Clusters

Kubernetes services are represented as virtual services in the Illumio policy model. For the services in Kubernetes, Kubelink creates virtual services in the PCE and reports the list of Replication Controllers, DaemonSets, and ReplicaSets responsible for managing the pods that support the services.

When there is a match between the Replication Controller and ReplicaSet managing a pod, the PCE creates a binding between the virtual service and the container workload.

The Service Backend represents a match between a virtual service and an application type, such as Deployment or ReplicaSet.

Use this method to get the service backend:

Functionality

HTTP

URI

Get data about the service backend

GET

GET /orgs/1/container_clusters/:container_cluster_id/service_backends

Properties for Backend Services

Parameters

Description

Type

Required

name

The name of the container cluster backend.

String

Yes

kind

The type (or kind) of the container cluster backend.

String

Yes

updated_at

The time (rfc339 timestamp) at which the container cluster backend was updated.

String

Yes

created_at

The time (rfc339 timestamp) at which the container cluster backend was created.

String

Yes

virtual_services

Includes the following properties:

  • href:The URI to the associated virtual service

  • name: The virtual service name

Object

String

String

Yes

Curl Examples

Curl Example for GET

curl --request GET --url https://pce.my-company.com:8443/api/v2/orgs/1/container_clusters/445bfa9b-4de4-4c09-9705-496eb04b190f/service_backends --header 'authorization: Basic YzE2YjBkYjI0MjJhZGNkYWU5OjA5ZmRjNjA4MDhiMzExZTc2Y2UyNzNmOWNiN2ZhMTA5OTdkMWNlMDAzZmMzOTQ1ZGMxYzEwZGJhZTg5NzlmZjM='

Example Response for GET

[
    {
        "name": "58687784f9",    
        "kind": "replicasethash",
        "namespace": "kube-system",
        "updated_at": "2020-10-25T20:07:39.741Z",
        "created_at": "2020-10-25T20:07:39.741Z",
        "virtual_service": {
        "href": "/orgs/1/sec_policy/draft/virtual_services/926c2f63-bcd8-42f1-8811-165b34f84334",
        "name": "coredns-k8s2-kube-system"
        }
    },
    {
        "name": "556b9ff8f8",
        "kind": "replicasethash",
        "namespace": "kube-system",   
        "updated_at": "2020-10-25T20:07:39.768Z",
        "created_at": "2020-10-25T20:07:39.768Z",
        "virtual_service": {
        "href": "/orgs/1/sec_policy/draft/virtual_services/58b0df03-1151-464e-8352-069e3ad0d7ed",  
        "name": "kubernetes-dashboard-k8s2-kube-system"
        }
    }
]

Kubernetes APIs

Kubernetes Workload Endpoints

Customers have been requiring to see the details of Kubernetes workloads in PCE so that they can write policies and troubleshoot any issues.

Two new endpoints have been created for Kubernetes workloads:

GET /api/v2/orgs/:xorg_id/kubernetes_workloads

This API lists all new Kubernetes Workloads in separate tab/page with separate sorts and filters.

It contains required properties such as name, kind, namespace,

as well as optional properties href, labels, enforcement_mode,visibility_level, container_workload_profile, container_cluster, security_policy_applied_at, security_policy_sync_state, created_at, k8s_label, and k8s_annotations.

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"type": "object",
	"required": [
		"name",
		"kind",
		"namespace"
	],
	"properties": {
		"href": {
			"description": "URI of the container workload",
			"type": "string"
		},
		"name": {
			"description": "Container workload name",
			"type": "string"
		},
		"namespace": {
			"description": "k8s namespace where this k8s Workload belongs to",
			"type": "string"
		},
		"kind": {
			"description": "k8s resource kind, e.g. Deployment",
			"type": "string"
		},
		"labels": {
			"type": "array",
			"items": {
			"$ref": "../common/label_optional_key_value.schema.json"
		   }
		},
		"enforcement_mode": {
			"$ref": "../common/workload_enforcement_mode.schema.json"
		},
		"visibility_level": {
			"$ref": "../common/workload_visibility_level.schema.json"
		},
		"container_workload_profile": {
			"$ref": "container_clusters_container_workload_profiles_get.schema.json"
		},
		"container_cluster": {
			"$ref": "container_clusters_get.schema.json"
		},
		"security_policy_applied_at": {
			"description": "Last reported time when policy was processed by CLAS to the k8s workload (UTC)",
			"type": [
			 "string",
			 "null"
			],
			"format": "date-time"
		},
		"security_policy_sync_state": {
			"description": "Current state of security policy",
			   "type": "string"
		},
		"created_at": {
			"description": "RFC 3339 timestamp at which this record was created",
			"format": "date-time",
			"type": "string"
		},
		"updated_at": {
			"description": "RFC 3339 timestamp at which this record was updated",
			"format": "date-time",
			"type": "string"
		},
		"k8s_labels": {
			"type": "array",
			"items": {
			"type": "object",
			"required": [
			   "key",
			   "value"
			],
			"properties": {
			   "key": {
			   "type": "string"
			},
			"value": {
			"type": "string"
			}
                    }
		   }
		},
		"k8s_annotations": {
			"type": "array",
			"items": {
			"type": "object",
			"required": [
			   "key",
			   "value"
			],
			"properties": {
			   "key": {
			   "type": "string"
			},
			"value": {
			   "type": "string"
			}
		    }
		}
	    }
	}
}

For this API, these changes have been made in release 23.5.0:

  • two arrays have been removed, k8s_labels and sk8s_annotation, and replaced with the property metadata

	"metadata": {
		"$ref": "
		../common/kubernetes_workloads_metadata.schema.json"

  • HREF description has been changed from URI of the container workload, to URI of the kubernetes workload.

GET /api/v2/orgs/:xorg_id/kubernetes_workloads/:kubernetes_workload_uuid

This API provides a detailed page for the specified Kubernetes workload with custom K8S attributes.

common non_empty_label_scopes.schema.json

This new common schema provides a collection of assigned list of labels. Minimum number is one.

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"description": "Collection of assigned list of labels",
	"type": "array",
	"items": {
		"$ref": "labels.schema.json",
		"minItems": 1
	},
	"uniqueItems": true,
	"minItems": 1
}
common kubernetes_workloads_metadata

The new common schema kubernetes_workloads_metadata was added in release 23.5.0 that is referenced from kubernetes_workload_get.

It provides Kubernetes properties such as labels, annotations, and external service's UID.

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"description": "k8s object metadata",
	"additionalProperties": false,
	"type": "object",
	"properties": {
	"labels": {
	   "description": "k8s key/value pairs attached to object that specify identifying attributes",
	   "type": "object"
           },
	"annotations": {
	   "description": "k8s key/value pairs representing arbitrary non-identifying metadata of object",
	   "type": "object"
	   },
	"external_service_uid": {
	   "description": "k8s object uid of external traffic service (NodePort or LoadBalancer)",
	    "type": "string"
          }
     }
}

For more information, see Kubernetes Openshift Guideguide.

See also: