Deploying Cluster Essentials v1.2

This document describes how to install, upgrade, and uninstall Cluster Essentials v1.2.

Supported Kubernetes versions

Installation requires Kubernetes cluster v1.20, v1.21, v1.22, v1.23, or v1.24 on one of the following Kubernetes providers:

  • Azure Kubernetes Service
  • Amazon Elastic Kubernetes Service
  • Google Kubernetes Engine
  • Minikube
  • Kind

Supported Platforms

The Cluster Essentials install script can only be run on MacOS and Linux.

Install

If you are using a VMware Tanzu Kubernetes Grid cluster, you do not need to install Cluster Essentials because the contents of Cluster Essentials are already installed on your cluster.

For all other clusters, install Cluster Essentials using the following steps.

Download artifacts from Tanzu Network

  1. Sign in to Tanzu Network.

  2. Go to Cluster Essentials for VMware Tanzu on VMware Tanzu Network.

  3. Accept or confirm that you have accepted the EULA for the product

  4. Select a download according to your Kubernetes provider and operating system:

    • For macOS, download tanzu-cluster-essentials-darwin-amd64-1.2.0.tgz.
    • For Linux, download tanzu-cluster-essentials-linux-amd64-1.2.0.tgz.
  5. Unpack the TAR file into the tanzu-cluster-essentials directory:

    mkdir $HOME/tanzu-cluster-essentials
    tar -xvf DOWNLOADED-CLUSTER-ESSENTIALS-BUNDLE -C $HOME/tanzu-cluster-essentials
    

    Where DOWNLOADED-CLUSTER-ESSENTIALS-BUNDLE is the name of the bundle you downloaded.

Set Kubernetes cluster context

  1. List the existing contexts by running:

    kubectl config get-contexts
    
  2. Set the context to the cluster that you want to use for the Cluster Essentials install.

    kubectl config use-context CONTEXT-NAME
    

Deploy onto cluster

  1. (Optional) If your registry needs a custom certificate, you must load that configuration into the cluster before installing kapp-controller. If your registry uses a public certificate, this step is not required.

    Create the kapp-controller namespace:

    kubectl create namespace kapp-controller
    

    Create a configuration secret by using the registry’s ca.crt stored on local disk:

    kubectl create secret generic kapp-controller-config \
       --namespace kapp-controller \
       --from-file caCerts=ca.crt
    
  2. Configure and run install.sh, which will install kapp-controller and secretgen-controller on your cluster:

    • For online installation, run:

      export INSTALL_BUNDLE=registry.tanzu.vmware.com/tanzu-cluster-essentials/cluster-essentials-bundle@sha256:e00f33b92d418f49b1af79f42cb13d6765f1c8c731f4528dfff8343af042dc3e
      export INSTALL_REGISTRY_HOSTNAME=registry.tanzu.vmware.com
      export INSTALL_REGISTRY_USERNAME=TANZU-NET-USER
      export INSTALL_REGISTRY_PASSWORD=TANZU-NET-PASSWORD
      cd $HOME/tanzu-cluster-essentials
      ./install.sh --yes
      

      Where TANZU-NET-USER and TANZU-NET-PASSWORD are your credentials for VMware Tanzu Network.

    • For air-gapped installation, run:

      $ IMGPKG_REGISTRY_HOSTNAME=registry.tanzu.vmware.com \
        IMGPKG_REGISTRY_USERNAME=TANZUNET-REGISTRY-USERNAME \
        IMGPKG_REGISTRY_PASSWORD=TANZUNET-REGISTRY-PASSWORD \
        imgpkg copy \
          -b registry.tanzu.vmware.com/tanzu-cluster-essentials/cluster-essentials-bundle@sha256:e00f33b92d418f49b1af79f42cb13d6765f1c8c731f4528dfff8343af042dc3e \
          --to-tar cluster-essentials-bundle-1.2.0.tar \
          --include-non-distributable-layers
      
      $ IMGPKG_REGISTRY_HOSTNAME=MY-REGISTRY \
        IMGPKG_REGISTRY_USERNAME=MY-REGISTRY-USER \
        IMGPKG_REGISTRY_PASSWORD=MY-REGISTRY-PASSWORD \
        imgpkg copy \
          --tar cluster-essentials-bundle-1.2.0.tar \
          --to-repo CUSTOMER-REGISTRY-HOSTNAME/cluster-essentials-bundle \
          --include-non-distributable-layers \
          --registry-ca-cert-path CA_PATH
      $ INSTALL_BUNDLE=CUSTOMER-REGISTRY-HOSTNAME/cluster-essentials-bundle:e00f33b92d418f49b1af79f42cb13d6765f1c8c731f4528dfff8343af042dc3e \
        INSTALL_REGISTRY_HOSTNAME=MY-REGISTRY \
        INSTALL_REGISTRY_USERNAME=MY-REGISTRY-USER \
        INSTALL_REGISTRY_PASSWORD=MY-REGISTRY-PASSWORD \
        ./install.sh
      

      Where:

      • TANZUNET-REGISTRY-USERNAME is your username of the VMware Tanzu Network.
      • TANZUNET-REGISTRY-PASSWORD is your password of the VMware Tanzu Network.
      • MY-REGISTRY is your air-gapped container registry.
      • MY-REGISTRY-USER is the user with write access to MY-REGISTRY.
      • MY-REGISTRY-PASSWORD is the password for MY-REGISTRY-USER.

