Installing and Managing Packages with the Tanzu CLI

This topic describes how to install and manage packages and package repositories using the Tanzu CLI.

Note: The tanzu package CLI plugin is intended only for CLI-managed packages. Do not use the commands provided in this topic to install and manage any of the packages in the tanzu-core package repository or to manage the tanzu-core package repository itself. Their lifecycle is managed automatically by Tanzu Kubernetes Grid. For more information, see Install and Configure Packages.

Overview

Using the Tanzu CLI, you can install packages from the built-in tanzu-standard package repository or from other package repositories that you add to your target cluster.

For instructions on how to install and manage packages using the Tanzu CLI, see the sections below.

  • Package Repositories: See this section if you want to:

    • List all package repositories available for or added to the target cluster
    • Get the details of an available or added package repository
    • Add, update, or delete a package repository
  • Packages: See this section if you want to:

    • List all packages available to or installed in the target cluster
    • Get the details of an available or installed package
    • Install, update, or delete a package

For information about prerequisites, package dependencies, and step-by-step instructions on how to configure and install each of the packages in the tanzu-standard package repository, see the CLI-Managed Packages topic.

Package Namespaces and System Namespaces

You install package repositories and packages to the namespace of your choice, which defaults to default, except for Contour and Harbor packages upgraded from TKG v1.3 extensions as described in Namespace Exceptions for Upgraded Contour and Harbor below.

The components of the packaged services run in a system namespace that is separate from where packages themselves are deployed. For example, Contour and Envoy components run in the namespace tanzu-system-ingress and Harbor components run in tanzu-system-registry. System namespace names begin with tanzu-system-, except for the Cert Manager package, whose components run in the namespace cert-manager.

Do not install packages to any tanzu-system- namespace or to the cert-manager namespace except as described below.

Namespace Exceptions for Upgraded Contour and Harbor

When upgrading the Contour or Harbor packages from TKG v1.3 extensions, you install them into the namespaces where the original v1.3 extensions ran, for example:

  • Contour: tanzu-system-ingress
  • Harbor: tanzu-system-registry

To install Contour and Harbor packages new in TKG v1.4+, not upgraded from v1.3, use different namespace names as described in Package Namespaces and System Namespaces above.

Package Repositories

The sections below describe how to list, add, update, and delete package repositories.


Command Description
tanzu package repository list Lists all package repositories.
tanzu package repository get Shows the details of a package repository.
tanzu package repository add Adds a package repository.
tanzu package repository update Updates a package repository.
tanzu package repository delete Removes a package repository.

The --kubeconfig and --namespace flags:

Flag Description
–kubeconfig The path to the kubeconfig file of the target cluster. You can use this flag to point the Tanzu CLI to a cluster other than the current default, without changing the current context of your kubectl. For example, if the context of your kubectl is set to a management cluster and you do not want to change it, you can use the –kubeconfig flag to run the above tanzu package repository commands against a workload cluster.
–namespace The target namespace. If this flag is not specified, the Tanzu CLI uses the default namespace.

List Package Repositories

The tanzu package repository list command lists all package repositories. This includes package repositories that are automatically available in every cluster and package repositories that have been added to the target cluster by running the tanzu package repository add command.

  • To list package repositories across all namespaces in the target cluster, run:

    tanzu package repository list -A
    

    For example:

    tanzu package repository list -A
    / Retrieving repositories...
     NAME            REPOSITORY                                                                      STATUS               DETAILS  NAMESPACE
     tanzu-standard  projects.registry.vmware.com/tkg/packages/standard/repo:v1.4.0                  Reconcile succeeded           tanzu-package-repo-global
     tanzu-core      projects.registry.vmware.com/tkg/packages/core/repo:v1.21.8_vmware.1-tkg.1      Reconcile succeeded           tkg-system
    
  • To list package repositories in a specific namespace, run:

    tanzu package repository list -n NAMESPACE
    

    Where NAMESPACE is the target namespace. The --namespace, or -n, option is required if you want to list package repositories in a namespace other than default. For example:

    tanzu package repository list -n tanzu-package-repo-global
    \ Retrieving repositories...
    NAME            REPOSITORY                                                         STATUS               DETAILS
    tanzu-standard  projects.registry.vmware.com/tkg/packages/standard/repo:v1.4.0     Reconcile succeeded
    

    To list package repositories in the default namespace, you can run:

    tanzu package repository list
    

