Install Tanzu Application Platform package and profiles

This topic describes how to install Tanzu Application Platform packages from the Tanzu Application Platform package repository.

Before installing the packages, ensure you have:

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. Install Docker if it is not already installed.

  2. Log in to your image registry by running:

    docker login MY-REGISTRY
    

    Where MY-REGISTRY is your own container registry.

  3. Log in to the VMware Tanzu Network registry with your VMware Tanzu Network credentials by running:

    docker login registry.tanzu.vmware.com
    
  4. Set up environment variables for installation use by running:

    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.
    • VERSION-NUMBER is your Tanzu Application Platform version. For example, 1.3.4.
    • TARGET-REPOSITORY is your target repository, a folder/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.

  5. 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 | grep -v sha | sort -V
    
  6. 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
    

Add the Tanzu Application Platform package repository

Tanzu CLI packages are available on repositories. Adding the Tanzu Application Platform package repository makes Tanzu Application Platform and its packages available for installation.

Relocate images to a registry is strongly recommended but not required for installation. If you skip this step, you can use the following values to replace the corresponding variables:

  • INSTALL_REGISTRY_HOSTNAME is registry.tanzu.vmware.com
  • INSTALL_REPO is tanzu-application-platform
  • INSTALL_REGISTRY_USERNAME and INSTALL_REGISTRY_PASSSWORD are the credentials to run docker login registry.tanzu.vmware.com
  • TAP_VERSION is your Tanzu Application Platform version. For example, 1.3.4

