tanzu cluster

Manages Kubernetes clusters.

Important

Version 0.32.0 of the tanzu cluster command group for Tanzu Kubernetes Grid v2.5 does not support the creation of TKG workload clusters on AWS and Azure. Use the Tanzu Mission Control interface or the Tanzu Mission Control CLI commands ekscluster and aks-cluster to create native AWS EKS and Azure AKS clusters.

For more information, see End of Support for TKG Management and Workload Clusters on AWS and Azure in the VMware Tanzu Kubernetes Grid v2.5 Release Notes.

Three Tanzu CLI plugins provide commands under tanzu cluster based on different targets:

• kubernetes target: see below
• operations target: see tanzu operations cluster
• mission-control target: see cluster in the Tanzu Mission Control Plug-ins documentation

Usage

CLI plugin: cluster | Target: kubernetes | Primarily used for: Platform operations | Release Notes

Syntax:

tanzu cluster [COMMAND]

Aliases

cluster, cl, and clusters

Global Flags

-h, --help

Help text.

--log-file

Path to the log file.

-v, --verbose

Log verbosity, from 0 to 9.

tanzu cluster available-upgrades

Discovers the Kubernetes versions that are available for a specific cluster.

Available command:

get

tanzu cluster available-upgrades get

Lists all of the newer Kubernetes versions that are compatible with the specified cluster. For more information, see Upgrade Workload Clusters.

Usage

tanzu cluster available-upgrades get CLUSTER-NAME [FLAGS]

Example

To list the compatible Kubernetes versions for my-cluster:

tanzu cluster available-upgrades get my-cluster

Flags

-h, --help

Help text.

-n, --namespace

The namespace of the cluster. When not specified, tanzu cluster available-upgrades targets the default namespace.

tanzu cluster create

Creates a cluster. For more information, see Create Workload Clusters.

Usage

tanzu cluster create CLUSTER-NAME [FLAGS]

Examples

To create my-cluster from a configuration file, for example, configuration-file.yaml:

tanzu cluster create my-cluster --file configuration-file.yaml

To create my-cluster with a version of Kubernetes that is not the default for your version of Tanzu Kubernetes Grid, for example, v1.25.10---vmware.1-tkg.1:

tanzu cluster create my-cluster --file configuration-file.yaml --tkr v1.25.10---vmware.1-tkg.1

To preview the deployment manifest for my-cluster:

tanzu cluster create my-cluster --dry-run --file configuration-file.yaml > example-manifest.yaml

Flags

-d, --dry-run

Generates a deployment manifest from the cluster configuration file passed to the --file option. You can use this option to preview deployment manifests.

-f, --file

The configuration file from which to create the cluster.

-h, --help

Help text.

--tkr

The Tanzu Kubernetes release. Specify if you want to deploy a cluster with a version of Kubernetes that is not the default for your version of Tanzu Kubernetes Grid. If you specify only the release name prefix (for example, v1.21.8), tanzu cluster create uses the latest compatible Tanzu Kubernetes release matching the prefix. To list available Tanzu Kubernetes releases, see tanzu kubernetes-release get. For more information, see Create Workload Clusters with Different Kubernetes Versions.

tanzu cluster credentials

Configures the vSphere credentials that the specified cluster uses to access vSphere.

Available command:

update

tanzu cluster credentials update

Updates the credentials that the specified cluster uses to access vSphere or Azure (v0.31.x only). For more information, see Update Workload Cluster Credentials.

Usage

tanzu cluster credentials update CLUSTER-NAME [FLAGS]

Example

To update the credentials for my-cluster that is running in my-cluster-namespace:

tanzu cluster credentials update my-cluster --namespace my-cluster-namespace

Flags

Note

The --azure-* flags have been removed in version 0.32.0 of tanzu cluster credentials update, due to the end of support for deployments to Azure.

--azure-client-id

The client ID of the app for Tanzu Kubernetes Grid that you registered in Azure.

--azure-client-secret

The client secret of the app for Tanzu Kubernetes Grid that you registered in Azure.

--azure-tenant-id

The tenant ID for Azure Active Directory in which the app for Tanzu Kubernetes Grid is located.

-h, --help

Help text.

-n, --namespace

The namespace of the cluster that you are updating credentials for.

--vsphere-password

The new password for the vSphere account.

--vsphere-thumbprint

The SHA-1 signature of the vCenter Server TLS certificate.

--vsphere-user

The new username for the vSphere account.

tanzu cluster delete

