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 process, ensure that you have installed the following tools on your local machine:

  • the tanzu cli and Package plugin. Instructions for installing tanzu cli and Package plugin can be found here.
  • the Tanzu Application Platform (TAP) Package Repository. Instructions for installing TAP Package Repository can be found here.

The TAP repository allows you to easily install and manage multiple versions of API portal among its available packages.

Viewing API portal among your installable packages in the TAP repo

You can verify 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 TAP repo installation, e.g. tap-install.

You should see a result similar to:

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

You can check what 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 TAP repo installation, e.g. tap-install.

You should see a result similar to:

/ Retrieving package versions for api-portal.tanzu.vmware.com...
  NAME                         VERSION                         RELEASED-AT
  api-portal.tanzu.vmware.com  1.0.8                           2021-12-15 19:00:00 -0500 EST
  api-portal.tanzu.vmware.com  1.0.9                           2022-01-02 19:00:00 -0500 EST
  api-portal.tanzu.vmware.com  1.1.0                           ...

The API portal has several configurations that can be overridden during installation. To see the values, along with 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 repo installation, e.g. tap-install.
  • where ${VERSION} is the version you wish to install, e.g. 1.1.0.

You should see a result similar to:

| 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, check out 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 VMware Tanzu Network. 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 make use of the Carvel secretgen-controller to expose them to the namespace with a SecretExport.

Installing API portal with defaults

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

sso:
  secretName: sso-credentials

or for SSO disabled:

sso:
  enabled: false

Then, you can run:

tanzu package install api-portal -n ${TAP_NAMESPACE} -p api-portal.tanzu.vmware.com -v ${VERSION} -f values.yaml
  • where ${TAP_NAMESPACE} is the namespace you created during TAP repo installation, e.g. tap-install.
  • where ${VERSION} is the version you wish to install, e.g. 1.1.0.

You should see a result similar to:

/ 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}'

Now, you should see API portal deployed and running in api-portal namespace.

Installing API portal with Overrides

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

    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

sso:
  enabled: true
  secretName: sso-credentials
  apiManager:
    roles: manager
    rolesAttributeName: teams
  session:
    distributed: true
    geode:
      server:
        replicaCount: 3
        resources:
          requests:
            memory: "512Mi"
            cpu: "200m"
          limits:
            memory: "1024Mi"
            cpu: "1"
      locator:
        replicaCount: 2
        resources:
          requests:
            memory: "512Mi"
            cpu: "1"
          limits:
            memory: "1024Mi"
            cpu: "2"

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

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

You can always update the values file and rerun the tanzu cli command to update API portal for VMware Tanzu.

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

You will see a result similar to installing with defaults.

Configure Installation Namespace [Optional]

By default, the API portal for VMware Tanzu service will be deployed in the api-portal namespace. If you want to use a different namespace, you can configure the namespace in your values.yaml like so:

apiPortalServer:
  namespace: different-api-portal-namespace

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 enabled by default and can be disabled by setting sso.enabled property to false.

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

Installing multiple API portal instances

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

values-finance.yaml:

apiPortalServer:
  namespace: finance

values-accounting.yaml:

apiPortalServer:
  namespace: accounting

Then use the tanzu cli to install:

tanzu package install api-portal-finance -n ${NAMESPACE} -p api-portal.tanzu.vmware.com -v ${VERSION} -f values-finance.yaml
tanzu package install api-portal-accounting -n ${NAMESPACE} -p api-portal.tanzu.vmware.com -v ${VERSION} -f values-accounting.yaml
  • where ${NAMESPACE} is the namespace you created during TAP repo installation, e.g. tap-install. This is not the namespace where API portal is installed to.
  • where ${VERSION} is the version you wish 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 out all your installed packages, you can run:

tanzu package installed list -n ${NAMESPACE} -A
  • where ${NAMESPACE} is the namespace you created during TAP repo installation, e.g. tap-install.

You should see a result similar to:

/ 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 repo installation, e.g. tap-install.

You should see a result similar to:

/ 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}'
check-circle-line exclamation-circle-line close-line
Scroll to top icon