To add the Tanzu Application Platform package repository to your cluster:

  1. Create a namespace called tap-install for deploying any component packages by running:

    kubectl create ns tap-install
    

    This namespace keeps the objects grouped together logically.

  2. Create a registry secret by running:

    tanzu secret registry add tap-registry \
      --username ${INSTALL_REGISTRY_USERNAME} --password ${INSTALL_REGISTRY_PASSWORD} \
      --server ${INSTALL_REGISTRY_HOSTNAME} \
      --export-to-all-namespaces --yes --namespace tap-install
    
  3. Add the Tanzu Application Platform package repository to the cluster by running:

    tanzu package repository add tanzu-tap-repository \
      --url ${INSTALL_REGISTRY_HOSTNAME}/${INSTALL_REPO}/tap-packages:$TAP_VERSION \
      --namespace tap-install
    
  4. Get the status of the Tanzu Application Platform package repository, and ensure the status updates to Reconcile succeeded by running:

    tanzu package repository get tanzu-tap-repository --namespace tap-install
    

    For example:

    $ tanzu package repository get tanzu-tap-repository --namespace tap-install
    - Retrieving repository tap...
    NAME:          tanzu-tap-repository
    VERSION:       16253001
    REPOSITORY:    tapmdc.azurecr.io/mdc/1.0.2/tap-packages
    TAG:           1.3.4
    STATUS:        Reconcile succeeded
    REASON:
    
    Note

    The VERSION and TAG numbers differ from the earlier example if you are on Tanzu Application Platform v1.0.2 or earlier.

  5. List the available packages by running:

    tanzu package available list --namespace tap-install
    

    For example:

    $ tanzu package available list --namespace tap-install
    / Retrieving available packages...
      NAME                                                 DISPLAY-NAME                                                              SHORT-DESCRIPTION
      accelerator.apps.tanzu.vmware.com                    Application Accelerator for VMware Tanzu                                  Used to create new projects and configurations.
      api-portal.tanzu.vmware.com                          API portal                                                                A unified user interface for API discovery and exploration at scale.
      apis.apps.tanzu.vmware.com                           API Auto Registration for VMware Tanzu                                    A TAP component to automatically register API exposing workloads as API entities
                                                                                                                                     in TAP GUI.
      backend.appliveview.tanzu.vmware.com                 Application Live View for VMware Tanzu                                    App for monitoring and troubleshooting running apps
      build.appliveview.tanzu.vmware.com                   Application Live View Conventions for VMware Tanzu                        Application Live View convention server
      buildservice.tanzu.vmware.com                        Tanzu Build Service                                                       Tanzu Build Service enables the building and automation of containerized
                                                                                                                                     software workflows securely and at scale.
      carbonblack.scanning.apps.tanzu.vmware.com           VMware Carbon Black for Supply Chain Security Tools - Scan                Default scan templates using VMware Carbon Black
      cartographer.tanzu.vmware.com                        Cartographer                                                              Kubernetes native Supply Chain Choreographer.
      cnrs.tanzu.vmware.com                                Cloud Native Runtimes                                                     Cloud Native Runtimes is a serverless runtime based on Knative
      connector.appliveview.tanzu.vmware.com               Application Live View Connector for VMware Tanzu                          App for discovering and registering running apps
      controller.conventions.apps.tanzu.vmware.com         Convention Service for VMware Tanzu                                       Convention Service enables app operators to consistently apply desired runtime
                                                                                                                                     configurations to fleets of workloads.
      controller.source.apps.tanzu.vmware.com              Tanzu Source Controller                                                   Tanzu Source Controller enables workload create/update from source code.
      conventions.appliveview.tanzu.vmware.com             Application Live View Conventions for VMware Tanzu                        Application Live View convention server
      developer-conventions.tanzu.vmware.com               Tanzu App Platform Developer Conventions                                  Developer Conventions
      eventing.tanzu.vmware.com                            Eventing                                                                  Eventing is an event-driven architecture platform based on Knative Eventing
      fluxcd.source.controller.tanzu.vmware.com            Flux Source Controller                                                    The source-controller is a Kubernetes operator, specialised in artifacts
                                                                                                                                     acquisition from external sources such as Git, Helm repositories and S3 buckets.
      grype.scanning.apps.tanzu.vmware.com                 Grype for Supply Chain Security Tools - Scan                              Default scan templates using Anchore Grype
      image-policy-webhook.signing.apps.tanzu.vmware.com   Image Policy Webhook                                                      Image Policy Webhook enables defining of a policy to restrict unsigned container
                                                                                                                                     images.
      learningcenter.tanzu.vmware.com                      Learning Center for Tanzu Application Platform                            Guided technical workshops
      metadata-store.apps.tanzu.vmware.com                 Supply Chain Security Tools - Store                                       Post SBoMs and query for image, package, and vulnerability metadata.
      ootb-delivery-basic.tanzu.vmware.com                 Tanzu App Platform Out of The Box Delivery Basic                          Out of The Box Delivery Basic.
      ootb-supply-chain-basic.tanzu.vmware.com             Tanzu App Platform Out of The Box Supply Chain Basic                      Out of The Box Supply Chain Basic.
      ootb-supply-chain-testing-scanning.tanzu.vmware.com  Tanzu App Platform Out of The Box Supply Chain with Testing and Scanning  Out of The Box Supply Chain with Testing and Scanning.
      ootb-supply-chain-testing.tanzu.vmware.com           Tanzu App Platform Out of The Box Supply Chain with Testing               Out of The Box Supply Chain with Testing.
      ootb-templates.tanzu.vmware.com                      Tanzu App Platform Out of The Box Templates                               Out of The Box Templates.
      policy.apps.tanzu.vmware.com                         Supply Chain Security Tools - Policy Controller                           Policy Controller enables defining of a policy to restrict unsigned container
                                                                                                                                     images.
      scanning.apps.tanzu.vmware.com                       Supply Chain Security Tools - Scan                                        Scan for vulnerabilities and enforce policies directly within Kubernetes native
                                                                                                                                     Supply Chains.
      service-bindings.labs.vmware.com                     Service Bindings for Kubernetes                                           Service Bindings for Kubernetes implements the Service Binding Specification.
      services-toolkit.tanzu.vmware.com                    Services Toolkit                                                          The Services Toolkit enables the management, lifecycle, discoverability and
                                                                                                                                     connectivity of Service Resources (databases, message queues, DNS records,
                                                                                                                                     etc.).
      snyk.scanning.apps.tanzu.vmware.com                  Snyk for Supply Chain Security Tools - Scan                               Default scan templates using Snyk
      spring-boot-conventions.tanzu.vmware.com             Tanzu Spring Boot Conventions Server                                      Default Spring Boot convention server.
      sso.apps.tanzu.vmware.com                            AppSSO                                                                    Application Single Sign-On for Tanzu
      tap-auth.tanzu.vmware.com                            Default roles for Tanzu Application Platform                              Default roles for Tanzu Application Platform
      tap-gui.tanzu.vmware.com                             Tanzu Application Platform GUI                                            web app graphical user interface for Tanzu Application Platform
      tap-telemetry.tanzu.vmware.com                       Telemetry Collector for Tanzu Application Platform                        Tanzu Application Plaform Telemetry
      tap.tanzu.vmware.com                                 Tanzu Application Platform                                                Package to install a set of TAP components to get you started based on your use
                                                                                                                                     case.
      tekton.tanzu.vmware.com                              Tekton Pipelines                                                          Tekton Pipelines is a framework for creating CI/CD systems.
      workshops.learningcenter.tanzu.vmware.com            Workshop Building Tutorial                                                Workshop Building Tutorial
    

