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)

For more information, see the Illumio Core for Kubernetes and OpenShift guide at Illumio Kubernetes Openshift Guide

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`	`/orgs/:xorg_id/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

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 API

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 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 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`
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`	(GET, POST, PUT) Organization	Integer	Yes
`container_cluster_id`	(GET, POST, PUT) Cluster UUID	String	Yes
`container_workload_profile_id`	(PUT) Container workload profile UUID	String	Yes
`href`	(POST) Label URI	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`	(GET) Filter by linked container workload profiles.	Boolean	No
`managed`	(GET) Filter by managed state	Boolean	No
`name`	(GET) Name string to match. Supports partial matches. (POST) A friendly name is given to a profile if the namespace is not user-friendly.	String	No YES
`namespace`	(GET) Namespace string to match. Supports partial matches.	String	No
`max_results`	(GET) Maximum number of container workloads to return..	Integer	No
`mode`	Filter by mode. There are three enforcement modes for container workloads: `idle`, `visibility_only`, and `full` NOTE: Although configurable in Container Workload Profiles, container workloads do not support enforcement mode set to `Selective`. The only supported enforcement modes are `Idle`, `Visibility Only`, or `Full`. Configuring enforcement to `Selective` in a container workload profile may result in unexpected enforcement behaviors. The two management modes are: `managed` and `unmanaged`	String	No
`visibility_level`	(GET) Filter by visibility level	String	No

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"
		}
	}

]

Label Restrictions

Kubernetes pods and services running in a namespace (Kubernetes) or project (OpenShift) must be labeled (RAEL) to be included in the 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:

No label will be assigned.
One label will be assigned from PCE.
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.
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": []
}

Service Backend API

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`

Query Parameters

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
`namespace`	The namespace of the container cluster backend.	String	No
`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"
		}
	}
]

REST APIs for 22.2

Container Clusters

Container Cluster API

Curl Examples and Responses

Container Cluster Workload Profiles API

Curl Examples and Responses

Label Restrictions

Examples

Label Assignment Configuration

Service Backend API

Curl Examples

Search results