Tanzu CLI Architecture and Configuration

This topic explains the architecture of the Tanzu CLI and how to update your Tanzu CLI configuration.

Overview

The Tanzu CLI uses a context-scoped, pluggable architecture that lets you connect to servers of multiple types and run the appropriate commands on each. For example, you can use the Tanzu CLI to connect to these Tanzu products:

Tanzu Mission Control (TMC), to perform operations described in Capabilities of the Tanzu Mission Control Plug-ins in the TMC documentation.
Tanzu Applicaton Platform (TAP), to run tanzu apps, tanzu accelerator, and other commands described in Tanzu CLI Overview in the TAP documentation.
Tanzu Kubernetes Grid (TKG), as described in Creating and Managing TKG 2.5 Workload Clusters with the Tanzu CLI in the TKG documentation.

What you can connect to with the Tanzu CLI, what commands you can run, what those commands do, and how you can expand CLI functionality depend on abstractions described in the sections below.

CLI Core, Plugins, and Plugin Installation

Tanzu CLI commands are organized into command groups, which are the sets of commands that all start with the same words. To list your current available command groups, run tanzu.

The core CLI has some command groups built in, and CLI plugins extend the CLI with additional command groups that are useful for particular products. Each plugin is an executable binary that packages a group of CLI commands.

Most plugins need to be installed with the tanzu plugin install command, either in groups or individually:

Plugin groups: To install all the plugins typically needed for a facet of Tanzu with a single command, include the --group option. Plugin groups include TAP, vSphere, TKG, and others.
- Run tanzu plugin group search to see available groups, or see Command Groups, Plugins, and Plugin Groups below.
Individual plugins: Without the --groups option, tanzu plugin install installs CLI plugins individually.

Context-scoped plugins install themselves automatically when you switch the CLI to use a context that they apply to. Many plugins for Tanzu Mission Control, the tmc context type, are context-scoped, and so their commands are available without your having to run tanzu plugin install.

Targets and Context Types

The Tanzu CLI connects to Kubernetes clusters, product dashboards, and other API servers. Depending on what the CLI is connected to as a client, it changes the commands that it supports and what those commands do.

There are two sides to this interaction, client side and server side, which the Tanzu CLI represents as follows:

Target labels a set of plugins that are relevant to a type of server, to determine client-side behavior.
- Each CLI plugin is associated with one target, as listed in Command Groups, Plugins, and Plugin Groups below.
- Possible plugin targets are:
  - kubernetes or k8s for commands run on Kubernetes clusters, either directly or via Tanzu Platform hub
  - operations or ops for platform operation commands run on Tanzu Platform hub
  - mission-control or tmc for commands run on Tanzu Mission Control
  - global for commands that do not depend on what the CLI is connected to
- When you invoke a command provided by a plugin, the plugin’s target follows tanzu in the command, unless the target is global. For example with tanzu ops apply commands.
  - You can also omit the k8s target from command strings.
Context identifies the specific server that the Tanzu CLI connects to. You create these with tanzu context create and log in to them with tanzu context use.
- Each context has one of the following context types:
  - kubernetes or k8s for Kubernetes clusters
  - tanzu for Tanzu Platform hub
  - mission-control or tmc for Tanzu Mission Control
- You pass the context type to the -t or --type flag of tanzu context create when you create a context.

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

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

Command Groups, Plugins, and Plugin Groups

The Tanzu CLI includes the following commands and command groups.

Command functionality comes from either the core CLI or from CLI plugins. Each plugin is associated with a command group, which is a set of available commands that all start with the same words, for example tanzu imgpkg.

The table below lists Tanzu CLI command groups, along with:

Command Group: The base command string for the group, including its target where applicable.
- Core CLI commands and commands from plugins with target global do not include a target after tanzu.
- Commands from plugins include the plugin’s target (k8s, tmc, or ops), or omit it if the plugin’s target is global.
  - You can invoke commands that have target k8s without including the k8s.
  - The target determines the available commands under the command group.
Source: Where the commands come from, whether core CLI or a CLI plugin.
Context type: The type of server that the plugin commands typically apply to: k8s, tmc, or tanzu.
- You pass this to the -t or --type flag of tanzu context create when you create a context.
Plugin groups (or context-scoped): The plugin groups, if any, that install the plugin, or else “context-scoped” for plugins that install automatically.
- You pass a plugin group to the --group flag of tanzu plugin install when you install a group of plugins at once. You identify the group with a string that the table below abbreviates as follows:
  - TAP: vmware-tap/default
  - Tanzu Platform hub Dev: vmware-tanzu/app-developer
  - Tanzu Platform hub PE: vmware-tanzu/platform-engineer
  - TKG: vmware-tkg/default
  - TMC: vmware-tmc/default
  - vSphere: vmware-vsphere/default
- Additional installations:
  - The telemetry plugin is installed by vmware-tanzucli/essentials in addition to the TKG plugin group.
  - The TKG and vSphere plugin groups install the pinniped-auth plugin, which provides commands that are not normally invoked directly.

