Tagging Kubernetes Cluster-Related Resources

Using the Console to Specify Cluster Tags

To add a cluster tag to a new cluster:

1. Follow the instructions in Using the Console to create a Cluster with Explicitly Defined Settings in the 'Custom Create' workflow to create a new cluster.
2. Display the Cluster tags section of the Create Cluster page.
3. To add a defined tag to the cluster:
   • Tag Namespace: Select the tag namespace to which the tag belongs.
   • Tag Key: Select the name of the defined tag to apply to the cluster.
   • Tag Value: Either select the value for the tag from a pre-defined list of values, or enter a new value, or leave blank (depending on how the defined tag has been set up).
4. To add a free-form tag to the cluster:
   • Tag Namespace: Set to None (free-form tags do not belong to a tag namespace).
   • Tag Key: Enter a name for the free-form tag to apply to the cluster.
   • Tag Value: Enter a value for the tag to apply to the cluster.

To update cluster tags applied to an existing cluster:

1. Follow the instructions in Modifying Kubernetes Cluster Properties to update an existing cluster.
2. Display the Tags tab of the Cluster Details page.
3. Click Add Tags to add, remove, and change the value of defined tags and free-form tags applied to the cluster.

Using the CLI to Specify Cluster Tags

oci ce cluster create \
--compartment-id <compartment-ocid> \
--kubernetes-version <kubernetes-version> \
--name <cluster-name> --vcn-id <vcn-ocid> \
--defined-tags <json-name-value-pairs> \
--freeform-tags <json-name-value-pairs>

For example:

oci ce cluster create \
--compartment-id ocid1.compartment.oc1..aaaaaaaay______t6q \
--kubernetes-version v1.20.11 \
--name Finance-Cluster \
--vcn-id ocid1.vcn.oc1.iad.aaaaaae___yja \
--defined-tags {"Operations": {"CostCenter": "42"}} \
--freeform-tags {"Department": "Finance"}

Using the API to Specify Cluster Tags

Use the freeformTags and definedTags attributes of the CreateClusterDetails and UpdateClusterDetails objects used by the CreateCluster and Update Cluster operations to add and update cluster tags.

Using the Console to Specify Node Pool Tags

To add a node pool tag to a new node pool when creating a new cluster:

1. Follow the instructions in Using the Console to create a Cluster with Explicitly Defined Settings in the 'Custom Create' workflow to create a new cluster.
2. Display the Node Pool tags section of the Node Pools page.
3. To add a defined tag to the node pool:
   • Tag Namespace: Select the tag namespace to which the tag belongs.
   • Tag Key: Select the name of the defined tag to apply to the node pool.
   • Tag Value: Either select the value for the tag from a pre-defined list of values, or enter a new value, or leave blank (depending on how the defined tag has been set up).
4. To add a free-form tag to the node pool:
   • Tag Namespace: Set to None (free-form tags do not belong to a tag namespace).
   • Tag Key: Enter a name for the free-form tag to apply to the node pool.
   • Tag Value: Enter a value for the tag to apply to the node pool.

To update node pool tags applied to an existing node pool:

1. Follow the instructions in Modifying Node Pool and Worker Node Properties to update an existing node pool.
2. Display the Tags tab of the Node Pool Details page.
3. Click Add Tags to add, remove, and change the value of defined tags and free-form tags applied to the node pool.

Using the CLI to Specify Managed Node Pool Tags

oci ce node-pool create \
--cluster-id <cluster-ocid> \
--compartment-id <compartment-ocid> \
--kubernetes-version <kubernetes-version> \
--name <node-pool-name> \
--node-shape <node-shape> \
--defined-tags <json-name-value-pairs> \
--freeform-tags <json-name-value-pairs>

For example:

oci ce node-pool create \
--cluster-id ocid1.cluster.oc1.iad.aaaaaaaaaf______jrd \
--compartment-id ocid1.compartment.oc1..aaaaaaaay______t6q \
--kubernetes-version v1.20.11 \
--name Finance-Node-Pool \
--node-shape VM.Standard2.1 \
--defined-tags {"Operations": {"CostCenter": "42"}} \
--freeform-tags {"Department": "Finance"}

