Container Clusters Reference

This topic covers properties, parameters, and examples for container clusters.

Parameters

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 is used for this container cluster only in Supercluster.	String	No
`cluster_mode`	The new property `cluster_mode` was added in 23.5.10 to describe the cluster mode for the container cluster. The default is `legacy`.	String

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

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

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

Properties for container workload methods

Property	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	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

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

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
	}, 
	...
]

Examples for label restrictions

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.

Properties

Backend services associated with container clusters

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

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

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

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

{
	"$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

{
	"$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 Illumio Core for Kubernetes and OpenShift.

REST APIs for 24.5