This section includes tips to help you to troubleshoot common problems that you might encounter when installing Tanzu Kubernetes Grid and deploying Tanzu Kubernetes clusters.

Many of these procedures use the kind CLI on your bootstrap machine. To install kind, see Installation in the kind documentation.

Management Cluster Deployment Logs

To review and troubleshoot management cluster deployments, refer to:

  • The log file listed in the terminal output Logs of the command execution can also be found at...

  • The log from your cloud provider module for Cluster API. Retrieve the most recent one as follows:

    1. Search your tkg init output for Bootstrapper created. Kubeconfig: and copy the kubeconfig file path listed. The file is in ~/.kube-tkg/tmp/.
    2. Run the following, based on your cloud provider:
      • vSphere: kubectl logs deployment.apps/capv-controller-manager -n capv-system manager --kubeconfig </path/to/kubeconfig>
      • Amazon EC2: kubectl logs deployment.apps/capa-controller-manager -n capa-system manager --kubeconfig </path/to/kubeconfig>
      • Azure: kubectl logs deployment.apps/capz-controller-manager -n capz-system manager --kubeconfig </path/to/kubeconfig>

Monitor Workload Cluster Deployments in Cluster API Logs

After running tkg create cluster, you can monitor the deployment process in the Cluster API logs on the management cluster.

To access these logs, follow the steps below:

  1. Set kubeconfig to your management cluster. For example:

    kubectl config use-context my-management-cluster-admin@my-management-cluster
  2. Run the following:

    • capi logs:

      kubectl logs deployments/capi-controller-manager -n capi-system manager
    • IaaS-specific logs:

      • vSphere: kubectl logs deployments/capv-controller-manager -n capv-system manager
      • Amazon EC2: kubectl logs deployments/capa-controller-manager -n capa-system manager
      • Azure: kubectl logs deployments/capz-controller-manager -n capz-system manager

Clean Up Bootstrap Machine After Unsuccessful Management Cluster Deployments


Unsuccessful attempts to deploy Tanzu Kubernetes Grid can leave Docker objects in your bootstrap machine, which consume resources.


To clean up after attempts to deploy the management cluster fail, remove the Docker containers, images, and volumes that are left behind.

CAUTION: These steps remove all Docker containers, images, and volumes from your system. If you are running Docker processes that are not related to Tanzu Kubernetes Grid on this system, do no run these commands. Remove unneeded containers, images, and volumes individually.

  1. Remove all kind clusters.

    kind get clusters | xargs -n1 kind delete cluster --name
  2. Remove all containers.

    docker rm -f $(docker ps -aq)
  3. Remove all container images.

    docker rmi -f $(docker images -aq)
  4. Remove all orphaned Docker volumes.

    docker system prune --all --volumes -f

Clean Up Cloud Account After Unsuccessful Management Cluster Deployments


Unsuccessful attempts to deploy a management cluster leave orphaned objects in your vSphere instance or AWS account.


There are different ways to clean up unsuccessful deployments. Attempt these methods in the following order of preference.

  1. Run kubectl delete to delete the cluster manually.

    If the deployment of the management cluster fails, the Tanzu Kubernetes Grid CLI provides a help message to inform you of the location of kubeconfig file of the bootstrap cluster, and prompts you to run the following command, replacing UUID with the ID provided in the help message.

     kubectl delete -n tkg-system --kubeconfig ~/.kube-tkg/tmp/config-UUID 

  2. Remove the kind container, replacing unique_ID with the ID provided in the help message.
     docker rm -v tkg-kind-unique_ID-control-plane -f 
  3. Clean up the objects in your cloud infrastructure:
    • vSphere: Locate the VMs created, power them off and delete them from your system.
    • AWS: Use a tool such as aws-nuke with a specific configuration to delete the objects from Amazon EC2. Or log in to your Amazon EC2 dashboard and delete the objects manually in the console.
    • Azure: In Resource Groups, open your AZURE_RESOURCE_GROUP. Use checkboxes to select and Delete resources just created, which contain a timestamp in their names.

Kind Cluster Remains after Deleting Management Cluster


Running tkg delete management-cluster removes the management cluster, but fails to delete the local kind cluster from the bootstrap machine.


  1. List all running kind clusters and remove the one that looks like tkg-kind-unique_ID

    kind delete cluster --name tkg-kind-unique_ID
  2. List all running clusters and identify the kind cluster.

    docker ps -a
  3. Copy the container ID of the kind cluster and remove it.

    docker kill container_ID

Deploying a Tanzu Kubernetes Cluster Times Out, but the Cluster is Created


Running tkg create cluster fails with a timeout error similar to the following:

I0317 11:11:16.658433 clusterclient.go:341] Waiting for resource my-cluster of type *v1alpha3.Cluster to be up and running
E0317 11:26:16.932833 common.go:29]
Error: unable to wait for cluster and get the cluster kubeconfig: error waiting for cluster to be provisioned (this may take a few minutes): cluster control plane is still being initialized
E0317 11:26:16.933251 common.go:33]
Detailed log about the failure can be found at: /var/folders/_9/qrf26vd5629_y5vgxc1vjk440000gp/T/tkg-20200317T111108811762517.log

