Tanzu Community Edition


Unmanaged Clusters Reference

This is the reference documentation for the unmanaged-cluster plugin. If this is your first time deploying an unmanaged cluster, see Getting Started with Unmanaged Clusters.

Command aliases

As a Tanzu CLI plugin, unmanaged clusters can be interacted with using tanzu unmanaged-cluster. uc, um, and unmanaged are all valid aliases for the command. This means the following commands equate to the same:

  • tanzu unmanaged-cluster create hello
  • tanzu uc create hello
  • tanzu um create hello
  • tanzu unmanaged create hello

Creating clusters

create is used to create a new cluster. By default, it:

  1. Installs a cluster using kind.
  2. Installs kapp-controller.
  3. Installs a core package repository.
  4. Installs a user-managed package repository.
  5. Installs a CNI package.
    • defaults to antrea.
  6. Sets your kubeconfig context to the newly created cluster.

To create a cluster, run:

tanzu unmanaged-cluster create ${CLUSTER_NAME}

Listing clusters

list or ls is used to list all known clusters. To list known clusters, run:

tanzu unmanaged-cluster list

Deleting clusters

delete or rm is used to delete a cluster. It will:

  1. Attempt to delete the cluster based on the provider.
    • by default, clusters use kind, this will delete the kind cluster.
  2. Attempt to remove the cluster’s directory.
    • located at ~/.config/tanzu/tkg/unmanaged/${CLUSTER_NAME}/.

To delete a cluster, run:

tanzu unmanaged-cluster delete ${CLUSTER_NAME}

Custom configuration

To create a configuration file for cluster creation, run:

tanzu unmanaged-cluster config create ${CLUSTER_NAME}

This will create a configuration file, which you can modify to change how clusters are created. When creating a cluster, the -f flag can be used to specify this configuration file.

Along with a configuration file, unmanaged-cluster respects settings from other settings such as flags. The order in which settings are resolved is:

  1. Defaults (lowest precedence)
  2. Configuration File
  3. Environment Variables
  4. Flags (highest precedence)

As a result of rendering the above, a final configuration file is persisted to:


Reviewing this file can help in troubleshooting issues during cluster bootstrapping.

Install to existing cluster

If you wish to install the Tanzu components, such as kapp-controller and the package repositories into an existing cluster, you can do so with the --existing-cluster-kubeconfig/e flags or existingClusterKubeconfig configuration field. The following example demonstrates installing into an existing minikube cluster.

  1. Create a minikube cluster.

    $ minikube start
    * minikube v1.24.0 on Arch rolling
    * Automatically selected the docker driver. Other choices: kvm2, ssh
    * Starting control plane node minikube in cluster minikube
    * Pulling base image ...
    * Preparing Kubernetes v1.22.3 on Docker 20.10.8 ...
      - Generating certificates and keys ...
      - Booting up control plane ...
      - Configuring RBAC rules ...
    * Verifying Kubernetes components...
      - Using image gcr.io/k8s-minikube/storage-provisioner:v5
    * Enabled addons: storage-provisioner, default-storageclass
    * Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default
  2. Install the unmanaged cluster components

    tanzu unmanaged-cluster create -e ~/.kube/config --cni=none
    • ~/.kube/config is the location of the kubeconfig used to access the minikube cluster.
    • --cni=none is set since minikube already sets up a network for pods.
  3. Now you can use the tanzu CLI to interact with the cluster.

    tanzu package list -A

Disable CNI installation

To create a cluster without a CNI installed, run:

tanzu unmanaged-cluster create --cni=none

This will skip CNI installation and prompt the following during the CNI installation step.

🌐 Installing CNI
   No CNI installed: CNI was set to none.

The cluster creation will complete successfully. After that, you are free to install a CNI into the cluster.

Customize the distribution

Unmanaged clusters gather details on how to create a cluster from a Tanzu Kubernetes Release (TKr) file. For each release of unmanaged clusters, a default TKr is set.

When creating clusters, you can point to a different TKr using the --tkr flag. The TCE project keeps TKrs for unmanaged clusters at projects.registry.vmware.com/tce/tkr. Using imgpkg, you can query available TKrs using:

$ imgpkg tag list -i projects.registry.vmware.com/tce/tkr


To create a cluster with an alternative TKr, you can run:

tanzu unmanaged-cluster create --tkr projects.registry.vmware.com/tce/tkr:v1.22.2

To customize a TKr, you can pull an existing one down using imgpkg:

$ imgpkg pull -i projects.registry.vmware.com/tce/tkr:v1.22.2 -o tkr
Pulling image 'projects.registry.vmware.com/tce/tkr@sha256:7c1a241dc57fe94f02be4dd6d7e4b29f159415417164abc4b5ab6bb10cf4cbaa'
Extracting layer 'sha256:e17e901811682a2c8c91c8865f3344a21fdf8f83f012de167c15d2ab06cc494a' (1/1)


You can then edit the above TKr in the tkr/tkr-bom-v1.22.2.yaml. After modifying it, you may also wish to rename the YAML file. Once you have made your modifications, you can repush it using:

imgpkg push -f ./tkr/tkr-bom-CUSTOM.yaml -i ${YOUR_REGISTRY}:${YOUR_TAG}

Once pushed, you can reference this repo using the --tkr flag.


This section details known limitations of unmanaged clusters.

Can’t Upgrade Kubernetes

By design, unmanaged-clusters do not lifecycle-manage Kubernetes. They are not meant to be long-running with real workloads. To change Kubernetes versions, delete the existing cluster and create a new cluster with a different configuration.

Join us!

Our open community welcomes all users and contributors