Deletes the specified cluster. For more information, see Delete Workload Clusters.

Usage

tanzu cluster delete CLUSTER-NAME [FLAGS]

Example

To delete my-cluster that is running in my-cluster-namespace:

tanzu cluster delete my-cluster --namespace my-cluster-namespace

Flags

-h, --help

Help text.

-n, --namespace

The namespace of the cluster that you are deleting. When not specified, tanzu cluster delete targets the default namespace.

-y, --yes

When specified, tanzu cluster delete skips the confirmation step.

tanzu cluster get

Shows the details of the specified cluster.

Usage

tanzu cluster get CLUSTER-NAME [FLAGS]

Example

To see the details of my-cluster that is running in the default namespace:

tanzu cluster get my-cluster --namespace default

Flags

-h, --help

Help text.

-n, --namespace

The namespace of the cluster. If not specified, tanzu cluster get targets all namespaces.

--show-all-conditions

A list of comma-separated objects, kind or kind/name, for which you want to see their status conditions. all shows conditions for all of the objects.

--show-details

Shows the details of MachineInfrastructure and BootstrapConfig when the Ready condition is true or it has the same Status, Severity, and Reason as the machine’s object.

--show-group-members

Expands machine groups whose Ready condition has the same Status, Severity, and Reason.

tanzu cluster kubeconfig

Manages kubeconfig files.

Available command:

get

tanzu cluster kubeconfig get

Gets the kubeconfig of the specified cluster and merges its context into the default kubeconfig file. For more information, see Connect to and Examine Workload Clusters.

Usage

tanzu cluster kubeconfig get CLUSTER-NAME [FLAGS]

Examples

To get the kubeconfig of my-cluster running in my-namespace:

tanzu cluster kubeconfig get my-cluster --namespace my-namespace

To get the admin kubeconfig of my-cluster running in my-namespace:

tanzu cluster kubeconfig get my-cluster --namespace my-namespace --admin

Flags

--admin

Gets the admin kubeconfig of the cluster.

--export-file

Saves the kubeconfig file to the path that you specify.

-h, --help

Help text.

-n, --namespace

The namespace of the cluster. If not specified, tanzu cluster kubeconfig get targets the default namespace.

tanzu cluster list

Lists workload clusters and the management clusters that manage them. For more information, see Connect to and Examine Workload Clusters.

Usage

tanzu cluster list [FLAGS]

Examples

To list all of the workload clusters in the default namespace that are managed by the current management cluster:

tanzu cluster list

To list only those clusters that are running in a given namespace, for example, my-namespace:

tanzu cluster list --namespace my-namespace

To include the current management cluster in the output:

tanzu cluster list --include-management-cluster

Flags

-A, --all-namespaces

Includes clusters in all namespaces that are managed by the management cluster and for which the user has View permissions or greater.

-h, --help

Help text.

--include-management-cluster

Includes the current management cluster in the output.

-n, --namespace

The namespace from which to list the clusters. If not specified, the output lists all of the workload clusters in the default namespace that are managed by the management cluster.

-o, --output

Output format. Supported values are yaml, json, and table.

tanzu cluster machinehealthcheck

Creates and manages machine health checks for control plane and worker nodes. For more information, see Configure Machine Health Checks for Workload Clusters.

Available commands:

• control-plane
• node

tanzu cluster machinehealthcheck control-plane

Creates and manages machine health checks for the control plane nodes of a cluster.

Available commands:

• delete
• get
• set

tanzu cluster machinehealthcheck control-plane delete

Deletes the MachineHealthCheck object for the control plane nodes of the specified cluster.

Usage

tanzu cluster machinehealthcheck control-plane delete CLUSTER-NAME [FLAGS]

Example

To delete the MachineHealthCheck object for the control plane nodes of my-cluster:

tanzu cluster machinehealthcheck control-plane delete my-cluster --mhc-name my-cp-mhc

In this example, my-cp-mhc is the name of the MachineHealthCheck object. Omit this flag if the object was created with the default name or if you are targeting a class-based cluster.

Flags

-h, --help

Help text.

-m, --mhc-name

(Legacy clusters only) The name of the MachineHealthCheck object. You can omit this flag if the object was created with the default name. By default, MachineHealthCheck is created with the same name as the cluster name. --mhc-name is ignored for class-based clusters.

-n, --namespace

The namespace of the MachineHealthCheck object. Defaults to the namespace of the specified cluster.

-y, --yes