Get the Details of a Package Repository

The tanzu package repository get command retrieves the details of a package repository.

To retrieve the details of a package repository, run:

tanzu package repository get REPOSITORY-NAME -n REPOSITORY-NAMESPACE

Where:

  • REPOSITORY-NAME is the name of the package repository in the target cluster.
  • REPOSITORY-NAMESPACE is the namespace of the package repository in the target cluster.

For example:

tanzu package repository get tanzu-standard -n tanzu-package-repo-global
\ Retrieving repository tanzu-standard...
NAME:          tanzu-standard
VERSION:       4696927
REPOSITORY:    projects.registry.vmware.com/tkg/packages/standard/repo:v1.4.0
STATUS:        Reconcile succeeded
REASON:

Add a Package Repository

The tanzu package repository add command adds a package repository. Use this command if you want to install CLI-managed packages from a repository other than tanzu-standard.

NOTE: You cannot add a Tanzu Community Edition (TCE) package repository to a cluster created by Tanzu Kubernetes Grid. TCE packages are incompatible with TKG.

To add a package repository to the target cluster, run:

tanzu package repository add REPOSITORY-NAME --url REPOSITORY-URL -n REPOSITORY-NAMESPACE

Where:

  • REPOSITORY-NAME is a name you choose for the package repository.
  • REPOSITORY-URL is the OCI registry URL of the package repository, typically under projects.registry.vmware.com/tkg. This URL cannot be under projects.registry.vmware.com/tce.
  • REPOSITORY-NAMESPACE is the target namespace for the package repository. If this option is not specified, the Tanzu CLI adds the package repository to the default namespace.

If the target namespace does not exist in the cluster, you can create it by running the command below:

tanzu package repository add REPOSITORY-NAME --url REPOSITORY-URL -n REPOSITORY-NAMESPACE --create-namespace

The --create-namespace flag creates the namespace if does not exist in the target cluster.

Update a Package Repository

The tanzu package repository update command updates a package repository with a new version published at a URL. Before updating the package repository, obtain the URL to the new package repository from the Tanzu Kubernetes Grid Bill of Materials (BoM) file, which is available at ~/.config/tanzu/tkg/bom/.

NOTE: Do not update the tanzu-standard package repository if the target cluster is connected to VMware Tanzu Mission Control.

To update a package repository in the target cluster, run:

tanzu package repository update REPOSITORY-NAME --url REPOSITORY-URL -n REPOSITORY-NAMESPACE

Where:

  • REPOSITORY-NAME is the name of the package repository in the cluster.
  • REPOSITORY-URL is the new URL of the package repository. Obtain this URL from the Tanzu Kubernetes Grid Bill of Materials (BoM) file, which is the tkr- file in your local ~/.config/tanzu/tkg/bom/ directory. The URL follows the format IMAGE-REPO/IMAGE-PATH, where:

    • IMAGE-REPO is the BoM’s value for imageConfig.imageRepository
    • IMAGE-PATH is the BoM’s value for components.tkg-standard-packages.images.tanzuStandardPackageRepositoryImage.imagePath
  • REPOSITORY-NAMESPACE is the namespace of the package repository in the cluster.

If the package repository that you are updating does not exist in your target cluster, you can create it by running the following command:

tanzu package repository update REPOSITORY-NAME --url REPOSITORY-URL -n REPOSITORY-NAMESPACE --create

The --create flag creates the package repository if it does not exist in the target cluster.

Delete a Package Repository

The tanzu package repository delete command removes a package repository. Do not remove the tanzu-standard package repository. Because the tanzu-standard package repository is automatically enabled in all clusters, its lifecycle is managed by Tanzu Kubernetes Grid.

To delete a package repository from the target cluster, run:

tanzu package repository delete REPOSITORY-NAME -n REPOSITORY-NAMESPACE

