Tagging Clusters
Note: As of v1.8, Enterprise PKS has been renamed to VMware Tanzu Kubernetes Grid Integrated Edition. Some screenshots in this documentation do not yet reflect the change.
Page last updated:
This topic explains how to tag new and existing clusters using the TKGI CLI.
Overview
IaaSes provide the ability for customers to “tag” VMs, databases, and other resources with custom labels and metadata values. Apply one or more tags to your clusters to simplify organizing, managing, searching for, and filtering resources within your IaaS-provided management console and other tools:
If your Tanzu Kubernetes Grid Integrated Edition deployment is on Azure or vSphere, including vSphere with NSX-T, you can use the TKGI CLI to tag clusters by following the steps in Tag Your Clusters as They Are Created below.
If your Tanzu Kubernetes Grid Integrated Edition deployment is on AWS or GCP, you can tag your clusters using your IaaS-provided management console.
Note: Tanzu Kubernetes Grid Integrated Edition Cluster tagging requires Ops Manager v2.8.0 or later.
Tag Your Clusters as They Are Created
To apply tags to your cluster’s VMs, include the --tags
parameter in your
tkgi create-cluster
command line,
and specify the desired tags as a comma-delimited list of key:value
pairs.
tkgi create-cluster CLUSTER-NAME --tags "TAGS"
Where:
CLUSTER-NAME
is the name of the cluster to create.TAGS
is a comma-delimited list ofkey:value
pairs to apply to the cluster.
For example:
$ tkgi create-cluster my-cluster --tags "status:billable" $ tkgi create-cluster my-cluster --tags "status:non-billable,region:northwest" $ tkgi create-cluster my-cluster --tags "client:example.com, costcenter:pettycash"
Tag Your Existing Clusters
To apply tags to your existing cluster’s VMs, run the tkgi update-cluster
command line,
and specify the --tags
parameter and a comma-delimited list of key:value
pairs of the tags to apply to the cluster.
tkgi update-cluster CLUSTER-NAME --tags "TAGS"
Where:
CLUSTER-NAME
is the name of the cluster to tag.TAGS
is a comma-delimited list ofkey:value
pairs.
For example:
$ tkgi update-cluster my-cluster --tags "client:tinymegacorp" $ tkgi update-cluster my-cluster --tags "client:example.com,costcenter:pettycash" $ tkgi update-cluster my-cluster --tags "status:non-billable, region:northwest"
Modify Cluster Tags
You can also use tkgi update-cluster
to modify your cluster’s existing tags.
When you modify cluster tags you completely replace all of the
cluster’s existing tags with the specified tags.
Note:
On Azure, tkgi update-cluster
cannot remove tags from your IaaS.
For more information, see Azure-Specific Tagging Limitations below.
Modify Your Existing Tags
To modify your cluster’s existing tags do the following:
Retrieve the cluster’s existing tags list string by running
tkgi cluster
. For information ontkgi cluster
Review Your Tags below.Modify the tags list string by doing one of the following:
- To add a new tag, append it to existing tags list string.
- To modify an existing tag, modify it within the tags list string.
- To remove an existing tag, delete it from within the tags list string.
Run the following command:
tkgi update-cluster CLUSTER-NAME --tags "TAGS"
Where
TAGS
is a comma-delimited list of revisedkey:value
pairs.
Remove All Tags From Your Cluster
To remove all of your cluster’s existing tags do the following:
Run the following
tkgi update-cluster --tags
on your command line:tkgi update-cluster CLUSTER-NAME --tags ""
Where
CLUSTER-NAME
is the cluster to remove tags from.
Review Your Tags
To review the tags applied to a cluster, run tkgi cluster
.
For example:
$ tkgi cluster my-cluster Name: my-cluster Plan Name: large UUID: 01a234bc-d56e-7f89-01a2-3b4cde5f6789 Last Action: CREATE Last Action State: succeeded Last Action Description: Instance provisioning completed Kubernetes Master Host: my-cluster.example.com Kubernetes Master Port: 8443 Worker Instances: 3 Kubernetes Master IP(s): 192.168.20.7 Tags: client:tinymegacorp,costcenter:pettycash
The tkgi cluster
function returns only the custom tags you’ve applied to
the cluster using the TKGI CLI.
To display all of the tags applied to your cluster VMs use your IaaS-provided management console.
Note:
Do not use the IaaS-provided management console to modify your custom tags.
Custom tag alterations you’ve applied via the management console will be overwritten
when you next run tkgi update-cluster
.
Tagging Rules
The tagging you apply must adhere to the following rules:
- Tag names and values should not include either
"
,:
or,
. - Surrounding double quotes are required if there are one or more spaces in your tag list, such as a space after a comma delimiter.
- Tag names and values must adhere to the tagging rules of the IaaS hosting your Tanzu Kubernetes Grid Integrated Edition environment.
For information about IaaS-specific tagging rules see the following:
- Azure: See Use tags to organize your Azure resources in the Azure documentation.
- vSphere: See vSphere Tags and Attributes in the vSphere documentation.
Tagging Limitations
Cluster tagging has the following limitations:
Tags Reserved for BOSH
The BOSH layer applies 10 system-level metadata tags to each cluster, including deployment
, director
, id
, index
, instance_group
, job
, and name
.
These reserved tags impose the following limitations:
The maximum number of custom tags you can apply to a cluster is 10 less than the maximum number of tags supported by your IaaS.
- For example: Azure limits tagging to a maximum of 50 tags per entity. Therefore, if your Tanzu Kubernetes Grid Integrated Edition environment is hosted on Azure, apply fewer than 40 custom tags to your clusters.
You cannot set or change BOSH system-level tags using the TKGI CLI. If you use the TKGI CLI to create tags with those reserved names, they are ignored.
- When you try to change system-level tags with the TKGI CLI, the output of
tkgi cluster
shows the tag values passed into thecreate-cluster
orupdate-cluster
command, but BOSH overrides and ignores these settings.
- When you try to change system-level tags with the TKGI CLI, the output of
Azure-Specific Tagging Limitations
The following are the known Azure-specific IaaS tagging limitations:
tkgi update-cluster
cannot remove tags from your Azure clusters. This limitation is due to an issue in the Azure CPI for BOSH which is used bytkgi cli
for Azure IaaS tagging.
- To remove an IaaS tag from an Azure cluster do the following:
- Perform the removal steps described in Modify Existing Tags above.
- Remove unwanted tags through the Azure portal.
- To remove an IaaS tag from an Azure cluster do the following:
For information about additional Azure-specific tagging limitations see Use tags to organize your Azure resources in the Azure documentation.
vSphere-Specific Tagging Limitations
The following are the known vSphere-specific IaaS tagging limitations:
tkgi update-cluster
applies tagging to vSphere entities as vSphere Custom Attributes. This limitation is due to an issue in the vSphere CPI which is used bytkgi cli
for vSphere IaaS tagging.
- vSphere Custom Attribute tagging is applied to VMs only. Disks and other resources are not tagged.
- A vSphere Custom Attribute applied to a single VM is also visible on all other VMs, but as an empty property.
- vSphere Custom Attribute tagging is applied to VMs only. Disks and other resources are not tagged.
For information about additional vSphere-specific tagging limitations see vSphere Tags and Attributes in the vSphere documentation.
Please send any feedback you have to pks-feedback@pivotal.io.