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 and Targets

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

The list of available command groups differs based on what Tanzu CLI plugins are installed on your machine, and on what type of server you are currently logged in to. Both of these depend on the Tanzu products that you are using.

For each command group the Tanzu CLI defines a Target, or context type, that associates the set of commands with the type of server that the commands apply to, for example:

  • Plugins that define commands for Kubernetes clusters have the Target k8s.
  • Plugins that define commands for TMC commands have the Target tmc.
  • Plugins that define context-independent commands have no Target.
  • Identically-named plugins for different targets let the Tanzu CLI tailor commands under command groups such as tanzu cluster to fit the context.

The tanzu plugin list command lists plugin targets under a TARGET column.

tanzu context commands let you specify a default specific server context for each target, switch targets, and list the contexts for each target using the --type flag.

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.
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 Activates auto-discovery of CLI plugins.
context-target-v2 true Allows you to create and manage Tanzu CLI contexts. For more information, see tanzu context.
This setting replaces context-target from previous versions of the Tanzu CLI. Setting context-target has no effect and may be removed from the CLI configuration.
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 (Technical Preview, 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 (Technical Preview, 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 (Technical Preview, vSphere only) Allows you to deploy dual-stack clusters, with IPv6 as the primary protocol. This feature is in development.
export-from-confirm true Activates 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 Allows you to deploy standalone clusters in Tanzu Community Edition. This feature is not available in Tanzu Kubernetes Grid.
cluster plugin features:
allow-legacy-cluster false Allows you to create plan-based clusters (legacy). By default, the Tanzu CLI creates class-based clusters.
auto-apply-generated-clusterclass-based-configuration false Auto-applies the class-based cluster configuration generated by the Tanzu CLI when you pass a legacy cluster configuration file to tanzu cluster create. When set to false, tanzu cluster create saves the configuration to a file without creating the cluster.
custom-nameservers false (Technical Preview, vSphere only) See management-cluster plugin features, above.
dual-stack-ipv4-primary false (Technical Preview, vSphere only) See management-cluster plugin features, above.
dual-stack-ipv6-primary false (Technical Preview, vSphere only) See management-cluster plugin features, above.
network-separation-beta Experimental. Do not enable. Reserved for future use.
package plugin features:
kctrl-command-tree true 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.

Activating and Deactivating Features

  • To activate a CLI feature:

    • To activate a global feature, run:

      tanzu config set features.global.FEATURE true

      Where FEATURE is the name of the feature that you want to activate.

    • To activate a plugin feature, run:

      tanzu config set features.PLUGIN.FEATURE true

      Where:

      • PLUGIN is the name of the CLI plugin. For example, cluster or management-cluster.
      • FEATURE is the name of the feature that you want to activate.

  • To deactivate a CLI feature:

    • To deactivate a global feature, run:

      tanzu config set features.global.FEATURE false

      Where FEATURE is the name of the feature that you want to deactivate.

    • To deactivate a plugin feature, run:

      tanzu config set features.PLUGIN.FEATURE false

      Where:

      • PLUGIN is the name of the CLI plugin. For example, cluster or management-cluster.
      • FEATURE is the name of the feature that you want to deactivate.

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.

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