Where:

  • REPOSITORY-NAME is the name of the package repository.
  • REPOSITORY-NAMESPACE is the namespace of the package repository.

Packages

The sections below describe how to list, install, update, and delete packages.


Command Description
tanzu package available list Lists all available packages and package versions.
tanzu package available get Shows the details of an available package.
tanzu package installed list Lists all installed packages.
tanzu package installed get Shows the details of an installed package.
tanzu package install Installs a package.
tanzu package installed create Same as tanzu package install.
tanzu package installed update Updates a package.
tanzu package installed delete Deletes a package.

The --kubeconfig and --namespace flags:

Flag Description
–kubeconfig The path to the kubeconfig file of the target cluster. You can use this flag to point the Tanzu CLI to a cluster other than the current default, without changing the current context of your kubectl. For example, if the context of your kubectl is set to a management cluster and you do not want to change it, you can use the –kubeconfig flag to run the above tanzu package commands against a workload cluster.
–namespace The target namespace. If this flag is not specified, the Tanzu CLI uses the default namespace.

List Available Packages

The tanzu package available list command lists all available packages and package versions.

List available packages:

  • To list available packages across all namespaces in the target cluster, run:

    tanzu package available list -A
    
  • To list available packages in a specific namespace, run:

    tanzu package available list -n NAMESPACE
    

    Where NAMESPACE is the namespace from which you want to retrieve the list of available packages. To list available packages in the default namespace, you can also run:

    tanzu package available list
    

    The CLI-managed packages from the tanzu standard package repository are available in each namespace in the cluster.

List available package versions:

  • To list available package versions for a package across all namespaces in the target cluster, run:

    tanzu package available list AVAILABLE-PACKAGE-NAME -A
    

    Where AVAILABLE-PACKAGE-NAME is the package name that you retrieved by running the tanzu package available list command.

    For example:

    tanzu package available list contour.tanzu.vmware.com -A
    \ Retrieving package versions for contour.tanzu.vmware.com...
    NAME                      VERSION                           RELEASED-AT           NAMESPACE
    contour.tanzu.vmware.com  1.17.1+vmware.1-tkg.1             2021-07-23T18:00:00Z  tanzu-package-repo-global
    
  • To list available package versions for a package in a specific namespace, run:

    tanzu package available list AVAILABLE-PACKAGE-NAME -n AVAILABLE-PACKAGE-NAMESPACE
    

    Where:

    • AVAILABLE-PACKAGE-NAME is the package name that you retrieved by running the tanzu package available list command.
    • AVAILABLE-PACKAGE-NAMESPACE is the namespace of the available package.

    For example:

    tanzu package available list contour.tanzu.vmware.com -n my-packages
    \ Retrieving package versions for contour.tanzu.vmware.com...
    NAME                      VERSION                           RELEASED-AT
    contour.tanzu.vmware.com  1.17.1+vmware.1-tkg.1             2021-07-23T18:00:00Z
    

    To list available package versions for a package in the default namespace, you can also run:

    tanzu package available list AVAILABLE-PACKAGE-NAME
    

Get the Details of an Available Package

The tanzu package available get command retrieves the details of an available package.

To retrieve the details of an available package, run:

tanzu package available get AVAILABLE-PACKAGE-NAME -n AVAILABLE-PACKAGE-NAMESPACE

Or:

tanzu package available get AVAILABLE-PACKAGE-NAME/AVAILABLE-PACKAGE-VERSION -n AVAILABLE-PACKAGE-NAMESPACE

Where:

  • AVAILABLE-PACKAGE-NAME is the name of the available package. You can retrieve this name by running the tanzu package available list command.
  • AVAILABLE-PACKAGE-VERSION is the version of the available package. You can retrieve the list of available package versions by running the tanzu package available list AVAILABLE-PACKAGE-NAME command.
  • AVAILABLE-PACKAGE-NAMESPACE is the namespace of the available package.

For example:

tanzu package available get contour.tanzu.vmware.com/1.17.1+vmware.1-tkg.1 -n tanzu-package-repo-global

