Install Tanzu Application Platform through Gitops with Secrets OPerationS (SOPS)

This topic tells you how to install Tanzu Application Platform (commonly known as TAP) through GitOps with secrets managed in a Git repository.

Caution

  • Tanzu Application Platform (GitOps) is currently in beta and is intended for evaluation and test purposes only. Do not use in a production environment.
  • Tanzu GitOps Reference Implementation (RI) does not support changing the secrets management strategy for a cluster.

Prerequisites

Before installing Tanzu Application Platform, you need:

Relocate images to a registry

VMware recommends relocating the images from VMware Tanzu Network registry to your own container image registry before attempting installation. If you don’t relocate the images, Tanzu Application Platform depends on VMware Tanzu Network for continued operation, and VMware Tanzu Network offers no uptime guarantees. The option to skip relocation is documented for evaluation and proof-of-concept only.

The supported registries are Harbor, Azure Container Registry, Google Container Registry, and Quay.io. See the following documentation for a registry to learn how to set it up:

To relocate images from the VMware Tanzu Network registry to your registry:

  1. Set up environment variables for installation use by running:

    export IMGPKG_REGISTRY_HOSTNAME_0=registry.tanzu.vmware.com
    export IMGPKG_REGISTRY_USERNAME_0=MY-TANZUNET-USERNAME
    export IMGPKG_REGISTRY_PASSWORD_0=MY-TANZUNET-PASSWORD
    export IMGPKG_REGISTRY_HOSTNAME_1=MY-REGISTRY
    export IMGPKG_REGISTRY_USERNAME_1=MY-REGISTRY-USER
    export IMGPKG_REGISTRY_PASSWORD_1=MY-REGISTRY-PASSWORD
    export INSTALL_REGISTRY_USERNAME=MY-REGISTRY-USER
    export INSTALL_REGISTRY_PASSWORD=MY-REGISTRY-PASSWORD
    export INSTALL_REGISTRY_HOSTNAME=MY-REGISTRY
    export TAP_VERSION=VERSION-NUMBER
    export INSTALL_REPO=TARGET-REPOSITORY
    

    Where:

    • MY-REGISTRY-USER is the user with write access to MY-REGISTRY.
    • MY-REGISTRY-PASSWORD is the password for MY-REGISTRY-USER.
    • MY-REGISTRY is your own container registry.
    • MY-TANZUNET-USERNAME is the user with access to the images in the VMware Tanzu Network registry registry.tanzu.vmware.com.
    • MY-TANZUNET-PASSWORD is the password for MY-TANZUNET-USERNAME.
    • VERSION-NUMBER is your Tanzu Application Platform version. For example, 1.5.10.
    • TARGET-REPOSITORY is your target repository, a folder or repository on MY-REGISTRY that serves as the location for the installation files for Tanzu Application Platform.

    VMware recommends using a JSON key file to authenticate with Google Container Registry. In this case, the value of INSTALL_REGISTRY_USERNAME is _json_key and the value of INSTALL_REGISTRY_PASSWORD is the content of the JSON key file. For more information about how to generate the JSON key file, see Google Container Registry documentation.

  2. Install the Carvel tool imgpkg CLI.

    To query for the available versions of Tanzu Application Platform on VMWare Tanzu Network Registry, run:

    imgpkg tag list -i registry.tanzu.vmware.com/tanzu-application-platform/tap-packages | sort -V
    
  3. Relocate the images with the imgpkg CLI by running:

    imgpkg copy -b registry.tanzu.vmware.com/tanzu-application-platform/tap-packages:${TAP_VERSION} --to-repo ${INSTALL_REGISTRY_HOSTNAME}/${INSTALL_REPO}/tap-packages
    

(Optional) Install Tanzu Application Platform in an air-gapped environment