Install your Tanzu Application Platform profile

The tap.tanzu.vmware.com package installs predefined sets of packages based on your profile settings. This is done by using the package manager installed by Tanzu Cluster Essentials.

For more information about profiles, see Components and installation profiles.

To prepare to install a profile:

  1. List version information for the package by running:

    tanzu package available list tap.tanzu.vmware.com --namespace tap-install
    
  2. Create a tap-values.yaml file by using the Full Profile sample in the following section as a guide. These samples have the minimum configuration required to deploy Tanzu Application Platform. The sample values file contains the necessary defaults for:

    • The meta-package, or parent Tanzu Application Platform package.
    • Subordinate packages, or individual child packages.
    Important

    Keep the values file for future configuration use.

  3. View possible configuration settings for your package

Full profile

The following is the YAML file sample for the full-profile. The profile: field takes full as the default value, but you can also set it to iterate, build, run or view. Refer to Install multicluster Tanzu Application Platform profiles for more information.

Important

While installing Tanzu Application Platform v1.3 and later, exclude the policy controller policy.apps.tanzu.vmware.com, or deploy a Sigstore Stack to use as a TUF Mirror. For more information, see Policy controller known issues.

shared:
  ingress_domain: "INGRESS-DOMAIN"
  image_registry:
    project_path: "SERVER-NAME/REPO-NAME"
    username: "KP-DEFAULT-REPO-USERNAME"
    password: "KP-DEFAULT-REPO-PASSWORD"
  kubernetes_distribution: "openshift" # To be passed only for OpenShift. Defaults to "".
  ca_cert_data: | # To be passed if using custom certificates.
      -----BEGIN CERTIFICATE-----
      MIIFXzCCA0egAwIBAgIJAJYm37SFocjlMA0GCSqGSIb3DQEBDQUAMEY...
      -----END CERTIFICATE-----

ceip_policy_disclosed: FALSE-OR-TRUE-VALUE # Installation fails if this is not set to true. Not a string.

#The above keys are minimum numbers of entries needed in tap-values.yaml to get a functioning TAP Full profile installation.

#Below are the keys which may have default values set, but can be overridden.

profile: full # Can take iterate, build, run, view.

excluded_packages:
- policy.apps.tanzu.vmware.com

supply_chain: basic # Can take testing, testing_scanning.

ootb_supply_chain_basic: # Based on supply_chain set above, can be changed to ootb_supply_chain_testing, ootb_supply_chain_testing_scanning.
  registry:
    server: "SERVER-NAME" # Takes the value from shared section above by default, but can be overridden by setting a different value.
    repository: "REPO-NAME" # Takes the value from shared section above by default, but can be overridden by setting a different value.
  gitops:
    ssh_secret: "SSH-SECRET-KEY" # Takes "" as value by default; but can be overridden by setting a different value.

contour:
  envoy:
    service:
      type: LoadBalancer # This is set by default, but can be overridden by setting a different value.

buildservice:
  kp_default_repository: "KP-DEFAULT-REPO"
  kp_default_repository_username: "KP-DEFAULT-REPO-USERNAME"
  kp_default_repository_password: "KP-DEFAULT-REPO-PASSWORD"

tap_gui:
  service_type: ClusterIP # If the shared.ingress_domain is set as above, this must be set to ClusterIP.
  app_config:
    catalog:
      locations:
        - type: url
          target: https://GIT-CATALOG-URL/catalog-info.yaml

metadata_store:
  ns_for_export_app_cert: "MY-DEV-NAMESPACE"
  app_service_type: ClusterIP # Defaults to LoadBalancer. If shared.ingress_domain is set earlier, this must be set to ClusterIP.

scanning:
  metadataStore:
    url: "" # Configuration is moved, so set this string to empty.

grype:
  namespace: "MY-DEV-NAMESPACE"
  targetImagePullSecret: "TARGET-REGISTRY-CREDENTIALS-SECRET"

