Deploying Cluster Essentials v1.8.3

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

Supported Kubernetes versions

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

  • Azure Kubernetes Service
  • Amazon Elastic Kubernetes Service
  • Google Kubernetes Engine
  • Red Hat OpenShift v4.14 or v4.15 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 the Broadcom Support Portal

  1. Sign in to the Broadcom Support Portal.

  2. Go to Cluster Essentials for VMware Tanzu in Tanzu > My Downloads.

  3. Expand the Cluster Essentials for VMWare Tanzu section.

  4. Retrieve your Broadcom registry API token:

    1. Click the Token Download icon next to the Cluster Essentials version you want to download.

      Screenshot of the Cluster Essentials download page in the Broadcom Support Portal with the Token Download icon highlighted.

    2. Follow the instructions in the dialog box. Save the token as a variable named MY_BROADCOM_SUPPORT_ACCESS_TOKEN. For example:

      export MY_BROADCOM_SUPPORT_ACCESS_TOKEN=API-TOKEN

      Where API-TOKEN is your token from the Broadcom Support Portal.

  5. Click the 1.8.3.

  6. Select the I agree to Terms and Conditions check box.

  7. Choose a download according to your Kubernetes provider and operating system:

    • For macOS, download tanzu-cluster-essentials-darwin-amd64-1.8.3.tgz.
    • For Linux, download tanzu-cluster-essentials-linux-amd64-1.8.3.tgz.
    • For Windows, download tanzu-cluster-essentials-windows-amd64-1.8.3.tgz.

  8. 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

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

    • On Windows, in Command Prompt:

      :: 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.

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

    • On macOS or Linux:

      $ cd tanzu-cluster-essentials

$ IMGPKG_REGISTRY_HOSTNAME=registry.packages.broadcom.com \
  IMGPKG_REGISTRY_USERNAME=BROADCOM-REGISTRY-USERNAME \
  IMGPKG_REGISTRY_PASSWORD=${MY_BROADCOM_SUPPORT_ACCESS_TOKEN} \
  ./imgpkg copy \
    -b registry.packages.broadcom.com/tanzu-cluster-essentials/cluster-essentials-bundle@sha256:87bf0af1f6db8b449ec090416cd82a624dff97da49b975116d38e1d07050d01b \
    --to-tar cluster-essentials-bundle-1.8.3.tar \
    --include-non-distributable-layers

      Where BROADCOM-REGISTRY-USERNAME is your username for Broadcom registry.

    • On Windows, in Command Prompt:

      cd tanzu-cluster-essentials

set IMGPKG_REGISTRY_HOSTNAME=registry.packages.broadcom.com
set IMGPKG_REGISTRY_USERNAME=BROADCOM-REGISTRY-USERNAME
set /p IMGPKG_REGISTRY_PASSWORD=password:
:: Interactively enter $MY_BROADCOM_SUPPORT_ACCESS_TOKEN
imgpkg copy ^
  -b registry.packages.broadcom.com/tanzu-cluster-essentials/cluster-essentials-bundle@sha256:87bf0af1f6db8b449ec090416cd82a624dff97da49b975116d38e1d07050d01b ^
  --to-tar cluster-essentials-bundle-1.8.3.tar ^
  --include-non-distributable-layers

      Where BROADCOM-REGISTRY-USERNAME is your username for Broadcom registry.

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 installs kapp-controller and secretgen-controller on your cluster:

  • For online installation, run:

    export INSTALL_BUNDLE=registry.packages.broadcom.com/tanzu-cluster-essentials/cluster-essentials-bundle@sha256:87bf0af1f6db8b449ec090416cd82a624dff97da49b975116d38e1d07050d01b