Complete the following steps if you install Tanzu Application Platform in an air-gapped environment:

  1. Relocate the Tanzu Build Service images to your registry:

    imgpkg copy -b registry.tanzu.vmware.com/tanzu-application-platform/full-tbs-deps-package-repo:VERSION --to-repo ${INSTALL_REGISTRY_HOSTNAME}/${INSTALL_REPO}/full-tbs-deps-package-repo
    

    Where:

    • VERSION is the version of Tanzu Build Service. You can retrieve this value by running kubectl get package -n tap-install | grep buildservice
  2. Host a grype database in the air-gapped environment. For more information, see Use Grype in offline and air-gapped environments.

Create a new Git repository

  1. In a hosted Git service, for example, GitHub or GitLab, create a new repository.

    This version of Tanzu GitOps RI only supports authenticating to a hosted Git repository by using SSH.

  2. Initialize a new Git repository:

    mkdir -p $HOME/tap-gitops
    cd $HOME/tap-gitops
    
    git init
    git remote add origin git@github.com:my-organization/tap-gitops.git
    
  3. Create a read-only deploy key for this new repository (recommended) or SSH key for an account with read access to this repository.

    The private portion of this key is referred to as GIT_SSH_PRIVATE_KEY.

Download and unpack Tanzu GitOps Reference Implementation (RI)

  1. Sign in to VMware Tanzu Network.
  2. Go to the Tanzu Application Platform product page.
  3. Select Release 1.5.10 from the release drop-down menu.
  4. Click Tanzu GitOps Reference Implementation.
  5. Unpack the downloaded TGZ file into the $HOME/tap-gitops directory by running:

    tar xvf tanzu-gitops-ri-*.tgz -C $HOME/tap-gitops
    
  6. Commit the initial state:

    cd $HOME/tap-gitops
    
    git add . && git commit -m "Initialize Tanzu GitOps RI"
    git push -u origin
    

Create cluster configuration

  1. Seed configuration for a cluster using SOPS:

    cd $HOME/tap-gitops
    
    ./setup-repo.sh CLUSTER-NAME sops
    

    Where:

    • CLUSTER-NAME the name of your cluster.
    • sops selects the Secrets OPerationS-based secrets management variant.

    Example:

    cd $HOME/tap-gitops
    
    ./setup-repo.sh full-tap-cluster sops
    Created cluster configuration in ./clusters/full-tap-cluster.
    ...
    

    This script creates the directory clusters/full-tap-cluster/ and copies in the configuration required to sync this Git repository with the cluster and installing Tanzu Application Platform.

  2. Commit and push:

    git add . && git commit -m "Add full-tap-cluster"
    git push
    

Configure Tanzu Application Platform

Tanzu Sync Reference Implementation (RI) splits the values configuration of Tanzu Application Platform into two categories:

  • Sensitive TAP values, for example, credentials, encryptions keys and so on.
  • Non-sensitive TAP values, for example, packages to exclude, namespace configuration and so on.

The following sections describe how to create these values files.