When specified, tanzu cluster machinehealthcheck control-plane delete skips the confirmation step.

tanzu cluster machinehealthcheck control-plane get

Gets the MachineHealthCheck object for the control plane nodes of the specified cluster.

Usage

tanzu cluster machinehealthcheck control-plane get CLUSTER-NAME [FLAGS]

Example

To get the MachineHealthCheck object for the control plane nodes of my-cluster:

tanzu cluster machinehealthcheck control-plane get my-cluster --mhc-name my-cp-mhc

In this example, my-cp-mhc is the name of the MachineHealthCheck object. Omit this flag if the object was created with the default name.

Flags

-h, --help

Help text.

-m, --mhc-name

The name of the MachineHealthCheck object. You can omit this flag if the object was created with the default name. By default, MachineHealthCheck is created with the same name as the cluster name.

-n, --namespace

The namespace of the MachineHealthCheck object.

tanzu cluster machinehealthcheck control-plane set

Creates or updates a MachineHealthCheck object.

Usage

tanzu cluster machinehealthcheck control-plane set CLUSTER-NAME [FLAGS]

Examples

To create a default MachineHealthCheck object for the control plane of a class-based cluster, for example, my-cluster:

tanzu cluster machinehealthcheck control-plane set my-cluster

To create a default MachineHealthCheck object for the control plane of a legacy cluster, for example, my-cluster:

tanzu cluster machinehealthcheck control-plane set my-cluster --mhc-name my-cp-mhc

In the example above, my-cp-mhc is the name of the MachineHealthCheck object.

Flags

-h, --help

Help text.

--match-labels

One or more key-value pairs to select machines.

--max-unhealthy

If the number of unhealthy machines exceeds the value you set using this flag, the MachineHealthCheck controller does not perform remediation. The --max-unhealthy setting defaults to 100%. You can specify either an absolute number or percentage for this flag.

-m, --mhc-name

(Legacy clusters only) The name of the MachineHealthCheck object. If --mhc-name is not specified, the name is set to the cluster name. If you intend to run both tanzu cluster machinehealthcheck control-plane set and tanzu cluster machinehealthcheck node set against a legacy cluster, specifying --mhc-name is required. --mhc-name is ignored for class-based clusters.

-n, --namespace

The namespace of the specified cluster.

--node-startup-timeout

The amount of time that the MachineHealthCheck controller waits for a machine to join the cluster before considering the machine unhealthy and remediating it.

--unhealthy-conditions

A list of conditions that determine whether a node is unhealthy. Supported conditions include Ready, MemoryPressure, DiskPressure, PIDPressure, and NetworkUnavailable. To set the status of a condition, use True, False, or Unknown.

tanzu cluster machinehealthcheck node

Creates and manages machine health checks for the worker nodes of a cluster.

Available commands:

• delete
• get
• set

tanzu cluster machinehealthcheck node delete

Deletes the MachineHealthCheck object or objects for the worker nodes of the specified cluster.

Usage

tanzu cluster machinehealthcheck node delete CLUSTER-NAME [FLAGS]

Example

To delete the MachineHealthCheck object for the worker nodes of my-cluster:

tanzu cluster machinehealthcheck node delete my-cluster --mhc-name my-workers-mhc

In the example above, my-workers-mhc is the name of the MachineHealthCheck object. Omit this flag if the object was created with the default name or if you are targeting a class-based cluster with a single machine deployment.

To delete the MachineHealthCheck objects for the worker nodes of a class-based cluster with multiple machine deployments, for example, my-cluster:

# md-0 is an example machine deployment name. Run this command for each machine deployment in the cluster.
tanzu cluster machinehealthcheck node delete my-cluster --machine-deployment md-0

Flags

-h, --help

Help text.

--machine-deployment

(Class-based clusters only) The name of the machine deployment. For example, md-0. Required if the cluster has multiple machine deployments; run for each machine deployment in the cluster. To retrieve the machine deployment name, run kubectl get cluster CLUSTER-NAME -o yaml and then locate spec.topology.workers.machineDeployments.name in the output.

-m, --mhc-name

(Legacy clusters only) The name of the MachineHealthCheck object. You can omit this flag if the object was created with the default name. By default, MachineHealthCheck is created with the same name as the cluster name. --mhc-name is ignored for class-based clusters.

-n, --namespace

The namespace of the MachineHealthCheck object. Defaults to the namespace of the specified cluster.

-y, --yes

When specified, tanzu cluster machinehealthcheck node delete skips the confirmation step.

