Installing API portal for VMware Tanzu using the Tanzu CLI

Last Updated January 07, 2025

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

Prerequisites

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

the Tanzu CLI and Package plug-in. For instructions, see the Install Tanzu Application Platform in the TAP documentation.
the Tanzu Application Platform (TAP) Package Repository. For instructions, see the Install Tanzu Application Platform in the TAP documentation.

The TAP repository includes the API portal among its packages.

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

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

This requires the creation of an SSO secret. API portal looks for a secret with the name sso-credentials, by default. You can customize it to use a values file; see Installing API portal with Overrides.

SSO can also be enabled later; that requires restarting the API portal component.

To see the steps read Configure Single Sign-On (SSO).

Viewing API portal among your installable packages in the TAP repository

You can verify that the API portal is available to install from the TAP repository by running:

tanzu package available list -n ${TAP_NAMESPACE}

Where ${TAP_NAMESPACE} is the namespace you created during the TAP repository installation; for example, tap-install.

You should see a result similar to the following:

/ Retrieving available packages...
  NAME                         DISPLAY-NAME  SHORT-DESCRIPTION
  api-portal.tanzu.vmware.com  API portal    API portal

You can check which versions of API portal are available to install by running:

tanzu package available list -n ${TAP_NAMESPACE} api-portal.tanzu.vmware.com

Where ${TAP_NAMESPACE} is the namespace you created during the TAP repository installation; for example, tap-install.

You should see a result similar to the following:

/ Retrieving package versions for api-portal.tanzu.vmware.com...
  NAME                         VERSION                         RELEASED-AT
  api-portal.tanzu.vmware.com  1.5.0                           2024-03-15 19:00:00 -0500 EST
  api-portal.tanzu.vmware.com  1.4.7                           2024-01-16 19:00:00 -0500 EST
  api-portal.tanzu.vmware.com  1.4.6                           ...

The API portal has several configurations that can be overridden during installation. To see the values and their defaults, run:

tanzu package available get -n ${TAP_NAMESPACE} api-portal.tanzu.vmware.com/${VERSION} --values-schema

Where:

${TAP_NAMESPACE} is the namespace you created during TAP repository installation; for example, tap-install.
${VERSION} is the version you want to install; for example, 1.5.0.

You should see a result similar to the following:

/ Retrieving package details for api-portal.tanzu.vmware.com/${VERSION}...
  KEY                                    DEFAULT
  sso.enabled                            true
  sso.secretName
  apiKey.enabled                         false
  apiKey.vault.role
  apiKey.vault.url
  apiPortalServer.title                  API portal
  apiPortalServer.description            API portal for <namespace> namespace
  apiPortalServer.limitMemory            1024Mi
  apiPortalServer.namespace              api-portal
  apiPortalServer.replicaCount           1
  apiPortalServer.requestMemory          512Mi
  apiPortalServer.sourceUrls             https://petstore.swagger.io/v2/swagger.json,https://petstore3.swagger.io/api/v3/openapi.json
  apiPortalServer.sourceUrlsTimeoutSec   10
  apiPortalServer.limitCpu               500m
  apiPortalServer.requestCpu             100m
  apiPortalServer.sourceUrlsCacheTtlSec  300

To override these defaults, see Installing API portal with Overrides.

Adding the image pull secret

For the Tanzu CLI to install the API portal, it requires a container registry secret to the image, which is hosted on the Broadcom Support portal. There are a number of ways to provide it:

API portal looks for a secret named api-portal-image-pull-secret. You can manually add this to your API portal installation namespace.
You might decide to keep all your secrets in a separate namespace and use the Carvel secretgen-controller to expose them to the namespace with a SecretExport.

Installation

Installing API portal with defaults

To install the API portal with default values and with SSO activated, create a values.yaml file with your values:

sso:
  secretName: sso-credentials

or for SSO deactivated:

sso:
  enabled: false

Then you can run:

tanzu package install api-portal -n ${TAP_NAMESPACE} -p api-portal.tanzu.vmware.com -v ${VERSION} --values-file values.yaml

Where:

${TAP_NAMESPACE} is the namespace you created during TAP repository installation; for example, tap-install.
${VERSION} is the version you want to install; for example, 1.5.0.

You should see a result similar to the following:

/ Installing package 'api-portal.tanzu.vmware.com'
| Getting namespace 'api-portal'
| Getting package metadata for 'api-portal.tanzu.vmware.com'
| Creating service account 'api-portal-api-portal-sa'
| Creating cluster admin role 'api-portal-api-portal-cluster-role'
| Creating cluster role binding 'api-portal-api-portal-cluster-rolebinding'
/ Creating package resource
- Package install status: Reconciling


 Added installed package 'api-portal' in namespace '${TAP_NAMESPACE}'

When this is complete, you should see API portal deployed and running in the api-portal namespace.

Installing API portal with Overrides

To install the API portal with overridden values, here are 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.

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

Here is a more detailed example of the file:

apiPortalServer:
  title: "API portal"
  description: "Description"
  replicaCount: 2
  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: ""
  ingressDomain: ""
  ingressIssuer: ""

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

For more information about each setting, see Configurations.

You can update the values file any time, and rerun the Tanzu CLI command to update API portal.

tanzu package installed update api-portal -n ${TAP_NAMESPACE} -p api-portal.tanzu.vmware.com -v ${VERSION} --values-file values.yaml

You will see a result similar to the output shown in Installing with defaults.

Configure Installation Namespace (Optional)

By default, the API portal service is deployed in the api-portal namespace. If you want to use a different namespace, you can configure the namespace in your values.yaml as shown here:

apiPortalServer:
  namespace: different-api-portal-namespace

Installing multiple API portal instances

To install multiple API portal instances in different namespaces; finance and accounting, for example, create two values.yaml files:

values-finance.yaml:

apiPortalServer:
  namespace: finance

values-accounting.yaml:

apiPortalServer:
  namespace: accounting

Then use the Tanzu CLI to install API portal to each one:

tanzu package install api-portal-finance -n ${NAMESPACE} -p api-portal.tanzu.vmware.com -v ${VERSION} --values-file values-finance.yaml
tanzu package install api-portal-accounting -n ${NAMESPACE} -p api-portal.tanzu.vmware.com -v ${VERSION} --values-file values-accounting.yaml

Where:

${NAMESPACE} is the namespace you created during TAP repository installation; for example, tap-install. This is not the namespace where API portal is installed.
${VERSION} is the version you want to install. Requires 1.0.4 and above.

Note here the parameter to tanzu package install differs between the two instances. You cannot use the same value across multiple installations.

Listing API portal installations

To list all your installed packages, run:

tanzu package installed list -n ${NAMESPACE} -A

Where ${NAMESPACE} is the namespace you created during TAP repository installation; for example, tap-install.

You should see a result similar to the following:

/ Retrieving installed packages...
  NAME                   PACKAGE-NAME                 PACKAGE-VERSION  STATUS               NAMESPACE
  api-portal             api-portal.tanzu.vmware.com  1.0.4            Reconcile succeeded  tap-install
  api-portal-accounting  api-portal.tanzu.vmware.com  1.0.4            Reconcile succeeded  tap-install
  api-portal-finance     api-portal.tanzu.vmware.com  1.0.4            Reconcile succeeded  tap-install

Uninstalling API portal

To uninstall the API portal, run:

tanzu package installed delete api-portal -n ${TAP_NAMESPACE} -y

Where ${TAP_NAMESPACE} is the namespace you created during TAP repository installation; for example, tap-install.

You should see a result similar to the following:

/ Getting package install for 'api-portal'
/ Deleting package install 'api-portal' from namespace '${NAMESPACE}'
- Package uninstall status: Deleting
| Deleting admin role 'api-portal-api-portal-cluster-role'
| Deleting role binding 'api-portal-api-portal-cluster-rolebinding'
| Deleting service account 'api-portal-api-portal-sa'

 Uninstalled package 'api-portal' from namespace '${NAMESPACE}'

Content feedback and comments

API portal for Tanzu 1.5

Installing API portal for VMware Tanzu using the Tanzu CLI

Prerequisites

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

Viewing API portal among your installable packages in the TAP repository

Adding the image pull secret

Installation

Installing API portal with defaults

Installing API portal with Overrides

Configure Installation Namespace (Optional)

Installing multiple API portal instances

Listing API portal installations

Uninstalling API portal