To retrieve the values schema of an available package, including the default value for each key, use --values-schema flag of the tanzu package available get command. This retrieves the valuesSchema section from the Package Kubernetes API resource for the available package. You can set the output format, -o, for the values schema to yaml, json, or table. For example:

tanzu package available get contour.tanzu.vmware.com/1.17.1+vmware.1-tkg.1 -n tanzu-package-repo-global --values-schema -o yaml

You use this information when preparing the configuration file for your package. See Install a Package below.

List Installed Packages

The tanzu package installed list command lists all packages that are currently installed in the target cluster.

To list installed packages across all namespaces in a cluster, run:

tanzu package installed list -A

To list installed packages in a specific namespace, run:

tanzu package installed list -n NAMESPACE

Where NAMESPACE is the namespace from which you want to retrieve the list of installed packages. For example:

tanzu package installed list -n my-packages
\ Retrieving installed packages...
  NAME          PACKAGE-NAME                   PACKAGE-VERSION                   STATUS
  cert-manager  cert-manager.tanzu.vmware.com  1.1.0+vmware.1-tkg.2              Reconcile succeeded
  contour       contour.tanzu.vmware.com       1.17.1+vmware.1-tkg.1             Reconcile succeeded
  harbor        harbor.tanzu.vmware.com        2.2.3+vmware.1-tkg.1              Reconcile succeeded

Get the Details of an Installed Package

The tanzu package installed get command retrieves the details of an installed package.

To retrieve the details of an installed package, run:

tanzu package installed get INSTALLED-PACKAGE-NAME -n INSTALLED-PACKAGE-NAMESPACE

Where:

  • INSTALLED-PACKAGE-NAME is the name of the installed package.
  • INSTALLED-PACKAGE-NAMESPACE is the namespace in which the package is installed.

If you want to save the current configuration of an installed package to a file, run:

tanzu package installed get INSTALLED-PACKAGE-NAME -n INSTALLED-PACKAGE-NAMESPACE -f FILE-PATH

Where FILE-PATH is the path to the file. For example, values.yaml.

Install a Package

The tanzu package install command installs a CLI-managed package.

To install a CLI-managed package in the target cluster:

  1. If you want to install a package from a package repository other than tanzu-standard, add the package repository that contains the package. See Add a Package Repository above.

  2. Note the name and the version of the package that you want to install. To see the package name and version, run the tanzu package available list command. See List Available Packages above.

  3. Install the package:

    • If the target namespace exists in the cluster, run:

      tanzu package install PACKAGE-NAME -p AVAILABLE-PACKAGE-NAME -v AVAILABLE-PACKAGE-VERSION -f PACKAGE-CONFIGURATION-FILE -n PACKAGE-NAMESPACE
      
    • If the target namespace does not exist in the cluster, run:

      tanzu package install PACKAGE-NAME -p AVAILABLE-PACKAGE-NAME -v AVAILABLE-PACKAGE-VERSION -f PACKAGE-CONFIGURATION-FILE -n PACKAGE-NAMESPACE --create-namespace
      

    Where:

    • PACKAGE-NAME is a name you choose for the package.
    • AVAILABLE-PACKAGE-NAME is the package name you noted above.
    • AVAILABLE-PACKAGE-VERSION is the package version you noted above.
    • PACKAGE-CONFIGURATION-FILE is the configuration file that you prepared for the package. If this option is not specified, the package is installed with the default configuration.
    • PACKAGE-NAMESPACE is the namespace in which to install the package (PackageInstall), package app (App), and any other Kubernetes resources that describe the package. For example, the my-packages or tanzu-cli-managed-packages namespace. If the -n flag is not specified, the Tanzu CLI uses the default namespace. Do not install the contents of the package, such as pods and services, into this namespace. The namespace for the package contents is set separately, in the package configuration.

    To see the full list of supported flags for this command, use the --help option.

    For example:

    tanzu package install contour -p contour.tanzu.vmware.com -v 1.17.1+vmware.1-tkg.1 -f contour-data-values.yaml -n my-packages
    
  4. To confirm that the package has been installed, run the tanzu package installed list command. See List Installed Packages above.

