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.

In a terminal, run:
```
tanzu plugin install PLUGIN-NAME
```
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.

Download the plugin tar.gz file from the release artifacts for your distribution.
Extract the tar.gz file to a location on your local machine using the extraction tool of your choice.

From that location, run:

tanzu plugin install all --local /PATH/TO/FILE/

Verify that you installed the plugin successfully by running:
```
tanzu plugin list
```