Deploying Cluster Essentials v1.7.7

This topic tells you how to install, upgrade, and uninstall Cluster Essentials v1.7.7.

Supported Kubernetes versions

Installation requires Kubernetes cluster v1.24, v1.25, v1.26, v1.27 or v1.28 on one of the following Kubernetes providers:

  • Azure Kubernetes Service
  • Amazon Elastic Kubernetes Service
  • Google Kubernetes Engine
  • Red Hat OpenShift v4.13 or v4.14 running on vSphere and baremetal clusters
  • Minikube
  • Kind

Supported Platforms

The Cluster Essentials install script can only be run on AMD64 CPUs with macOS, Windows or 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.7.7.tgz.
    • For Linux, download tanzu-cluster-essentials-linux-amd64-1.7.7.tgz.
    • For Windows, download tanzu-cluster-essentials-windows-amd64-1.7.7.tgz.
  5. Unpack the TAR file into the tanzu-cluster-essentials directory:

    On macOS or Linux:

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

    On Windows (in “Command Prompt” app):

    :: Ensure you are in the directory where you have downloaded DOWNLOADED-CLUSTER-ESSENTIALS-BUNDLE
    mkdir tanzu-cluster-essentials
    tar -xvf DOWNLOADED-CLUSTER-ESSENTIALS-BUNDLE -C tanzu-cluster-essentials
    

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

  6. For air-gapped installation, download the bundle:

    On macOS or Linux:

    $ cd tanzu-cluster-essentials
    
    $ 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:34b73de251304538c08f8ccfb79950d205b04587ac1c0e7d32a58208c6b6c606 \
        --to-tar cluster-essentials-bundle-1.7.7.tar \
        --include-non-distributable-layers
    

    On Windows (in “Command Prompt” app):

    cd tanzu-cluster-essentials
    
    set IMGPKG_REGISTRY_HOSTNAME=registry.tanzu.vmware.com
    set IMGPKG_REGISTRY_USERNAME=TANZUNET-REGISTRY-USERNAME
    set /p IMGPKG_REGISTRY_PASSWORD=password:
    :: Interactively enter TANZUNET-REGISTRY-PASSWORD
    imgpkg copy ^
      -b registry.tanzu.vmware.com/tanzu-cluster-essentials/cluster-essentials-bundle@sha256:34b73de251304538c08f8ccfb79950d205b04587ac1c0e7d32a58208c6b6c606 ^
      --to-tar cluster-essentials-bundle-1.7.7.tar ^
      --include-non-distributable-layers
    

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
    

    Where CONTEXT-NAME can be retrieved from the outputs of the previous step.

Deploy onto the cluster

To deploy to your cluster, create a configuration secret if your registry requires a custom certificate then run the script to install Cluster Essentials.

(Optional) Set your custom certificate

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, these steps are not required.

  1. Create the kapp-controller namespace:

    kubectl create namespace kapp-controller
    
  2. 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
    

Deploy using macOS or Linux

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:34b73de251304538c08f8ccfb79950d205b04587ac1c0e7d32a58208c6b6c606
    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:

    Upload the previously downloaded bundle to the air gapped registry and install Cluster Essentials by running:

    $ cd tanzu-cluster-essentials
    
    $ IMGPKG_REGISTRY_HOSTNAME=MY-REGISTRY \
      IMGPKG_REGISTRY_USERNAME=MY-REGISTRY-USER \
      IMGPKG_REGISTRY_PASSWORD=MY-REGISTRY-PASSWORD \
      ./imgpkg copy \
        --tar cluster-essentials-bundle-1.7.7.tar \
        --to-repo MY-REGISTRY/cluster-essentials-bundle \
        --include-non-distributable-layers \
        --registry-ca-cert-path CA_PATH
    
    $ INSTALL_BUNDLE=MY-REGISTRY/cluster-essentials-bundle@sha256:34b73de251304538c08f8ccfb79950d205b04587ac1c0e7d32a58208c6b6c606 \
      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.