Where:

  • INGRESS-DOMAIN is the subdomain for the host name that you point at the tanzu-shared-ingress service’s External IP address. It is not required to know the External IP address or set up the DNS record while installing. Installing the Tanzu Application Platform package creates the tanzu-shared-ingress and its External IP address. You can create the DNS record after completing the installation.
  • KP-DEFAULT-REPO is a writable repository in your registry. Tanzu Build Service dependencies are written to this location. Examples:
    • Harbor has the form kp_default_repository: "my-harbor.io/my-project/build-service".
    • Docker Hub has the form kp_default_repository: "my-dockerhub-user/build-service" or kp_default_repository: "index.docker.io/my-user/build-service".
    • Google Cloud Registry has the form kp_default_repository: "gcr.io/my-project/build-service".
  • KP-DEFAULT-REPO-USERNAME is the user name that can write to KP-DEFAULT-REPO. You can docker push to this location with this credential.
    • For Google Cloud Registry, use kp_default_repository_username: _json_key.
    • Alternatively, you can configure this credential as a secret reference.
  • KP-DEFAULT-REPO-PASSWORD is the password for the user that can write to KP-DEFAULT-REPO. You can docker push to this location with this credential.
    • For Google Cloud Registry, use the contents of the service account JSON file.
    • Alternatively, you can configure this credential as a secret reference.
  • SERVER-NAME is the host name of the registry server. Examples:
    • Harbor has the form server: "my-harbor.io".
    • Docker Hub has the form server: "index.docker.io".
    • Google Cloud Registry has the form server: "gcr.io".
  • REPO-NAME is where workload images are stored in the registry. If this key is passed through the shared section earlier and AWS ECR registry is used, you must ensure that the SERVER-NAME/REPO-NAME/buildservice and SERVER-NAME/REPO-NAME/workloads exist. AWS ECR expects the paths to be pre-created. Images are written to SERVER-NAME/REPO-NAME/workload-name. Examples:
    • Harbor has the form repository: "my-project/supply-chain".
    • Docker Hub has the form repository: "my-dockerhub-user".
    • Google Cloud Registry has the form repository: "my-project/supply-chain".
  • SSH-SECRET-KEY is the SSH secret key in the developer namespace for the supply chain to fetch source code from and push configuration to. This field is only required if you use a private repository, otherwise, leave it empty. See Git authentication for more information.
  • GIT-CATALOG-URL is the path to the catalog-info.yaml catalog definition file. You can download either a blank or populated catalog file from the Tanzu Application Platform product page. Otherwise, you can use a Backstage-compliant catalog you’ve already built and posted on the Git infrastructure.
  • MY-DEV-NAMESPACE is the name of the developer namespace. SCST - Store exports secrets to the namespace, and SCST - Scan deploys the ScanTemplates there. This allows the scanning feature to run in this namespace. If there are multiple developer namespaces, use ns_for_export_app_cert: "*" to export the SCST - Store CA certificate to all namespaces.
  • TARGET-REGISTRY-CREDENTIALS-SECRET is the name of the secret that contains the credentials to pull an image from the registry for scanning.

If you use custom CA certificates, you must provide one or more PEM-encoded CA certificates under the ca_cert_data key. If you configured shared.ca_cert_data, Tanzu Application Platform component packages inherit that value by default.

If you use AWS, the default settings create a classic LoadBalancer. To use the Network LoadBalancer instead of the classic LoadBalancer for ingress, add the following to your tap-values.yaml:

contour:
  infrastructure_provider: aws
  envoy:
    service:
      aws:
        LBType: nlb

CEIP policy disclosure

Tanzu Application Platform is part of VMware’s CEIP program where data is collected to help improve the customer experience. By setting ceip_policy_disclosed to true (not a string), you acknowledge the program is disclosed to you and you are aware data collection is happening. This field must be set for the installation to be completed.

See Opt out of telemetry collection for more information.

(Optional) Additional Build Service configurations

The following tasks are optional during the Tanzu Application Platform installation process:

(Optional) Configure your profile with full dependencies

When you install a profile that includes Tanzu Build Service, Tanzu Application Platform is installed with the lite set of dependencies. These dependencies consist of buildpacks and stacks required for application builds.

The lite set of dependencies do not contain all buildpacks and stacks. To use all buildpacks and stacks, you must install the full dependencies. For more information about the differences between lite and full dependencies, see About lite and full dependencies.

To configure full dependencies, add the key-value pair exclude_dependencies: true to your tap-values.yaml file under the buildservice section. For example:

buildservice:
  kp_default_repository: "KP-DEFAULT-REPO"
  kp_default_repository_username: "KP-DEFAULT-REPO-USERNAME"
  kp_default_repository_password: "KP-DEFAULT-REPO-PASSWORD"
  exclude_dependencies: true

After configuring full dependencies, you must install the dependencies after you have finished installing your Tanzu Application Platform package. See Install the full dependencies package for more information.

(Optional) Configure your profile with the Jammy stack only