Preparing sensitive Tanzu Application Platform values

  1. Generate Age public or secrets keys:

    Note

    Skip this step if you already have an Age key to encrypt or decrypt secrets.

    mkdir -p $HOME/tmp-enc
    chmod 700 $HOME/tmp-enc
    cd $HOME/tmp-enc
    
    age-keygen -o key.txt
    
    cat key.txt
    # created: 2023-02-08T10:55:35-07:00
    # public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
    AGE-SECRET-KEY-my-secret-key
    
  2. Create a plain YAML file tap-sensitive-values.yaml that contains a placeholder for the sensitive portion of Tanzu Application Platform values:

    ---
    tap_install:
      sensitive_values:
    
  3. Encrypt tap-sensitive-values.yaml with Age using SOPS:

    export SOPS_AGE_RECIPIENTS=$(cat key.txt | grep "# public key: " | sed 's/# public key: //')
    sops --encrypt tap-sensitive-values.yaml > tap-sensitive-values.sops.yaml
    

    Where:

    • grep is used to find the line containing the public key portion of the generated secret.
    • sed is used to extract the public key from the line found by grep.
  4. (Optional) Verify the encrypted file can be decrypted:

    export SOPS_AGE_KEY_FILE=key.txt
    sops --decrypt tap-sensitive-values.sops.yaml
    

    (Optional) Verify the encrypted file can be edited directly by using SOPS:

    sops tap-sensitive-values.sops.yaml
    
  5. Move the sensitive Tanzu Application Platform values into the cluster config:

    mv tap-sensitive-values.sops.yaml <GIT-REPO-ROOT>/clusters/<CLUSTER-NAME>/cluster-config/values/
    

    Example:

    mv tap-sensitive-values.sops.yaml $HOME/tap-gitops/clusters/full-tap-cluster/cluster-config/values/
    
  6. (Optional) Retain the Age identity key file in a safe and secure place such as a password manager, and purge the scratch space:

    mv key.txt SAFE-LOCATION/
    export SOPS_AGE_KEY_FILE=SAFE-LOCATION/key.txt
    rm -rf $HOME/tmp-enc
    

Preparing non-sensitive Tanzu Application Platform values

Create a plain YAML file <GIT-REPO-ROOT>/clusters/<CLUSTER-NAME>/cluster-config/values/tap-non-sensitive-values.yaml by using the Full Profile sample as a guide:

Example:

---
tap_install:
  values:
    ceip_policy_disclosed: true
    excluded_packages:
    - policy.apps.tanzu.vmware.com
...

To install Tanzu Application Service in an offline environment, you must configure Tanzu Build Service and Grype to work in an air-gapped environment:

---
tap_install:
  values:
    ...
    buildservice:
      exclude_dependencies: true
    grype:
      db:
        dbUpdateUrl: INTERNAL-VULN-DB-URL

Where:

  • INTERNAL-VULN-DB-URL URL that points to the internal file server.

Updating sensitive Tanzu Application Platform values

After filling in the non-sensitive values, follow these steps to extract the sensitive values into tap-sensitive-values.sops.yaml that you prepared earlier:

  1. Open an editor through SOPS to edit the encrypted sensitive values file:

    sops <GIT-REPO-ROOT>/clusters/<CLUSTER-NAME>/cluster-config/values/tap-sensitive-values.sops.yaml
    

    Example:

    sops $HOME/tap-gitops/clusters/full-tap-cluster/cluster-config/values/tap-sensitive-values.sops.yaml
    
  2. Add the sensitive values:

    Example of the container registry credentials using basic authentication:

    ---
    tap_install:
     sensitive_values:
       shared:
         image_registry:
           project_path: "example.com/my-project/tap"
           username: "my_username"
           password: "my_password"
    

    Example of the container registry credentials using Google Container Registry:

    ---
    tap_install:
     sensitive_values:
      shared:
        image_registry:
           project_path: "gcr.io/my-project/tap"
           username: "_json_key"
           password: |
             {
               "type": "service_account",
               "project_id": "my-project",
               "private_key_id": "my-private-key-id",
               "private_key": "-----BEGIN PRIVATE KEY-----\n..........\n-----END PRIVATE KEY-----\n",
               ...
             }
    

Generate Tanzu Application Platform installation and Tanzu Sync configuration

