Skip to content

Latest commit

 

History

History
581 lines (412 loc) · 20.6 KB

sops.hbs.md

File metadata and controls

581 lines (412 loc) · 20.6 KB
Raw

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:

    # Set tanzunet as the source registry to copy the Tanzu Application Platform packages from.
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

# The user’s registry for copying the Tanzu Application Platform package to.
export IMGPKG_REGISTRY_HOSTNAME_1=MY-REGISTRY
export IMGPKG_REGISTRY_USERNAME_1=MY-REGISTRY-USER
export IMGPKG_REGISTRY_PASSWORD_1=MY-REGISTRY-PASSWORD
# These environment variables starting with IMGPKG_* are used by the imgpkg command only.

# The registry from which the Tanzu Application Platform package is retrieved.
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 image 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, {{ vars.tap_version }}.
    • 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](https://{{ vars.staging_toggle }}.vmware.com/en/Cluster-Essentials-for-VMware-Tanzu/{{ vars.url_version }}/cluster-essentials/deploy.html#optionally-install-clis-onto-your-path).

    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

Follow these steps to create a new Git repository and set up the authentication:

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

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

  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. Set up the authentication method.

    SSH : 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 called GIT_SSH_PRIVATE_KEY.

    Basic Authentication : Have a user name with read access to the Git repository and password or personal access token for the same user.

    Important Only use one of ssh or Basic Authentication, not both.

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 {{ vars.tap_version }} 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.

Prepare the sensitive Tanzu Application Platform values

Follow these steps to prepare the 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 outside of your Git repository that contains a placeholder for the sensitive portion of the 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

Prepare the 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 Platform 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 is the URL that points to the internal file server.

For more information, see Components and installation profiles.

Update the 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",
           ...
         }

Prepare the sensitive Tanzu Sync values

Follow these steps to prepare the sensitive Tanzu Sync values:

  1. Create a plain YAML file tanzu-sync-values.yaml outside of your Git repository that contains a placeholder for the sensitive portion of Tanzu Sync values:

    ---
secrets:
    sops:

  2. Encrypt tanzu-sync-values.yaml with Age using SOPS:

    export SOPS_AGE_RECIPIENTS=$(cat key.txt | grep "# public key: " | sed 's/# public key: //')
sops --encrypt tanzu-sync-values.yaml > tanzu-sync-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.

  3. Move the encrypted sensitive Tanzu Application Platform values into the Tanzu Sync config:

    mv tanzu-sync-values.sops.yaml GIT-REPO-ROOT/clusters/CLUSTER-NAME/tanzu-sync/app/sensitive-values/tanzu-sync-values.sops.yaml

    Example:

    mv tanzu-sync-values.sops.yaml $HOME/tap-gitops/clusters/full-tap-cluster/tanzu-sync/app/sensitive-values/tanzu-sync-values.sops.yaml

Update the sensitive Tanzu Sync values

Follow these steps to populate tap-sensitive-values.sops.yaml with credentials:

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

    sops GIT-REPO-ROOT/clusters/CLUSTER-NAME/tanzu-sync/app/sensitive-values/tanzu-sync-values.sops.yaml

    Example:

    sops $HOME/tap-gitops/clusters/full-tap-cluster/tanzu-sync/app/sensitive-values/tanzu-sync-values.sops.yaml

  2. Add the sensitive values:

    Configuration example for the Git SSH authentication:

    ---
secrets:
    sops:
        age_key: |
            AGE-KEY
        registry:
            hostname: MY-REGISTRY
            username: MY-REGISTRY-USER
            password: MY-REGISTRY-PASSWORD
        git:
            ssh:
                private_key: |
                    PRIVATE-KEY
                known_hosts: |
                    HOST-LIST

    Configuration example for the Git basic authentication:

    ---
secrets:
    sops:
        age_key: |
            AGE-KEY
        registry:
            hostname: MY-REGISTRY
            username: MY-REGISTRY-USER
            password: MY-REGISTRY-PASSWORD
        git:
            basic_auth:
                username: MY-GIT-USERNAME
                password: MY-GIT-PASSWORD

    Where:

    • AGE-KEY is the contents of the Age key generated earlier.
    • MY-REGISTRY is your container image 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. Only applies when you use ssh.
    • HOST-LIST is the list of known hosts for Git host service. Only applies when you use ssh.
    • MY-GIT-USERNAME is the user with read access to your Git repository. Only applies when you use basic authentication.
    • MY-GIT-PASSWORD is the password for MY-GIT-USERNAME. Only applies when you use basic authentication.

    You can find the schema for Tanzu Sync credentials in GIT-REPO-ROOT/clusters/CLUSTER-NAME/tanzu-sync/app/config/.tanzu-managed/schema--sops.yaml

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 TAP_PKGR_REPO=TAP-PACKAGE-OCI-REPOSITORY
export SOPS_AGE_KEY=AGE-KEY

    Where:

    • 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.
    • AGE-KEY is the contents of the Age key generated earlier.

    Example of the Git repo hosted on GitHub:

    export TAP_PKGR_REPO=registry.tanzu.vmware.com/tanzu-application-platform/tap-packages
export SOPS_AGE_KEY=$(cat $HOME/tmp-enc/key.txt)

  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: "{{ vars.tap_version }}" # Populate these values with the latest patch version.
        package_version: "{{ vars.tap_version }}"

    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.6.x only contains the v1.6.1 GitOps artifact.

  4. Commit the generated configured to Git repository:

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

Deploy Tanzu Sync

Follow these steps to 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.