However, if you run tkg get cluster, the cluster appears to have been created.



my-cluster	Provisioned


  1. Use the tkg get credentials command to add the cluster credentials to your kubeconfig.

    tkg get credentials my-cluster
  2. Set kubectl to the cluster's context.

    kubectl config set-context my-cluster@user
  3. Check whether the cluster nodes are all in the ready state.

    kubectl get nodes
  4. Check whether all of the pods are up and running.

    kubectl get pods -A
  5. If all of the nodes and pods are running correctly, your Tanzu Kubernetes cluster has been created successfully and you can ignore the error.

  6. If the nodes and pods are not running correctly, attempt to delete the cluster.

    tkg delete cluster my-cluster
  7. If tkg delete cluster fails, use kubectl to delete the cluster manually.

Pods are stuck in pending on cluster due to vCenter connectivity


When you run kubectl get pods -A on the created cluster, some pods remain in pending.

You run kubectl describe pod -n pod-namespace pod-name on an affected pod and review events and see the following event:

n node(s) had taint { true}, that the pod didn't tolerate


Ensure there is connectivity and firewall rules in place to ensure communication between the cluster and vCenter.

Tanzu Kubernetes Grid UI does not display correctly on Windows


When you run the tkg init --ui command on a Windows system, the UI opens in your default browser, but the graphics and styling are not applied. This happens because a Windows registry is set to application/x-css.


  1. In Windows search, enter regedit to open the Registry Editor utility.
  2. Expand HKEY_CLASSES_ROOT and select .css.
  3. Right-click Content Type and select Modify.
  4. Set the Value to text/css and click OK.
  5. Run the tkg init --ui command again to relaunch the UI.

Running tkg init on Mac OS results in kubectl version error


If you run the tkg init command on Mac OS with the latest stable version of Docker Desktop, tkg init fails with the error message:

Error: : kubectl prerequisites validation failed: kubectl client version v1.15.5 is less than minimum supported kubectl client version 1.17.0

This happens because Docker Desktop symlinks kubectl 1.15 into the path.


Place a newer supported version of kubectl in the path before Docker's version.

Connect to Cluster Nodes with SSH

You can use SSH to connect to individual nodes of management clusters or Tanzu Kubernetes clusters. To do so, the SSH key pair that you created when you deployed the management cluster must be available on the machine on which you run the SSH command. Consquently, you must run ssh commands on the machine on which you run tkg commands.

The SSH keys that you register with the management cluster, and consequently that are used by any Tanzu Kubernetes clusters that you deploy from the management cluster, are associated with the following user accounts:

  • vSphere management cluster and Tanzu Kubernetes nodes: capv
  • Amazon EC2 bastion nodes: ubuntu
  • Amazon EC2 management cluster and Tanzu Kubernetes nodes: ec2-user

To connect to a node by using SSH, run one of the following commands from the machine that you use as the bootstrap machine:

  • vSphere nodes: ssh capv@node_IP_address
  • Amazon EC2 bastion: ssh ubuntu@bastion_IP_address
  • Amazon EC2 nodes: ssh ec2-user@node_IP_address
  • Azure nodes: ssh capi@node_IP_address

Because the SSH key is present on the system on which you are running the ssh command, no password is required.

Recover Management Cluster Credentials

If you have lost the credentials for a management cluster, for example by inadvertently deleting the .kube-tkg/config file on the system on which you run tkg commands, you can recover the credentials from the management cluster control plane node.

  1. Run tkg get management-cluster to recreate the .kube-tkg/config file.
  2. Obtain the public IP address of the management cluster control plane node, from vSphere, Amazon EC2, or Azure.
  3. Use SSH to log in to the management cluster control plane node.

    • vSphere: ssh capv@node_IP_address
    • Amazon EC2: ssh ec2-user@node_IP_address
    • Azure: ssh capi@node_IP_address
  4. Access the admin.conf file for the management cluster.

    sudo vi /etc/kubernetes/admin.conf

    The admin.conf file contains the cluster name, the cluster user name, the cluster context, and the client certificate data.

  5. Copy the cluster name, the cluster user name, the cluster context, and the client certificate data into the .kube-tkg/config file on the system on which you run tkg commands.

Disable nfs-utils on Photon OS Nodes


In Tanzu Kubernetes Grid v1.1.2 and later, nfs-utils is enabled by default. If you do not require nfs-utils, you can remove it from cluster node VMs.


To disable nfs-utils on clusters that you deploy with Tanzu Kubernetes Grid v1.1.2 or later, use SSH to log in to the cluster node VMs and run the following command:

tdnf erase nfs-utils

For information about using nfs-utils on clusters deployed with Tanzu Kubernetes Grid v1.0 or 1.1.0, see Enable or Disable nfs-utils on Photon OS Nodes in the VMware Tanzu Kubernetes Grid 1.1.x Documentation.

check-circle-line exclamation-circle-line close-line
Scroll to top icon