Follow these steps to generate the Tanzu Application Platform installation and Tanzu Sync configuration:

  1. Set up environment variables by running:

    export INSTALL_REGISTRY_HOSTNAME=MY-REGISTRY
    export INSTALL_REGISTRY_USERNAME=MY-REGISTRY-USER
    export INSTALL_REGISTRY_PASSWORD=MY-REGISTRY-PASSWORD
    export GIT_SSH_PRIVATE_KEY=PRIVATE-KEY
    export GIT_KNOWN_HOSTS=KNOWN-HOST-LIST
    export SOPS_AGE_KEY=AGE-KEY
    export TAP_PKGR_REPO=TAP-PACKAGE-OCI-REPOSITORY
    

    Where:

    • MY-REGISTRY is your container registry.
    • MY-REGISTRY-USER is the user with read access to MY-REGISTRY.
    • MY-REGISTRY-PASSWORD is the password for MY-REGISTRY-USER.
    • PRIVATE-KEY is the contents of an SSH private key file with read access to your Git repository.
    • HOST-LIST is the list of known hosts for Git host service.
    • AGE-KEY is the contents of the Age key generated earlier.
    • TAP-PACKAGE-OCI-REPOSITORY is the fully-qualified path to the OCI repository hosting the Tanzu Application Platform images. If the images are relocated as described in Relocate images to a registry, this value is ${INSTALL_REGISTRY_HOSTNAME}/${INSTALL_REPO}/tap-packages.

    Example of the Git repo hosted on GitHub:

    export INSTALL_REGISTRY_HOSTNAME=registry.tanzu.vmware.com
    export INSTALL_REGISTRY_USERNAME=foo@example.com
    export INSTALL_REGISTRY_PASSWORD=my-password
    export GIT_SSH_PRIVATE_KEY=$(cat $HOME/.ssh/my_private_key)
    export GIT_KNOWN_HOSTS=$(ssh-keyscan github.com)
    export SOPS_AGE_KEY=$(cat $HOME/key.txt)
    export TAP_PKGR_REPO=registry.tanzu.vmware.com/tanzu-application-platform/tap-packages
    
  2. Generate the Tanzu Application Platform install and the Tanzu Sync configuration files by using the provided script:

    cd <GIT-REPO-ROOT>/clusters/<CLUSTER-NAME>
    
    ./tanzu-sync/scripts/configure.sh
    

    Example:

    cd $HOME/tap-gitops/clusters/full-tap-cluster
    
    ./tanzu-sync/scripts/configure.sh
    
  3. (Optional) Update Tanzu Application Platform to use the latest patch:

    Update the Tanzu Application Platform version in GIT-REPO-ROOT/clusters/CLUSTER-NAME/cluster-config/values/tap-install-values.yaml:

    tap_install:
        ...
        version:
            package_repo_bundle_tag: "1.5.6" # Populate these values with the latest patch version.
            package_version: "1.5.6"
    

    Where:

    • package_repo_bundle_tag is the version of Tanzu Application Platform you want to upgrade to.
    • package_version is the version of Tanzu Application Platform you want to upgrade to. This version must match package_repo_bundle_tag.
    Note

    Tanzu GitOps RI does not provide a separate artifact for each patch version within a minor line. For example, Tanzu Application Platform v1.5.x contains the GitOps artifact with v1.5.0 only.

  4. Commit the generated configured to Git repository:

    git add cluster-config/ tanzu-sync/
    git commit -m "Configure install of TAP 1.5.0"
    git push
    

Deploy Tanzu Sync

  1. Install the Carvel tools kapp and ytt onto your $PATH:

    sudo cp $HOME/tanzu-cluster-essentials/kapp /usr/local/bin/kapp
    sudo cp $HOME/tanzu-cluster-essentials/ytt /usr/local/bin/ytt
    
  2. Set the Kubernetes cluster context.

    1. List the existing contexts:

      kubectl config get-contexts
      
    2. Set the context to the cluster that you want to deploy:

      kubectl config use-context CONTEXT-NAME
      

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

  3. Deploy the Tanzu Sync component:

    cd GIT-REPO-ROOT/clusters/CLUSTER-NAME
    
    ./tanzu-sync/scripts/deploy.sh
    

    Example:

    cd $HOME/tap-gitops/clusters/full-tap-cluster
    
    ./tanzu-sync/scripts/deploy.sh
    
    Note

    Depending on the profile and components included, it may take 5-10 minutes for Tanzu Application Platform to install. During this time, kapp waits for the deployment of Tanzu Sync to reconcile successfully. This is normal.

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