Optionally install CLIs onto your $PATH

  1. (Optional) Several Tanzu products, such as Tanzu Application Platform, use the kapp CLI to deploy. For convenience, you may install the kapp CLI onto your $PATH:

    sudo cp $HOME/tanzu-cluster-essentials/kapp /usr/local/bin/kapp
    
  2. (Optional) Several Tanzu products, such as Tanzu Application Platform, use the imgpkg CLI to relocate packages. For convenience, you may install the imgpkg CLI onto your $PATH:

    sudo cp $HOME/tanzu-cluster-essentials/imgpkg /usr/local/bin/imgpkg
    

Upgrade

Cluster Essentials components (such as kapp-controller and secretgen-controller) cannot be upgraded on clusters provisioned using VMware Tanzu Kubernetes Grid, Tanzu Community Edition, and VMware Tanzu Mission Control.

For all other clusters, if you already have Cluster Essentials 1.0+ installed on your target cluster, you can upgrade to Cluster Essentials 1.2 using the following steps. Running this upgrade will update the kapp-controller version on your cluster to v0.38.4 and secretgen-controller version to v0.9.1.

  1. Follow the steps above to Download artifacts from Tanzu Network and Set Kubernetes cluster context

  2. Configure and run install.sh, which will install kapp-controller and secretgen-controller on your cluster:

    export INSTALL_BUNDLE=registry.tanzu.vmware.com/tanzu-cluster-essentials/cluster-essentials-bundle@sha256:e00f33b92d418f49b1af79f42cb13d6765f1c8c731f4528dfff8343af042dc3e
    export INSTALL_REGISTRY_HOSTNAME=registry.tanzu.vmware.com
    export INSTALL_REGISTRY_USERNAME=TANZU-NET-USER
    export INSTALL_REGISTRY_PASSWORD=TANZU-NET-PASSWORD
    cd $HOME/tanzu-cluster-essentials
    ./install.sh --yes
    

    Where TANZU-NET-USER and TANZU-NET-PASSWORD are your credentials for VMware Tanzu Network.

  3. Follow the steps above to optionally install newer versions of the kapp and imgpkg CLIs to your path

Uninstall

Caution: Please ensure that you have uninstalled all Custom Resources created by kapp-controller and secretgen-controller before running the uninstall script for Cluster Essentials.

  1. Follow the steps above to Set Kubernetes cluster context

  2. Run uninstall.sh, which will uninstall kapp-controller and secretgen-controller on your cluster:

    cd $HOME/tanzu-cluster-essentials
    ./uninstall.sh --yes
    
check-circle-line exclamation-circle-line close-line
Scroll to top icon