export INSTALL_REGISTRY_HOSTNAME=registry.packages.broadcom.com
export INSTALL_REGISTRY_USERNAME=BROADCOM-REGISTRY-USERNAME
export INSTALL_REGISTRY_PASSWORD=${MY_BROADCOM_SUPPORT_ACCESS_TOKEN}
cd $HOME/tanzu-cluster-essentials
./install.sh --yes

    Where BROADCOM-REGISTRY-USERNAME is your username for Broadcom registry.

  • 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.8.3.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:87bf0af1f6db8b449ec090416cd82a624dff97da49b975116d38e1d07050d01b \
  INSTALL_REGISTRY_HOSTNAME=MY-REGISTRY \
  INSTALL_REGISTRY_USERNAME=MY-REGISTRY-USER \
  INSTALL_REGISTRY_PASSWORD=MY-REGISTRY-PASSWORD \
  ./install.sh

    Where:

    • 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 installs kapp-controller and secretgen-controller on your cluster:

  • For online installation, run:

    cd tanzu-cluster-essentials

set INSTALL_BUNDLE=registry.packages.broadcom.com/tanzu-cluster-essentials/cluster-essentials-bundle@sha256:87bf0af1f6db8b449ec090416cd82a624dff97da49b975116d38e1d07050d01b
set INSTALL_REGISTRY_HOSTNAME=registry.packages.broadcom.com
set INSTALL_REGISTRY_USERNAME=BROADCOM-REGISTRY-USERNAME
set /p INSTALL_REGISTRY_PASSWORD=password:
:: Interactively enter $MY_BROADCOM_SUPPORT_ACCESS_TOKEN

install.bat

    Where BROADCOM-REGISTRY-USERNAME is your username for Broadcom registry.

  • 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.8.3.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:87bf0af1f6db8b449ec090416cd82a624dff97da49b975116d38e1d07050d01b
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:

    • 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.

(Optional) Install CLIs onto your $PATH

  1. (Optional) Several Tanzu products, such as Tanzu Application Platform, use the kapp CLI to deploy. For convenience, you can 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 can 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 and VMware Tanzu Mission Control.

For all other clusters, if you already have Cluster Essentials v1.0 or later installed on your target cluster, you can upgrade to Cluster Essentials v1.8 using the following steps. Running this upgrade updates the kapp-controller version on your cluster to v0.50.4 and secretgen-controller version to v0.16.3.

  1. Follow the steps in Download artifacts from the Broadcom Support Portal and Set Kubernetes cluster context.

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

    • On macOS or Linux:

      cd $HOME/tanzu-cluster-essentials

export INSTALL_BUNDLE=registry.packages.broadcom.com/tanzu-cluster-essentials/cluster-essentials-bundle@sha256:87bf0af1f6db8b449ec090416cd82a624dff97da49b975116d38e1d07050d01b
export INSTALL_REGISTRY_HOSTNAME=registry.packages.broadcom.com
export INSTALL_REGISTRY_USERNAME=BROADCOM-REGISTRY-USERNAME
export INSTALL_REGISTRY_PASSWORD=${MY_BROADCOM_SUPPORT_ACCESS_TOKEN}

./install.sh --yes

      Where BROADCOM-REGISTRY-USERNAME is your username for Broadcom registry.

    • On Windows, in Command Prompt:

      cd tanzu-cluster-essentials

set INSTALL_BUNDLE=registry.packages.broadcom.com/tanzu-cluster-essentials/cluster-essentials-bundle@sha256:87bf0af1f6db8b449ec090416cd82a624dff97da49b975116d38e1d07050d01b
set INSTALL_REGISTRY_HOSTNAME=registry.packages.broadcom.com
set INSTALL_REGISTRY_USERNAME=BROADCOM-REGISTRY-USERNAME
set /p INSTALL_REGISTRY_PASSWORD=password:
:: Interactively enter $MY_BROADCOM_SUPPORT_ACCESS_TOKEN

install.bat

      Where BROADCOM-REGISTRY-USERNAME is your username for Broadcom registry.

  3. (Optional) Follow the steps in Install CLIs onto your $PATH to 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 in Set Kubernetes cluster context.

  2. Run uninstall.sh, which uninstalls 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