Tanzu Application Platform v1.3.0 supports building applications with the Ubuntu 22.04 (Jammy) stack. By default, workloads are built with Ubuntu 18.04 (Bionic) stack. However, if you do not need access to the Bionic stack, you can install Tanzu Application Platform without the Bionic stack and all workloads are built with the Jammy stack by default.

To install Tanzu Application Platform with Jammy as the only available stack, include the stack_configuration: jammy-only field under the buildservice: section in tap-values.yaml.

(Optional) Exclude Image Policy Webhook

Image Policy Webhook is deprecated. To exclude this package, update your tap-values file with a section listing the exclusion:

...
excluded_packages:
  - image-policy-webhook.signing.apps.tanzu.vmware.com
...

See Exclude packages from a Tanzu Application Platform profile for more information.

Install your Tanzu Application Platform package

Follow these steps to install the Tanzu Application Platform package:

  1. Install the package by running:

    tanzu package install tap -p tap.tanzu.vmware.com -v $TAP_VERSION --values-file tap-values.yaml -n tap-install
    
  2. Verify the package install by running:

    tanzu package installed get tap -n tap-install
    

    This can take 5-10 minutes because it installs several packages on your cluster.

  3. Verify that the necessary packages in the profile are installed by running:

    tanzu package installed list -A
    
  4. If you configured full dependencies in your tap-values.yaml file, install the full dependencies by following the procedure in Install full dependencies.

Important

After installing the full profile on your cluster, you must set up developer namespaces. Otherwise, creating a workload, a Knative service or other Tanzu Application Platform packages fails. For more information, see Set up developer namespaces to use installed packages.

You can run the following command after reconfiguring the profile to reinstall the Tanzu Application Platform:

tanzu package installed update tap -p tap.tanzu.vmware.com -v $TAP_VERSION  --values-file tap-values.yaml -n tap-install

Install the full dependencies package

If you configured full dependencies in your tap-values.yaml file in Configure your profile with full dependencies earlier, you must install the full dependencies package.

For more information about the differences between lite and full dependencies, see About lite and full dependencies.

To install the full dependencies package:

  1. If you have not done so already, add the key-value pair exclude_dependencies: true to your tap-values.yaml file under the buildservice section. For example:

    buildservice:
      kp_default_repository: "KP-DEFAULT-REPO"
      kp_default_repository_username: "KP-DEFAULT-REPO-USERNAME"
      kp_default_repository_password: "KP-DEFAULT-REPO-PASSWORD"
      exclude_dependencies: true
    ...
    
  2. Get the latest version of the buildservice package by running:

    tanzu package available list buildservice.tanzu.vmware.com --namespace tap-install
    
  3. Relocate the Tanzu Build Service full dependencies package repository by running:

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

    Where VERSION is the version of the buildservice package you retrieved in the previous step.

  4. Add the Tanzu Build Service full dependencies package repository by running:

    tanzu package repository add tbs-full-deps-repository \
      --url ${INSTALL_REGISTRY_HOSTNAME}/${INSTALL_REPO}/tbs-full-deps:VERSION \
      --namespace tap-install
    

    Where VERSION is the version of the buildservice package you retrieved earlier.

  5. Install the full dependencies package by running:

    tanzu package install full-tbs-deps -p full-tbs-deps.tanzu.vmware.com -v VERSION -n tap-install
    

    Where VERSION is the version of the buildservice package you retrieved earlier.

Access Tanzu Application Platform GUI

To access Tanzu Application Platform GUI, you can use the host name that you configured earlier. This host name is pointed at the shared ingress. To configure LoadBalancer for Tanzu Application Platform GUI, see Accessing Tanzu Application Platform GUI.

You’re now ready to start using Tanzu Application Platform GUI. Proceed to the Getting Started topic or the Tanzu Application Platform GUI - Catalog Operations topic.

Exclude packages from a Tanzu Application Platform profile

To exclude packages from a Tanzu Application Platform profile:

  1. Find the full subordinate (child) package name:

    tanzu package available list --namespace tap-install
    
  2. Update your tap-values file with a section listing the exclusions:

    profile: PROFILE-VALUE
    excluded_packages:
      - tap-gui.tanzu.vmware.com
      - service-bindings.lab.vmware.com
    
Important

If you exclude a package after performing a profile installation including that package, you cannot see the accurate package states immediately after running tap package installed list -n tap-install. Also, you can break package dependencies by removing a package. Allow 20 minutes to verify that all packages have reconciled correctly while troubleshooting.

Next steps

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