Tanzu CLI Architecture and Configuration

This topic provides information about Tanzu CLI architecture. It also explains how to update your Tanzu CLI configuration.

Command Groups

Tanzu CLI commands are organized into command groups. To list available command groups, run tanzu.

The list of available command groups is different depending on the product that you are using and Tanzu CLI plugins that are installed on your machine. For more information about CLI plugins, see Tanzu CLI Architecture below.

CLI Architecture

The Tanzu CLI has a pluggable architecture. Tanzu CLI plugins contain CLI commands. Some plugins are available in the Tanzu CLI automatically while others are installed manually. The list of plugins that are available in the CLI automatically varies depending on the product that you are using.

Examples of Tanzu CLI plugins:

  • Default standalone plugins: For example, login or management-cluster.
  • Non-default standalone plugins: For example, apps or insight.
  • Context-scoped plugins: For example, cluster or kubernetes-release. These plugins are installed automatically after you add a server context, such as a standalone management cluster or Supervisor, to the Tanzu CLI.

For a list of Tanzu CLI plugins and commands that they provide, see Command Groups in Tanzu CLI Command Reference.

CLI Configuration

The Tanzu CLI configuration file, ~/.config/tanzu/config.yaml, contains your Tanzu CLI configuration, including:

  • Sources for CLI plugin discovery
  • Global and plugin-specific configuration options, or features
  • Names, contexts, and kubeconfig locations for the servers that the CLI knows about, and which is the current one

You can use the tanzu config set PATH VALUE and tanzu config unset PATH commands to customize your CLI configuration, as described in the table below. Running these commands updates the ~/.config/tanzu/config.yaml file.

Path Value Description
edition tkg (default), tce, and tce-standalone This path sets the Tanzu CLI edition. Default value is tkg. The edition path and the tanzu config set edition command are intended for installation scripts, used by Tanzu CLI developers. Do not set the Tanzu CLI edition manually, which includes running the tanzu config set edition command or updating the Tanzu CLI configuration file directly.*
env.VARIABLE Your variable value; for example, Standard_D2s_v3 This path sets or unsets global environment variables for the Tanzu CLI. For example, tanzu config set env.AZURE_NODE_MACHINE_TYPE Standard_D2s_v3. Variables set by running tanzu config set persist until you unset them with tanzu config unset. For a list of variables that you can set, see Configuration File Variable Reference.
features.global.FEATURE true or false This path activates or deactivates global features in your CLI configuration. Use only if you want to change or restore the defaults. For example, tanzu config set features.global.context-aware-cli-for-plugins true.
features.PLUGIN.FEATURE true or false This path activates or deactivates plugin-specific features in your CLI configuration. Use only if you want to change or restore the defaults; some of these features are experimental and intended for evaluation and test purposes only. For example, running tanzu config set features.cluster.dual-stack-ipv4-primary true sets the dual-stack-ipv4-primary feature of the cluster CLI plugin to true. By default, only production-ready plugin features are set to true in the CLI. For more information, see Experimental Features.
unstable-versions none (default), alpha, experimental, and all

This path sets the clientOptions.cli.unstableVersionSelector property in the CLI configuration file. By default, the Tanzu CLI uses only stable versions of CLI plugins. You can modify this behavior by setting unstable-versions to alpha, experimental, or all:

  • none: Allows only stable plugin versions. clientOptions.cli.unstableVersionSelector is set to none by default.
  • alpha: Allows stable and alpha plugin versions.
  • experimental: Allows stable and pre-release plugin versions, including alpha versions.
  • all: Allows all plugin versions, including stable, pre-release, and build-tagged versions.

To restore the default, set unstable-versions to none.

* In addition to the edition property, the Tanzu CLI also sets the bomrepo and compatibilityFilePath properties. Do not set these properties manually.

Features

Name Default Description
Global features:
context-aware-cli-for-plugins true Enables auto-discovery of CLI plugins.
tkr-version-v1alpha3-beta false Sets the API version for the kubernetes-release plugin to v1alpha3. Do not set; reserved for future use.
management-cluster plugin features:
aws-instance-types-exclude-arm true Excludes ARM-based instance types from the list of available instance types in the Tanzu Kubernetes Grid installer interface when deploying a management cluster to AWS. This feature is set by Tanzu Kubernetes Grid; do not set manually.
custom-nameservers false (Experimental, vSphere only) Allows you to configure custom DNS servers for control plane and worker nodes. This feature is in development.
dual-stack-ipv4-primary false (Experimental, vSphere only) Allows you to deploy dual-stack clusters, with IPv4 as the primary protocol. This feature is in development.
dual-stack-ipv6-primary false (Experimental, vSphere only) Allows you to deploy dual-stack clusters, with IPv6 as the primary protocol. This feature is in development.
export-from-confirm true Enables the Export Configuration button in the Tanzu Kubernetes Grid installer interface.
import false Allows you to import the cluster configuration file into the Tanzu Kubernetes Grid installer interface. This feature is not available in Tanzu Kubernetes Grid v1.6.
standalone-cluster-mode false Enables you to deploy standalone clusters in Tanzu Community Edition. This feature is not available in Tanzu Kubernetes Grid.
cluster plugin features:
custom-nameservers false See above.
dual-stack-ipv4-primary false See above.
dual-stack-ipv6-primary false See above.
package plugin features:
kctrl-package-command-tree false Activates or deactivates kctrl mode for tanzu package commands. This mode provides extended functionality for observability and debugging. For more information, see tanzu package with kctrl.

Sync Plugins

The tanzu plugin sync command installs the default standalone and context-scoped plugins that are included with your Tanzu CLI version. Installing these plugins is required if you want to create and manage Kubernetes clusters with the Tanzu CLI.

Examples:

  • Running tanzu plugin sync when you install the Tanzu CLI for the first time installs all of the standalone plugins that are available in the default discovery source for your Tanzu CLI version, including the login and management-cluster plugins.
  • When you target a server context with the tanzu login command, the Tanzu CLI automatically installs all of the required plugins for the server context, including the cluster and kubernetes-release plugins. Running tanzu plugin sync after you target a server context with tanzu login:
    • Checks if all of the required plugins for the server context are installed and if not, installs them.
    • Checks if the version of each installed plugin is supported and if not, updates the plugin to the recommended version.

For more information, see Sync Command in the Tanzu Framework repository. To install a single plugin, see Install a Single Plugin below.

Install a Single Plugin

If you want to install a Tanzu CLI plugin that was not automatically downloaded when running tanzu login or tanzu plugin sync, install it manually by following these steps.

  1. In a terminal, run:

    tanzu plugin install PLUGIN-NAME
    
  2. Verify that you installed the plugin successfully by running:

    tanzu plugin list
    

Install Local Plugins

If you want to install a Tanzu CLI plugin from a local directory, for example, a non-default standalone plugin, follow these steps.

  1. Download the plugin tar.gz file from the release artifacts for your distribution.

  2. Extract the tar.gz file to a location on your local machine using the extraction tool of your choice.

  3. From that location, run:

    tanzu plugin install all --local /PATH/TO/FILE/
    
  4. Verify that you installed the plugin successfully by running:

    tanzu plugin list
    
check-circle-line exclamation-circle-line close-line
Scroll to top icon