tanzu cluster machinehealthcheck node get

Gets the MachineHealthCheck object for the worker nodes of the specified cluster.

Usage

tanzu cluster machinehealthcheck node get CLUSTER-NAME [FLAGS]

Example

To get the MachineHealthCheck object for the worker nodes of my-cluster:

tanzu cluster machinehealthcheck node get my-cluster --mhc-name my-workers-mhc

In this example, my-workers-mhc is the name of the MachineHealthCheck object. Omit this flag if the object was created with the default name.

Flags

-h, --help

Help text.

-m, --mhc-name

The name of the MachineHealthCheck object. You can omit this flag if the object was created with the default name. By default, MachineHealthCheck is created with the same name as the cluster name.

-n, --namespace

The namespace of the MachineHealthCheck object.

tanzu cluster machinehealthcheck node set

Creates or updates a MachineHealthCheck object.

Usage

tanzu cluster machinehealthcheck node set CLUSTER-NAME [FLAGS]

Examples

To create a default MachineHealthCheck object for the worker nodes of a class-based cluster with a single machine deployment, for example, my-cluster:

tanzu cluster machinehealthcheck node set my-cluster

To create a default MachineHealthCheck object for the worker nodes of a class-based cluster with multiple machine deployments, for example, my-cluster:

# md-0 is an example machine deployment name. Run this command for each machine deployment in the cluster.
tanzu cluster machinehealthcheck node set my-cluster --machine-deployment md-0

To create a default MachineHealthCheck object for the worker nodes of a legacy cluster:

tanzu cluster machinehealthcheck node set my-cluster --mhc-name my-workers-mhc

In the example above, my-cluster and my-workers-mhc are the name of the cluster and MachineHealthCheck object respectively.

Flags

-h, --help

Help text.

--machine-deployment

(Class-based clusters only) The name of the machine deployment. For example, md-0. Required if the cluster has multiple machine deployments; run for each machine deployment in the cluster. To retrieve the machine deployment name, run kubectl get cluster CLUSTER-NAME -o yaml and then locate spec.topology.workers.machineDeployments.name in the output.

--match-labels

One or more key-value pairs to select machines.

--max-unhealthy

If the number of unhealthy machines exceeds the value you set using this flag, the MachineHealthCheck controller does not perform remediation. The --max-unhealthy setting defaults to 100%. You can specify either an absolute number or percentage for this flag.

-m, --mhc-name

(Legacy clusters only) The name of the MachineHealthCheck object. If --mhc-name is not specified, the name is set to the cluster name. If you intend to run both tanzu cluster machinehealthcheck control-plane set and tanzu cluster machinehealthcheck node set against a legacy cluster, specifying --mhc-name is required. --mhc-name is ignored for class-based clusters.

-n, --namespace

The namespace of the specified cluster.

--node-startup-timeout

The amount of time that the MachineHealthCheck controller waits for a machine to join the cluster before considering the machine unhealthy and remediating it.

--unhealthy-conditions

A list of conditions that determine whether a node is unhealthy. Supported conditions include Ready, MemoryPressure, DiskPressure, PIDPressure, and NetworkUnavailable. To set the status of a condition, use True, False, or Unknown.

tanzu cluster node-pool

Creates and manages node pools. For more information, see Manage Node Pools of Different VM Types.

Available commands:

• delete
• list
• set

Note

tanzu cluster node-pool commands do not apply to single-node clusters.

tanzu cluster node-pool delete

Deletes the specified node pool.

Usage

tanzu cluster node-pool delete CLUSTER-NAME [FLAGS]

Example

To delete my-node-pool from my-cluster:

tanzu cluster node-pool delete my-cluster --name my-node-pool

Flags

-h, --help

Help text.

-n, --name

The name of the NodePool object that you are deleting.

--namespace

The namespace of the NodePool object. Defaults to the namespace of the specified cluster.

tanzu cluster node-pool list

Lists the node pools that are available in the specified cluster.

Usage

tanzu cluster node-pool list CLUSTER-NAME [FLAGS]

Example

To list all of the available node pools in the default namespace of my-cluster:

tanzu cluster node-pool list my-cluster

Flags

-h, --help

Help text.

-n, --namespace

The namespace of the cluster. If not specified, tanzu cluster node-pool list targets the default namespace.

-o, --output

Output format. Supported values are yaml, json, and table.

tanzu cluster node-pool set

Creates or updates the specified node pool.

Usage

