This topic describes how to tag new and existing clusters using the VMware Tanzu Kubernetes Grid Integrated Edition Command Line Interface (TKGI CLI).
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:
You can use the TKGI CLI to tag clusters by following the steps in Tag Your Clusters as They Are Created below.
Note: Tanzu Kubernetes Grid Integrated Edition Cluster tagging requires Ops Manager v2.8.0 or later.
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.Note: Use only lowercase characters when naming your cluster if you manage your clusters with Tanzu Mission Control (TMC). Clusters with names that include an uppercase character cannot be attached to TMC.
TAGS
is a comma-delimited list of key: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"
You can use the TKGI CLI to tag an existing cluster.
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 of key: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"
WARNING: Update a cluster with a revised tags
only on a TKGI cluster that has been upgraded to the current TKGI version. For more information, see Tasks Supported Following a TKGI Control Plane Upgrade in About Tanzu Kubernetes Grid Integrated Edition Upgrades.
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.
To modify your cluster’s existing tags do the following:
Retrieve the cluster’s existing tags list string by running tkgi cluster
. For information on tkgi cluster
Review Your Tags below.
Modify the tags list string by doing one of the following:
Run the following command:
tkgi update-cluster CLUSTER-NAME --tags "TAGS"
Where TAGS
is a comma-delimited list of revised key:value
pairs.
WARNING: Update a cluster with a revised tags
only on a TKGI cluster that has been upgraded to the current TKGI version. For more information, see Tasks Supported Following a TKGI Control Plane Upgrade in About Tanzu Kubernetes Grid Integrated Edition Upgrades.
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.
WARNING: Update a cluster with a revised tags
only on a TKGI cluster that has been upgraded to the current TKGI version. For more information, see Tasks Supported Following a TKGI Control Plane Upgrade in About Tanzu Kubernetes Grid Integrated Edition Upgrades.
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
.
The tagging you apply must adhere to the following rules:
"
, :
, ,
.
For information about IaaS-specific tagging rules see the following:
Cluster tagging has the following limitations:
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.
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.
tkgi cluster
shows the tag values passed into the create-cluster
or update-cluster
command, but BOSH overrides and ignores these settings.For tagging limitations on Amazon Web Services (AWS), see Tag restrictions in the AWS documentation.
The following are known tagging limitations specific to Microsoft Azure:
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 by tkgi cli
for Azure IaaS tagging.
For information about additional Azure-specific tagging limitations see Use tags to organize your Azure resources in the Azure documentation.
Google Cloud Platform (GCP) refers to tags as “labels.” The following are known label limitations specific to Google Cloud Platform (GCP):
The following are known tagging limitations specific to vSphere:
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 by tkgi cli
for vSphere IaaS tagging.
For information about additional vSphere-specific tagging limitations see vSphere Tags and Attributes in the vSphere documentation.