Update a Package

The tanzu package installed update updates the current version and configuration of a CLI-managed package:

To update the version of a CLI-managed package, run:

tanzu package installed update INSTALLED-PACKAGE-NAME -v TARGET-PACKAGE-VERSION -n INSTALLED-PACKAGE-NAMESPACE

Where:

  • INSTALLED-PACKAGE-NAME is the name that you chose for the package. To see the name of the package, you can run the tanzu package installed list command. For more information, see List Installed Packages.
  • TARGET-PACKAGE-VERSION is the version that you want to update the package to.
  • INSTALLED-PACKAGE-NAMESPACE is the namespace in which the package is installed.

For example:

tanzu package installed update contour -v 1.17.1+vmware.1-tkg.1 -n my-packages
| Updating package 'contour'
\ Getting package install for 'contour'
| Updating package install for 'contour'

 Updated package install 'contour' in namespace 'my-packages'

To update the configuration of a CLI-managed package, run:

tanzu package installed update INSTALLED-PACKAGE-NAME -v INSTALLED-PACKAGE-VERSION -f PACKAGE-CONFIGURATION-FILE -n INSTALLED-PACKAGE-NAMESPACE

Where:

  • INSTALLED-PACKAGE-NAME is the name that you chose for the package. To see the name of the package, you can run the tanzu package installed list command. For more information, see List Installed Packages.
  • INSTALLED-PACKAGE-VERSION is the version of the installed package.
  • PACKAGE-CONFIGURATION-FILE is the path to the .yaml file that contains the updated package configuration. To retrieve the current configuration, see Get the Details of an Installed Package.
  • INSTALLED-PACKAGE-NAMESPACE is the namespace in which the package is installed.

For example:

tanzu package installed update contour -v 1.17.1+vmware.1-tkg.1 -f contour-data-values.yaml -n my-packages

\ Getting package install for 'contour'
| Updating secret 'contour-my-packages-values'
| Updating package install for 'contour'

Updated package install 'contour' in namespace 'my-packages'

Delete a Package

The tanzu package installed delete command deletes a CLI-managed package.

To delete a CLI-managed package from the target cluster:

  1. For a Contour or Harbor package that was upgraded from TKG v1.3 extensions, follow the workaround steps described in the Known Issue Deletion fails for Contour or Harbor packages upgraded from v1.3 in the TKG v1.4 Release Notes.

  2. In a terminal, run:

    tanzu package installed delete INSTALLED-PACKAGE-NAME -n INSTALLED-PACKAGE-NAMESPACE
    

    Where:

    • INSTALLED-PACKAGE-NAME is the name of the package that you want to delete. To see the name of the package, you can run the tanzu package installed list command. For more information, see List Installed Packages.
    • INSTALLED-PACKAGE-NAMESPACE is the namespace in which the package is installed. If you do not specify a namespace, default namespace is used.

    For example:

    tanzu package installed delete contour -n my-packages
    | Uninstalling package 'contour' from namespace 'my-packages'
    | Getting package install for 'contour'
    \ Deleting package install 'contour' from namespace 'my-packages'
    / Package uninstall status: Deleting
    | Deleting admin role 'contour-my-packages-cluster-role'
    | Deleting role binding 'contour-my-packages-cluster-rolebinding'
    | Deleting secret 'contour-my-packages-values'
    | Deleting service account 'contour-my-packages-sa'
    
    Uninstalled package 'contour' from namespace 'my-packages'
    
  3. (Optional) If you or another user created a namespace for this package when installing it by using the --create namespace parameter with tanzu package install, clean up by ensuring this namespace is empty, then delete the namespace.

    1. To ensure the namespace does not contain any resources, replace CUSTOM-NAMESPACE with your namespace and run:

      kubectl api-resources --verbs=list --namespaced -o name \
       | xargs -n 1 kubectl get --show-kind --ignore-not-found -n CUSTOM-NAMESPACE
      
    2. If the namespace is empty, delete it:

      kubectl delete namespaces CUSTOM-NAMESPACE
      
check-circle-line exclamation-circle-line close-line
Scroll to top icon