tanzu cluster node-pool set CLUSTER-NAME [FLAGS]

Example

To create a node pool in the default namespace of my-cluster:

tanzu cluster node-pool set my-cluster -f node-pool-configuration-file.yaml

Flags

--base-machine-deployment

The base machine deployment from which to create the node pool.

-f, --file

The configuration file for the node pool.

-h, --help

Help text.

--namespace

The namespace of the cluster. If not specified, tanzu cluster node-pool set targets the default namespace.

tanzu cluster scale

Scales the specified cluster. For more information, see Scale Workload Clusters.

Note

tanzu cluster scale commands do not apply to single-node clusters.

Usage

tanzu cluster scale CLUSTER-NAME [FLAGS]

Examples

To scale my-cluster to 5 control plane and 10 worker nodes:

tanzu cluster scale my-cluster --controlplane-machine-count 5 --worker-machine-count 10

If my-cluster was created in a namespace other than default, specify the --namespace option to scale the cluster:

tanzu cluster scale my-cluster --controlplane-machine-count 5 --worker-machine-count 10 --namespace my-cluster-namespace

Flags

-c, --controlplane-machine-count

The desired number of control plane nodes.

-h, --help

Help text.

-n, --namespace

The namespace of the cluster that you are scaling. If not specified, tanzu cluster scale targets the default namespace.

-p, --node-pool-name

The name of the node pool to scale. For more information, see Update Node Pools.

-w, --worker-machine-count

The desired number of worker nodes.

tanzu cluster upgrade

Upgrades the specified cluster. For more information, see Upgrade Workload Clusters and Select an OS During Cluster Upgrade.

Usage

tanzu cluster upgrade CLUSTER-NAME [FLAGS]

Examples

To upgrade my-cluster to the default Kubernetes version:

tanzu cluster upgrade my-cluster

To upgrade my-cluster using a specific Tanzu Kubernetes release, for example, v1.25.10---vmware.1-tkg.1:

tanzu cluster upgrade my-cluster --tkr v1.25.10---vmware.1-tkg.1

To upgrade my-cluster using the photon OS:

tanzu cluster upgrade my-cluster --os-name photon

To upgrade my-cluster using v20.04 of the ubuntu OS:

tanzu cluster upgrade my-cluster --os-name ubuntu --os-version 20.04

To upgrade my-cluster using v20.04 of the ubuntu OS and the amd64 architecture:

tanzu cluster upgrade my-cluster --os-name ubuntu --os-version 20.04 --os-arch amd64

Flags

-h, --help

Help text.

-n, --namespace

The namespace of the cluster. When this flag is not specified, tanzu cluster upgrade targets the default namespace.

--os-arch

The OS architecture to use during the upgrade operation. Supported value is amd64. If --os-arch is not specified, tanzu cluster upgrade discovers this parameter automatically.

--os-name

The OS name to use during the upgrade operation. Supported values:

• ubuntu on vSphere (all TKG versions)
• ubuntu on AWS and Azure (TKG versions up to and including v2.4)
• photon on vSphere (all TKG versions)
• amazon on AWS (TKG versions up to and including v2.4)

If --os-name is not specified when upgrading a cluster, its nodes retain their existing --os-name setting.

--os-version

The OS version to use during the upgrade operation. Supported values:

• 22.04 for Ubuntu on vSphere (from TKG v2.5 onwards)
• 20.04 for Ubuntu on vSphere (all TKG versions)
• 20.04 for Ubuntu on AWS and Azure (TKG versions up to and including v2.4)
• 18.04 for Ubuntu on Azure (TKG versions up to and including v2.4)
• 5 for Photon on vSphere (from TKG v2.5 onwards)
• 5 and 3 for Photon on vSphere (all TKG versions)
• 2 for amazon on AWS (TKG versions up to and including v2.4)

If --os-version is not specified, tanzu cluster upgrade discovers this parameter automatically.

-t, --timeout

The time to wait for the cluster upgrade to complete. The default waiting time is 30m0s. Specify --timeout in hours (h), minutes (m), or seconds (s). For example, 2h, 30m, or 2h30m10s.

--tkr

The Tanzu Kubernetes release. If only the release prefix is specified (for example, v1.21.8), tanzu cluster upgrade uses the latest compatible Tanzu Kubernetes release matching the prefix.

--vsphere-vm-template-name

The path or name of the vSphere VM template to use for the cluster.

-y, --yes

When --yes is specified, tanzu cluster upgrade skips the confirmation step.