Using the CLI to Specify Virtual Node Pool Tags

oci ce virtual-node-pool create \
--cluster-id <cluster-ocid> \
--compartment-id <compartment-ocid> \
--display-name <node-pool-name> \
--kubernetes-version <kubernetes-version> \
--placement-configurations "[{\"availabilityDomain\":\"<ad-name>\",\"faultDomain\":[\"FAULT-DOMAIN-<n>\"],\"subnetId\":\"<virtualnode-subnet-ocid>\"}]" \
--nsg-ids "[\"<virtual-node-nsg-ocid>\"]" \
--pod-configuration "{\"subnetId\":\"<pod-subnet-ocid>\",\"nsgIds\":[\"<pod-nsg-ocid>\"],\"shape\":\"<shape-name>\"}" \
--size <number-of-nodes> \
--defined-tags <json-name-value-pairs> \
--freeform-tags <json-name-value-pairs>

For example:

oci ce virtual-node-pool create \
--cluster-id ocid1.cluster.oc1.phx.aaaaaaaa______w5q \
--compartment-id ocid1.compartment.oc1..aaaaaaaa______n5q \
--display-name sales-vnp \
--kubernetes-version v1.24.1 \
--placement-configurations "[{\"availabilityDomain\":\"GMvH:PHX-AD-1\",\"faultDomain\":[\"FAULT-DOMAIN-1\"],\"subnetId\":\"ocid1.subnet.oc1.phx.aaaaaaaa______sra\"}]" \
--nsg-ids "[\"ocid1.networksecuritygroup.oc1.phx.aaaaaaaa______hpa\"]" \
--pod-configuration "{\"subnetId\":\"ocid1.subnet.oc1.phx.aaaaaaaa______o7q\",\"nsgIds\":[\"ocid1.networksecuritygroup.oc1.phx.aaaaaaaa______osq\"],\"shape\":\"Pod.Standard.E4.Flex\"}" \
--size 1 \
--defined-tags {"Operations": {"CostCenter": "43"}} \
--freeform-tags {"Department": "Sales"}

Using the API to Specify Node Pool Tags

To add and update managed node pool tags, use the freeformTags and definedTags attributes of the CreateNodePoolDetails and UpdateNodePoolDetails objects used by the CreateNodePool and UpdateNodePool operations.

To add and update virtual node pool tags, use the freeformTags and definedTags attributes of the CreateVirtualNodePoolDetails and UpdateVirtualNodePoolDetails objects used by the CreateVirtualNodePool and UpdateVirtualNodePool operations.

Using the Console to Specify Managed Node Tags

To add a node tag to managed nodes in a new managed node pool when creating a new cluster:

1. Follow the instructions in Using the Console to create a Cluster with Explicitly Defined Settings in the 'Custom Create' workflow to create a new cluster.
2. Display the Node tags section of the Node Pools page.
3. To add a defined node tag to worker nodes in the new node pool:
   • Tag Namespace: Select the tag namespace to which the tag belongs.
   • Tag Key: Select the name of the defined tag to apply to worker nodes.
   • Tag Value: Either select the value for the tag from a pre-defined list of values, or enter a new value, or leave blank (depending on how the defined tag has been set up).
4. To add a free-form node tag to worker nodes in the new node pool:
   • Tag Namespace: Set to None (free-form tags do not belong to a tag namespace).
   • Tag Key: Enter a name for the free-form tag to apply to worker nodes.
   • Tag Value: Enter a value for the tag to apply to worker nodes.

To update node tags applied to new managed nodes created in an existing managed node pool:

1. Follow the instructions in Modifying Node Pool and Worker Node Properties to update an existing node pool.
2. Display the Node Tags tab of the Node Pool Details page.
3. Click Add Tags to add, remove, and change the value of defined tags and free-form tags applied to worker nodes in the node pool.

   Note that tags are only applied to worker nodes when the worker nodes are first created. So if you update the tags applied to worker nodes, the changes only apply to new worker nodes. Tags already applied to existing worker nodes are unaffected.

Using the CLI to Specify Managed Node Tags