Deploy using Windows

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

  • For online installation, run:

    cd tanzu-cluster-essentials
    
    set INSTALL_BUNDLE=registry.tanzu.vmware.com/tanzu-cluster-essentials/cluster-essentials-bundle@sha256:34b73de251304538c08f8ccfb79950d205b04587ac1c0e7d32a58208c6b6c606
    set INSTALL_REGISTRY_HOSTNAME=registry.tanzu.vmware.com
    set INSTALL_REGISTRY_USERNAME=TANZU-NET-USER
    set /p INSTALL_REGISTRY_PASSWORD=password:
    :: Interactively enter TANZU-NET-PASSWORD
    
    install.bat
    

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

  • For air-gapped installation:

    Upload the previously downloaded bundle to the air gapped registry and install Cluster Essentials by running:

    cd tanzu-cluster-essentials
    
    set IMGPKG_REGISTRY_HOSTNAME=MY-REGISTRY
    set IMGPKG_REGISTRY_USERNAME=MY-REGISTRY-USER
    set IMGPKG_REGISTRY_PASSWORD=password:
    :: Interactive enter MY-REGISTRY-PASSWORD
    imgpkg copy ^
      --tar cluster-essentials-bundle-1.7.7.tar ^
      --to-repo MY-REGISTRY/cluster-essentials-bundle ^
      --include-non-distributable-layers ^
      --registry-ca-cert-path CA_PATH
    
    set INSTALL_BUNDLE=MY-REGISTRY/cluster-essentials-bundle@sha256:34b73de251304538c08f8ccfb79950d205b04587ac1c0e7d32a58208c6b6c606
    set INSTALL_REGISTRY_HOSTNAME=MY-REGISTRY
    set INSTALL_REGISTRY_USERNAME=MY-REGISTRY-USER
    set /p INSTALL_REGISTRY_PASSWORD=password:
    :: Interactively enter MY-REGISTRY-PASSWORD
    install.bat
    

    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.7.7 using the following steps. Running this upgrade will update the kapp-controller version on your cluster to v0.48.9 and secretgen-controller version to v0.15.6.

  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:

    On macOS or Linux:

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

    On Windows (in “Command Prompt” app):

    cd tanzu-cluster-essentials
    
    set INSTALL_BUNDLE=registry.tanzu.vmware.com/tanzu-cluster-essentials/cluster-essentials-bundle@sha256:34b73de251304538c08f8ccfb79950d205b04587ac1c0e7d32a58208c6b6c606
    set INSTALL_REGISTRY_HOSTNAME=registry.tanzu.vmware.com
    set INSTALL_REGISTRY_USERNAME=TANZU-NET-USER
    set /p INSTALL_REGISTRY_PASSWORD=password:
    :: Interactively enter TANZU-NET-PASSWORD
    
    install.bat
    

    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

Rollback

Caution

Uninstalling Cluster Essentials when the upgrade fails will cause an unrepairable state for your cluster.

To rollback to the previously installed version, follow the previous version of Cluster Essentials deployment instructions.

Uninstall

Caution

Uninstalling Cluster Essentials when the installation fails will cause an unrepairable state for your cluster.

You must uninstall all the 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:

    On macOS or Linux:

    cd $HOME/tanzu-cluster-essentials
    ./uninstall.sh --yes
    

    On Windows (in “Command Prompt” app):

    cd tanzu-cluster-essentials
    uninstall.bat
    

Troubleshoot

This section describes how to troubleshoot installing Cluster Essentials.

Cluster Essentails installation fails on PSA enforced cluster

You see the following error if Pod Security Admission (PSA) is enforced on the Kubernetes cluster, for example, TKGs with vSphere7 and Kubernetes version 1.26 and later:

kapp: Error: waiting on reconcile deployment/secretgen-controller (apps/v1) namespace: secretgen-controller:
Finished unsuccessfully (Deployment is not progressing: ProgressDeadlineExceeded (message: ReplicaSet "secretgen-controller-766479485f" has timed out progressing.))

Solution

  1. Locate the following code in install.sh:

    echo "## Deploying secretgen-controller"
    ./kapp deploy -a secretgen-controller -n $ns_name -f <(./ytt -f ./bundle/secretgen-controller/config/ -f ./bundle/registry-creds/ --data-values-env YTT | ./kbld -f- -f ./bundle/.imgpkg/images.yml) "$@"
    
  2. Replace the code located in step 1 with the following:

    # Adding an overlay to set the seccompProfile.
    cat > "bundle/overlay.yaml" <<EOF
    #@ load("@ytt:overlay", "overlay")
    
    #@overlay/match by=overlay.subset({"kind":"Deployment"})
    ---
    spec:
      template:
        spec:
          containers:
          #@overlay/match by=overlay.all, expects="0+"
          #@overlay/match-child-defaults missing_ok=True
          - securityContext:
              seccompProfile:
                type: RuntimeDefault
    EOF
    
    echo "## Deploying secretgen-controller"
    ./kapp deploy -a secretgen-controller -n $ns_name -f <(./ytt -f ./bundle/secretgen-controller/config/ -f ./bundle/registry-creds/ --data-values-env YTT -f ./bundle/overlay.yaml | ./kbld -f- -f ./bundle/.imgpkg/images.yml) "$@"
    
  3. Rerun install.sh.

check-circle-line exclamation-circle-line close-line
Scroll to top icon