Command group	Source	Context type	Plugin groups (or context-scoped)
tanzu k8s accelerator	CLI plugin: `accelerator`	`k8s`	TAP
tanzu ops apply	CLI plugin: `apply`	`tanzu`	Tanzu Platform hub PE
tanzu k8s apps	CLI plugin: `apps`	`k8s`	TAP
tanzu app	CLI plugin: `appsv2`	`tanzu`	Tanzu Platform hub Dev, `global` target
tanzu availability-target	CLI plugin: `space`	`tanzu`	Tanzu Platform hub Dev, Tanzu Platform hub PE
tanzu k8s build-service	CLI plugin: `build-service`	`k8s`	TAP
tanzu k8s cluster	CLI plugin: `cluster`	`k8s`	context-scoped
tanzu ops cluster	CLI plugin: `cluster`	`tanzu`	Tanzu Platform hub PE
tanzu ops clustergroup	CLI plugin: `cluster`; Target: `operations`	`tanzu`	Tanzu Platform hub PE
tanzu completion	Core CLI	N/A - local CLI	N/A - system command
tanzu config	Core CLI	N/A - local CLI	N/A - system command
tanzu context	Core CLI	N/A - local CLI	N/A - system command
tanzu deploy	CLI plugin: `resource`	`tanzu`	Tanzu Platform hub Dev
tanzu k8s diagnostics	CLI plugin: `diagnostics`	`k8s`
tanzu k8s external-secrets	CLI plugin: `external-secrets`	`k8s`	TAP
tanzu k8s feature	CLI plugin: `feature`	`k8s`	context-scoped
tanzu ops iam	CLI plugin: `feature`	`tanzu`	Tanzu Platform hub PE
tanzu imgpkg	CLI plugin: `imgpkg`	N/A - local CLI	N/A - global plugin
tanzu init	Core CLI	N/A - local CLI	N/A - system command
tanzu k8s insight	CLI plugin: `insight`	`k8s`	TAP
tanzu isolated-cluster	CLI plugin: `isolated-cluster`	N/A - local CLI	N/A - global plugin
tanzu k8s kubernetes-release	CLI plugin: `kubernetes-release`	`k8s`	context-scoped
tanzu login	Core CLI	N/A - local CLI	N/A - system command
tanzu management-cluster	CLI plugin: `management-cluster`	`k8s`	TKG
tanzu namespaces	CLI plugin: `namespaces`	`k8s`	TAP
tanzu k8s package	CLI plugin: `package`	`k8s`	TAP, Tanzu Platform hub Dev, TKG, vSphere
tanzu plugin	Core CLI	N/A - local CLI	N/A - system command
tanzu ops policy	CLI plugin: `policy`	`tanzu`	Tanzu Platform hub PE
tanzu profile	CLI plugin: `space`	`tanzu`	Tanzu Platform hub Dev, Tanzu Platform hub PE
tanzu project	CLI plugin: `project`	`tanzu`	TAP, Tanzu Platform hub Dev
tanzu promote	CLI plugin: `resource`	`tanzu`	Tanzu Platform hub Dev
tanzu k8s secret	CLI plugin: `secret`	`k8s`	TAP, Tanzu Platform hub Dev, Tanzu Platform hub PE, TKG, vSphere
tanzu service-mesh	CLI plugin: `service-mesh`	`k8s`	N/A - global plugin
tanzu k8s services	CLI plugin: `services`	`k8s`	TAP
tanzu space	CLI plugin: `space`	`tanzu`	Tanzu Platform hub Dev, Tanzu Platform hub PE
tanzu telemetry	CLI plugin: `telemetry`	N/A - local CLI	N/A - global plugin
tanzu k8s telemetry	CLI plugin: `telemetry`	`k8s`	`TKG`
tanzu trait	CLI plugin: `space`	`tanzu`	Tanzu Platform hub Dev, Tanzu Platform hub PE
tanzu version	Core CLI	N/A - local CLI	N/A - system command

CLI Usage Scenarios

The table below lists Tanzu CLI use cases with the following properties:

Why groups: What is the overall usage scenario.
Context: What the CLI is connecting to, grouped by why.
Context Type: Tanzu CLI context --type, or else N/A for the local CLI itself.
Target: Target for the relevant CLI plugins.
Plugin Group: CLI plugin group for the relevant CLI plugins, listed as in the Command Groups, Plugins, and Plugin Groups table above.

Context	Context Type	Target	Plugin Group
Why: CLI Operations: configure CLI options, install plugins, manage contexts, etc.
The CLI itself	N/A - local	N/A - CLI core and `global` target	N/A
Why: Platform Management: infrastructure, clusters, spaces, packaged services, monitoring, etc.
Tanzu Platform hub, for platform ops	`tanzu`	`ops`	Tanzu Platform hub PE
TKG Supervisor	`k8s`	`k8s`	vSphere
TKG standalone management cluster	`k8s`	`k8s`	TKG
Tanzu Mission Control	`tmc`	`tmc`	TMC
Why: Application Operations: develop, deploy, manage, and optimize apps.
Any Kubernetes workload cluster	`k8s`	`k8s`	TAP
Tanzu Platform hub, for apps managed across multiple clusters	`tanzu` or `k8s`	`k8s`	Tanzu Platform hub Dev

Tanzu 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
`env.VARIABLE`	Your variable value; for example, `TANZU_CLI_CEIP_OPT_IN_PROMPT_ANSWER`	This path sets or unsets global environment variables for the Tanzu CLI. For example, `tanzu config set env.TANZU_CLI_CEIP_OPT_IN_PROMPT_ANSWER Yes`. 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.
Deprecated: `bomRepo`, `compatibilityFilePath`, `edition`	N/A	Retained for backward-compatibility with older versions of the Tanzu CLI that were bundled with TKG. Do not set.

Features

Name	Default	Description
Global features:
`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. NOTE: Deploying management clusters to AWS is not supported from the TKG v2.5 version of the `tanzu management-cluster` commands onwards. Use the `ekscluster` commands from the Tanzu Mission Control CLI plugins to deploy EKS clusters on AWS, or deploy EKS clusters directly from the Tanzu Mission Control interface.
`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.
`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.