oci ce node-pool create \
--cluster-id <cluster-ocid> \
--compartment-id <compartment-ocid> \
--kubernetes-version <kubernetes-version> \
--name <node-pool-name> \
--node-shape <node-shape> \
--node-defined-tags <json-name-value-pairs> \
--node-freeform-tags <json-name-value-pairs>

For example:

oci ce node-pool create \
--cluster-id ocid1.cluster.oc1.iad.aaaaaaaaaf______jrd \
--compartment-id ocid1.compartment.oc1..aaaaaaaay______t6q \
--kubernetes-version v1.20.11 \
--name Finance-Node-Pool \
--node-shape VM.Standard2.1 \
--node-defined-tags {"Operations": {"CostCenter": "42"}} \
--node-freeform-tags {"Department": "Finance"}

Using the CLI to Specify Virtual Node Tags

oci ce virtual-node-pool create \
--cluster-id <cluster-ocid> \
--compartment-id <compartment-ocid> \
--display-name <node-pool-name> \
--kubernetes-version <kubernetes-version> \
--placement-configurations "[{\"availabilityDomain\":\"<ad-name>\",\"faultDomain\":[\"FAULT-DOMAIN-<n>\"],\"subnetId\":\"<virtualnode-subnet-ocid>\"}]" \
--nsg-ids "[\"<virtual-node-nsg-ocid>\"]" \
--pod-configuration "{\"subnetId\":\"<pod-subnet-ocid>\",\"nsgIds\":[\"<pod-nsg-ocid>\"],\"shape\":\"<shape-name>\"}" \
--size <number-of-nodes> \
--virtual-node-tags {\"defined-tags\": {<json-name-value-pairs>}, \"freeform-tags\": {<json-name-value-pairs>}}

For example:

oci ce virtual-node-pool create \
--cluster-id ocid1.cluster.oc1.phx.aaaaaaaa______w5q \
--compartment-id ocid1.compartment.oc1..aaaaaaaa______n5q \
--display-name sales-vnp \
--kubernetes-version v1.24.1 \
--placement-configurations "[{\"availabilityDomain\":\"GMvH:PHX-AD-1\",\"faultDomain\":[\"FAULT-DOMAIN-1\"],\"subnetId\":\"ocid1.subnet.oc1.phx.aaaaaaaa______sra\"}]" \
--nsg-ids "[\"ocid1.networksecuritygroup.oc1.phx.aaaaaaaa______hpa\"]" \
--pod-configuration "{\"subnetId\":\"ocid1.subnet.oc1.phx.aaaaaaaa______o7q\",\"nsgIds\":[\"ocid1.networksecuritygroup.oc1.phx.aaaaaaaa______osq\"],\"shape\":\"Pod.Standard.E4.Flex\"}" \
--size 1 \
--virtual-node-tags {\"defined-tags\": {\"Operations\": {\"CostCenter\": \"43\"}}, \"freeform-tags\": {\"Department\": \"Sales\"}}

Using the API

To add and update managed node tags, use the freeformTags and definedTags attributes of the CreateNodePoolNodeConfigDetails and UpdateNodePoolNodeConfigDetails objects used by the CreateNodePool and UpdateNodePool operations.

To add and update virtual node tags, use the freeformTags and definedTags attributes of the CreateVirtualNodePoolDetails.virtualNodeTags and UpdateVirtualNodePoolDetails.virtualNodeTags objects used by the CreateVirtualNodePool and UpdateVirtualNodePool operations.

Using the Console to Specify Initial Load Balancer Tags

To specify an initial load balancer tag to apply to load balancer resources created for a new cluster:

1. Follow the instructions in Using the Console to create a Cluster with Explicitly Defined Settings in the 'Custom Create' workflow to create a new cluster.
2. Display the Initial load balancer tags section of the Create Cluster page.
3. To add a defined tag to load balancer resources:
   • Tag Namespace: Select the tag namespace to which the tag belongs.
   • Tag Key: Select the name of the defined tag to apply to load balancer resources.
   • Tag Value: Either select the value for the tag from a pre-defined list of values, or enter a new value, or leave blank (depending on how the defined tag has been set up).
4. To add a free-form tag to load balancer resources:
   • Tag Namespace: Set to None (free-form tags do not belong to a tag namespace).
   • Tag Key: Enter a name for the free-form tag to apply to load balancer resources.
   • Tag Value: Enter a value for the tag to apply to load balancer resources.

To update initial load balancer tags to apply to new load balancer resources created for a cluster:

1. Follow the instructions in Modifying Kubernetes Cluster Properties to update an existing cluster.
2. Display the Initial Load Balancer Tags tab of the Cluster Details page.
3. Click Add Tags to add, remove, and change the value of defined tags and free-form tags applied to new load balancer resources.

   Note that tags are only applied to load balancers when the load balancers are first created. So if you update initial load balancer tags, the changes only apply to new load balancer resources. Tags already applied to existing load balancer resources are unaffected.

Using the CLI to Specify Initial Load Balancer Tags

oci ce node-pool create \
--cluster-id <cluster-ocid> \
--compartment-id <compartment-ocid> \
--kubernetes-version <kubernetes-version> \
--name <node-pool-name> \
--node-shape <node-shape>  \
--service-lb-defined-tags <json-name-value-pairs> \
--service-lb-freeform-tags <json-name-value-pairs>

For example:

oci ce node-pool create \
--cluster-id ocid1.cluster.oc1.iad.aaaaaaaaaf______jrd \
--compartment-id ocid1.compartment.oc1..aaaaaaaay______t6q \
--kubernetes-version v1.20.11 \
--name Finance-Node-Pool \
--node-shape VM.Standard2.1 \
--service-lb-defined-tags {"Operations": {"CostCenter": "42"}} \
--service-lb-freeform-tags {"Department": "Finance"}

Using the API to Specify Initial Load Balancer Tags

Use the freeformTags and definedTags attributes of the ServiceLbConfigDetails object used by the CreateCluster and Update Cluster operations to add and update initial load balancer tags.

Overriding Initial Load Balancer Tags

You can override initial load balancer tags specified for a cluster using annotations in the definition of a Kubernetes service of type LoadBalancer, as follows:

• For load balancer resources:

  • To override defined initial load balancer tags for load balancer resources, add the following annotation in the metadata section of the manifest file:

    oci.oraclecloud.com/initial-defined-tags-override: '{"<tag-namespace>": {"<tag-key>": "<tag-value>"}}'

  • To override free-form initial load balancer tags for load balancer resources, add the following annotation in the metadata section of the manifest file:

    oci.oraclecloud.com/initial-freeform-tags-override: '{"<tag-key>": "<tag-value>"}'

• For network load balancer resources:

  • To override defined initial load balancer tags for network load balancer resources, add the following annotation in the metadata section of the manifest file:

    oci-network-load-balancer.oraclecloud.com/initial-defined-tags-override: '{"<tag-namespace>": {"<tag-key>": "<tag-value>"}}'

  • To override free-form initial load balancer tags for network load balancer resources, add the following annotation in the metadata section of the manifest file:

    oci-network-load-balancer.oraclecloud.com/initial-freeform-tags-override: '{"<tag-key>": "<tag-value>"}'

For example:

apiVersion: v1
kind: Service
metadata:
  name: my-nginx-svc
  labels:
    app: nginx
  annotations:
    oci.oraclecloud.com/initial-defined-tags-override: '{"Operations": {"CostCenter": "42"}}'
    oci.oraclecloud.com/initial-freeform-tags-override: '{"Department": "Finance"}'
spec:
  type: LoadBalancer
  ports:
  - port: 80
  selector:
    app: nginx

Note the following:

• If you specify the above annotations, none of the initial load balancer tags set for the cluster are applied to the load balancer resource. Only the tags specified by the annotations, along with tag defaults, are applied to the load balancer resource.
• If you change the annotations in the manifest file, the changes only apply to new load balancer resources. Tags already applied to existing load balancer resources are unaffected. You cannot change the tags applied to an existing load balancer resource by changing the annotations. Instead, you have to create a new Kubernetes service of type LoadBalancer with the annotations for the tags you require.

Using the Console to Specify Initial Block Volume Tags

To specify an initial block volume tag to apply to block volume resources created for a new cluster:

1. Follow the instructions in Using the Console to create a Cluster with Explicitly Defined Settings in the 'Custom Create' workflow to create a new cluster.
2. Display the Initial block volume tags section of the Create Cluster page.
3. To add a defined tag to block volume resources:
   • Tag Namespace: Select the tag namespace to which the tag belongs.
   • Tag Key: Select the name of the defined tag to apply to block volume resources.
   • Tag Value: Either select the value for the tag from a pre-defined list of values, or enter a new value, or leave blank (depending on how the defined tag has been set up).
4. To add a free-form tag to block volume resources:
   • Tag Namespace: Set to None (free-form tags do not belong to a tag namespace).
   • Tag Key: Enter a name for the free-form tag to apply to block volume resources.
   • Tag Value: Enter a value for the tag to apply to block volume resources.

To update initial block volume tags to apply to new block volume resources created for a cluster::

1. Follow the instructions in Modifying Kubernetes Cluster Properties to update an existing cluster.
2. Display the Initial Block Volume Tags tab of the Cluster Details page.
3. Click Add Tags to add, remove, and change the value of defined tags and free-form tags applied to new block volume resources.

   Note that tags are only applied to block volume resources when the block volume resources are first created. So if you update initial block volume tags, the changes only apply to new block volume resources. Tags already applied to existing block volume resources are unaffected.

Using the CLI to Specify Initial Block Volume Tags

oci ce node-pool create \
--cluster-id <cluster-ocid> \
--compartment-id <compartment-ocid> \
--kubernetes-version <kubernetes-version> \
--name <node-pool-name> \
--node-shape <node-shape>  \
--persistent-volume-defined-tags <json-name-value-pairs> \
--persistent-volume-freeform-tags <json-name-value-pairs>

For example:

oci ce node-pool create \
--cluster-id ocid1.cluster.oc1.iad.aaaaaaaaaf______jrd \
--compartment-id ocid1.compartment.oc1..aaaaaaaay______t6q \
--kubernetes-version v1.20.11 \
--name Finance-Node-Pool \
--node-shape VM.Standard2.1 \
--persistent-volume-defined-tags {"Operations": {"CostCenter": "42"}} \
--persistent-volume-freeform-tags {"Department": "Finance"}

Using the API to Specify Initial Block Volume Tags

Use the freeformTags and definedTags attributes of the PersistentVolumeConfigDetails object used by the CreateCluster and Update Cluster operations to add and update initial block volume tags.

Overriding Initial Block Volume Tags

You can override initial block volume tags applied to a block volume resource using parameters in a storage class manifest file as follows:

• To override defined initial block volume tags, include the following parameter in the parameters section of the StorageClass definition:

  oci.oraclecloud.com/initial-defined-tags-override: '{"<tag-namespace>": {"<tag-key>": "<tag-value>"}}'

• To override free-form initial block volume tags, include the following parameter in the parameters section of the StorageClass definition:

  oci.oraclecloud.com/initial-freeform-tags-override: '{"<tag-key>": "<tag-value>"}'

For example:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: oci-bv-specifictags
provisioner: blockvolume.csi.oraclecloud.com
parameters:
  attachment-type: "paravirtualized"
  oci.oraclecloud.com/initial-freeform-tags-override: '{"Department": "Finance"}'
  oci.oraclecloud.com/initial-defined-tags-override: '{"Operations": {"CostCenter": "42"}}'
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer

Note the following:

• If you specify the above parameters, none of the initial block volume tags set for the cluster are applied to the block volume resource. Only the tags specified by the parameters, along with tag defaults, are applied to the block volume resource.
• Having applied a manifest file containing a StorageClass definition to create the storage class, you cannot subsequently change the tag parameter values by updating the definition and reapplying the manifest file. Once a storage class has been created, it is immutable. To specify different tag parameter values to the ones you previously specified, you have to create a new StorageClass definition that includes the new values for the tag parameters. Then specify the new storage class in the PVC definition.