Installing API portal for VMware Tanzu using Helm

This page will give an overview of the installation process for API portal for VMware Tanzu service on a Kubernetes cluster using Helm.

Prerequisites

Before beginning the installation process, ensure that you have installed the following tools on your local machine:

The Docker command-line interface (CLI) tool, docker. For information about installing the docker CLI tool, see the Docker documentation.
The Helm command-line interface (CLI) tool, helm. For information about installing the helm CLI tool, see the Helm documentation.

Download and Extract Installation Resources

API portal for VMware Tanzu is provided as a compressed archive file containing a series of utility scripts, manifests, and required images.

To download the components:

Visit the Broadcom Support portal and log in.
Navigate to the API portal for VMware Tanzu product listing.
In the Releases list, select the version that you wish to install.
Download "API portal for VMware Tanzu Installer".

Extract the contents of the archive file:

tar zxf api-portal-for-vmware-tanzu-[VERSION].tgz

The extracted directory contains the following directory layout:

ls api-portal-for-vmware-tanzu-[VERSION]

helm/      images/      jars/      scripts/

Relocate Images

Next, relocate the API portal for VMware Tanzu images to your private image registry. The images must be loaded into the local Docker daemon and pushed into the registry.

To relocate the images:

Use the docker CLI tool or your cloud provider CLI to authenticate to your image registry.
Run the image relocation script, located in the scripts directory.
```
./scripts/relocate-images.sh ${REGISTRY_URL}
```
Where ${REGISTRY_URL} should contain, or be changed by the URL of your image registry. For example:
```
./scripts/relocate-images.sh myregistry.example.com/api-portal
```
The script will load the API portal for VMware Tanzu images and push them into the image registry. This script will also generate a file named helm/api-portal-image-values.yaml. The contents of this file will resemble the following:
```
apiPortalServer:
  image: "myregistry.example.com/api-portal/api-portal-server:[VERSION]"
  sourceUrls:
```

More information about the properties in this file will be discussed in Additional Configuration During Installation section.

Installation

We can now proceed to API portal for VMware Tanzu installation using the scripts/install-api-portal.sh script. Before executing this script, you may want to optionally configure additional install values, SSO, or API Key Management described in the next sections first. Otherwise, you can skip directly to the Run the Installation Script section.

Additional Configuration During Installation [Optional]

You can create a yaml file containing additional configurations anywhere in your file system, and version control it if you would prefer. You can pass the file into the installation script with --values ${PATH_TO_VALUES_YAML}.

Some useful values you should consider to set before running the installation script:

apiPortalServer.sourceUrls: configure one or more Open API definitions (see Modifying OpenAPI Source URL Locations).
apiPortalServer.replicaCount: configure High Availability for API portal
sso: configure Single Sign On (see Configure Single Sign-On (SSO))
apiKey: enable api key management with connection information (see Configure API Key Management).

serviceAccount: this is an essential piece for granting access for api key management (see Configure API Key Management).

apiPortalServer:
  replicaCount: 2
  sourceUrls: "https://my-scg-operator/openapi,https://other-openapi-provider/openapi.json"

sso:
  enabled: true
  secretName: sso-credentials

apiKey:
  enabled: true
  vault:
    url: http://vault.vault.svc:8200/
    role: example-api-portal-role

serviceAccount:
  name: api-portal-service-account

Here is a more detailed example of the file:

apiPortalServer:
  title: "API portal"
  description: "Description"
  imagePullPolicy: IfNotPresent
  registryCredentialsSecret: api-portal-image-pull-secret
  replicaCount: 1
  sourceUrls: "https://my-scg-operator/openapi,https://other-openapi-provider/openapi.json"
  sourceUrlsCacheTtlSec: "300"
  sourceUrlsTimeoutSec: "10"
  requestMemory: "512Mi"
  requestCpu: "100m"
  limitMemory: "1024Mi"
  limitCpu: "500m"
  namespace: "api-portal"
  trustInsecureSourceUrls: false
  caCertData: ""

sso:
  enabled: true
  secretName: sso-credentials
  apiManager:
    roles: manager
    rolesAttributeName: teams
  session:
    distributed: true
    redisCredentialSecret: my-redis-credentials

apiKey:
  enabled: true
  vault:
    url: http://vault.vault.svc:8200/
    role: example-api-portal-role
    path: example-vault-path

serviceAccount:
  create: true
  name: api-portal

You can find more information about each setting in the Configurations section.

You can always update the values file and rerun the installation script to update API portal for VMware Tanzu.

Create Image Pull Secret [Optional]

If your cluster needs authentication to access the relocated images, then a secret must be provided before running the installation.

Make sure your credentials are safely managed and used securely during the process. You can set up environment variables for use during the installation:

export REGISTRY_HOSTNAME=MY-REGISTRY
export REGISTRY_USERNAME=MY-REGISTRY-USER
export REGISTRY_PASSWORD=MY-REGISTRY-PASSWORD
export INSTALLATION_NAMESPACE=MY-NAMESPACE

Create your installation namespace ${INSTALLATION_NAMESPACE} if it doesn't already exist and the secret within that namespace

kubectl create ns ${INSTALLATION_NAMESPACE}
kubectl create secret docker-registry api-portal-image-pull-secret -n ${INSTALLATION_NAMESPACE} \
--docker-server=${REGISTRY_HOSTNAME} \
--docker-username=${REGISTRY_USERNAME} \
--docker-password=${REGISTRY_PASSWORD}

The API portal deployment looks for a K8s secret with the name api-portal-image-pull-secret by default. If you'd like to use a different name, you can overwrite that by setting apiPortalServer.registryCredentialsSecret in the values.yaml file.

Create Secret for Single Sign-On (SSO) Integration [Optional]

API portal for VMware Tanzu supports authentication using Single Sign-On (SSO) with an OpenID Connect identity provider that supports OpenID Connect Discovery protocol.

This requires creating a secret in the installation namespace that includes the connection info for the OpenID Connect Identity Provider. SSO is activated by default and can be deactivated by setting sso.enabled property to false.

Read more about Configure Single Sign-On (SSO).

Configure HashiCorp Vault for API Key Management [Optional]

API portal for VMware Tanzu supports API key management integrating with HashiCorp Vault.

To see the detailed steps, please read Configure API Key Management.

Run the Installation Script

Run the script with defaults as shown in the following example:

./scripts/install-api-portal.sh

The installation script takes in any flags accepted by helm upgrade --install. Here are a few typical ones you might need:

--namespace ${INSTALLATION_NAMESPACE}: The namespace to install the product (defaults to api-portal). The installer will create the namespace for you if it doesn't already exist.
--values ${PATH_TO_VALUES_YAML}: The path to the yaml file containing additional values for the installation. You can specify this tag multiple times and helm will perform a deep merge on all the keys.
--dry-run: This tag would print out all the manifests that will be applied to the cluster. Please note that this is for troubleshooting only and the installation script may not exit correctly.
--set: You may set helm values for the installation that can overwrite what's set in the values yaml file.

After running the script, you should see a new deployment and service named api-portal-server in your chosen namespace, api-portal by default.

Installing multiple API portal

To install multiple API portal instances in different namespaces (e.g. finance and accounting), you can rerun the above installation steps but provide a different namespace wherever asked.

Uninstallation Steps

To uninstall API portal for VMware Tanzu, run:

helm uninstall api-portal -n ${INSTALLATION_NAMESPACE}
kubectl delete namespace ${INSTALLATION_NAMESPACE}