Skip to main content

REST APIs for 24.2.20 and 24.2.10

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.

See also: