Installing API portal for VMware Tanzu using Helm

Last Updated January 07, 2025

This page provides 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 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 product listing.
In the Releases list, select the version that you want 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

Relocate the API portal 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 loads the API portal images and pushes them into the image registry. This script also generates 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:
```

For more information about the properties in this file, see Additional Configuration during Installation.

Install

To start the API portal installation, use the scripts/install-api-portal.sh script. Before executing this script, you can configure additional install values, SSO, or API Key Management, as described in the next sections. Otherwise, you can skip directly to Run the Installation Script.

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 prefer. You can pass the file into the installation script with --values ${PATH_TO_VALUES_YAML}.

Some useful values you should consider setting 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

For more information about each setting, see Configurations.

To update the configuration, you can always update the values file and rerun the installation script.

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 want to use a different name, you can overwrite it by setting apiPortalServer.registryCredentialsSecret in the values.yaml file.

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

API portal 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. To deactivate it, set the sso.enabled property to false.

For more information, see Configure Single Sign-On (SSO).

Configure HashiCorp Vault for API Key Management (Optional)

API portal supports API key management by integrating with HashiCorp Vault.

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

Run the Installation Script

Run the script with the 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 flags you might need:

--namespace ${INSTALLATION_NAMESPACE}: The namespace in which to install the product (defaults to api-portal). The installer creates the namespace 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 instructs the installation to print all the manifests that will be applied to the cluster. This is for troubleshooting only and the installation script may not exit correctly.
--set: You can set Helm values for the installation that can overwrite what is 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 instances

To install multiple API portal instances in different namespaces (for example, finance and accounting), you can rerun the above installation steps using a different namespace wherever namespace is required.

Uninstall API portal

To uninstall API portal, run:

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

Content feedback and comments

API portal for Tanzu 1.5