Configuring API portal for VMware Tanzu on Kubernetes

API portal for VMware Tanzu supports deployments in both Kubernetes and Tanzu Application Service (TAS). This guide covers the specifics for Kubernetes.

There are two ways of applying configurations:

You may specify configuration in a yaml file and supply it to the installation script with --values tag. (See Additional Configuration During Installation)
You may set environment variables on the api-portal-server deployment, and restart the deployment to apply the changes:
```
kubectl set env deployment.apps/api-portal-server KEY=VALUE
kubectl rollout restart deployment api-portal-server
```

This guide will list out the properties and the env vars available to configure for API portal for VMware Tanzu.

Modifying OpenAPI Source URL Locations

API portal for VMware Tanzu displays API Groups and detailed documentation from any OpenAPI source URL locations in JSON format. To modify the OpenAPI source URL locations, you may choose one of these two options:

Set the following properties in the values.yaml and re-run installation script:

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

Edit the deployment's environment variable API_PORTAL_SOURCE_URLS in the installation namespace and restart the deployment:

kubectl set env deployment.apps/api-portal-server \
  API_PORTAL_SOURCE_URLS="https://petstore.swagger.io/v2/swagger.json, https://petstore3.swagger.io/api/v3/openapi.json"

If you'd like API portal to trust the source URLs that are served with self signed or untrusted TLS certificates, you may choose one of htese two options:

Set the following properties in the values yaml and rerun installation script:

apiPortalServer:
  sourceUrls: "https://my-untrusted.url"
  trustInsecureSourceUrls: true

Edit deployment's environment variable API_PORTAL_TRUST_INSECURE_SOURCE_URLS in the installation namespace and restart the deployment:
```
kubectl set env deployment.apps/api-portal-server API_PORTAL_TRUST_INSECURE_SOURCE_URLS=true
```

Modify Title & description

To identify a specific API portal instance, you can set the following fields to be displayed in the UI landing page: title and description. By default, title is set to "API portal" and description is set to "API portal for namespace".

To change the default values, set the properties using values.yaml or environment variable directly in the deployment:

apiPortalServer:
   title: "Changed title"
   description: "This is my new description"

kubectl set env deployment.apps/api-portal-server API_PORTAL_TITLE="Changed Title"
kubectl set env deployment.apps/api-portal-server API_PORTAL_DESCRIPTION="Changed Description"

Deactivate Try it out button

By default, the "try it out button" is enabled for each API group configured. If you would like to turn it off across the whole API portal instance, you can use either the values.yaml file or environment variable directly in the deployment:

apiPortalServer:
   tryItOutEnabled: false

kubectl set env deployment.apps/api-portal-server API_PORTAL_TRY_IT_OUT_ENABLED="false"

Configure OpenAPI Source URLs Cache Time-to-live and Request Timeout

To improve performance and reduce traffic, API portal caches OpenAPI descriptors locally. The following options are available:

K8s Installation Yaml Property Key	Environment Variable Key	Description	Default value
`apiPortalServer.sourceUrlsCacheTtlSec`	`API_PORTAL_SOURCE_URLS_CACHE_TTL_SEC`	Time after which they will be refreshed (in seconds)	300 sec
`apiPortalServer.sourceUrlsTimeoutSec`	`API_PORTAL_SOURCE_URLS_TIMEOUT_SEC`	Timeout for remote OpenAPI retrieval (in seconds)	10 sec

For example, to modify the cache ttl to 2 minutes, and timeout to 1 minutes, you may add the following properties to the installation yaml file:

apiPortalServer:
    sourceUrlsCacheTtlSec: "120"
    sourceUrlsTimeoutSec: "60"

Alternatively you may set environment variable:

kubectl set env deployment.apps/api-portal-server API_PORTAL_SOURCE_URLS_CACHE_TTL_SEC=120
kubectl set env deployment.apps/api-portal-server API_PORTAL_SOURCE_URLS_TIMEOUT_SEC=60

Configure External Access

API portal has an associated service of type ClusterIP. You can expose this service via common Kubernetes approaches such as ingress routing or port forwarding. Consult your cloud provider's documentation for Ingress options available to you.

Automatic HTTPProxy creation [Only with Tanzu CLI installation]

If you are installing API portal as part of a Tanzu Application Platform (TAP) installation, VMware recommends leveraging Contour's HTTPProxy.

API portal offers a configuration that automatically exposes its associated service by creating an HTTPProxy resource with a custom domain. In order to configure the domain, the following property is available:

ingressDomain (Default: ""): Domain name for the exposed service of API portal.

Example:

apiPortalServer:
  ingressDomain: example.com

If you also configure an Ingress Issuer, this exposed service will use TLS automatically.

The domain name will be prepended with the api-portal value, e.g.: api-portal.example.come

Using an Ingress Resource

Before adding an Ingress, ensure that you have an ingress controller running in your Kubernetes cluster according to your cloud provider documentation.

To use an Ingress resource for exposing an API portal instance:

In the namespace where the API portal was created, locate the ClusterIP service associated with the api-portal-server.

Create a file called ingress-config.yaml, with the following YAML definition:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-portal-ingress
  namespace: api-portal
  annotations:
    kubernetes.io/ingress.class: contour
spec:
  rules:
  - host: api-portal.my-example-domain.com
    http:
      paths:
      - pathType: Prefix
        path: "/"
        backend:
          service:
            name: api-portal-server
            port:
              number: 8080

For the host and serviceName values, substitute your desired hostname and service name.

This example Ingress resource configuration uses the Project Contour Ingress Controller. You can adapt the example configuration if you wish to use another Ingress implementation.

Apply the Ingress definition file. The Ingress resource will be created in the same namespace that the Gateway instance.

Examine the newly created Ingress resource:

kubectl -n api-portal get ingress api-portal-ingress

NAME                  CLASS    HOSTS                                     ADDRESS       PORTS   AGE
api-portal-ingress    <none>   api-portal.my-example-domain.com          34.69.53.79   80      2m51s

kubectl -n api-portal describe ingress api-portal-ingress

Name:             api-portal-ingress
Namespace:        api-portal
Address:          34.69.53.79
Default backend:  default-http-backend:80 (<error: endpoints "default-http-backend" not found>)
Rules:
  Host                                     Path  Backends
  ----                                     ----  --------
  api-portal.my-example-domain.com
                                           /   api-portal-server:80 ()

As the example output shows, the api-portal.my-example-domain.com virtual host in the Ingress definition is mapped to the api-portal-server service on the backend.

Ensure that you can resolve the Ingress definition hostname (in this example, api-portal.my-example-domain.com) to the IP address of the Ingress resource.

The IP address is shown in the Address field of the output from the kubectl describe command.

For local testing, use the command below to open your /etc/hosts file.
```
sudo vim /etc/hosts
```
Resolve the hostname by adding a line to the hosts file.
```
34.69.53.79     api-portal.my-example-domain.com
```
For extended evaluation, you might create a wildcard DNS A record that maps any virtual host on the domain name (for example, *.my-example-domain.com) to the Ingress resource.
You should now be able to connect to your API portal via the Ingress resource, using a web browser or an HTTP client such as HTTPie or cURL.
```
http api-portal.my-example-domain.com
```

Spring Cloud Gateway CORS Configuration and Self-signed Cert Configuration

In order for API portal for VMware Tanzu to support trying out APIs in the web browser, the OpenAPI locations provided in API_PORTAL_SOURCE_URLS must allow CORS access from the API portal URL. In the case of Spring Cloud Gateway, their CORS configuration must be configured to allow this access. Please review the documentation for CORS configuration for the Spring Cloud Gateway product you are using:

In case the OpenAPI server url uses self-signed certs, you might need to do the following steps for your system to trust the cert and use some features on API portal.

In MacOS:

Open the server URL in a new Safari tab
In the dialogue, click "Visit site anyway" and enter password
The self-signed cert will now be imported into Safari and try it out works

Resources: CPU and memory

The resources used by API portal can be configured in the values yaml file using the next properties:

requestMemory (Default: 512Mi): memory requested for the API portal container used to decide which Kubernetes node should be used for that instance (See units for memory)
requestCpu (Default: 100m): CPU requested for the API portal container used to decide which Kubernetes node should be used for that instance (See units for CPU)
limitMemory (Default: 1024Mi): if the container exceeds the memory limit, the container will be terminated or restarted
limitCpu (Default: 500m): the container will not be allowed to exceed this limit except for extended periods of time. However, the container will not be terminated

Example:

apiPortalServer:
  requestMemory: "512Mi"
  requestCpu: "100m"
  limitMemory: "1024Mi"
  limitCpu: "500m"

For more details, check the official Kubernetes documentation: Manage resources for Containers

Working with TLS

Security is one of the foremost concerns of VMware. API portal supports multiple mechanisms to allow the user configure TLS when connecting to source URLs, and also to expose an HTTPProxy when defining a custom domain name.

Using cert-manager ClusterIssuer

API portal is currently integrated with cert-manager's ClusterIssuer. This integration allows API portal to set and use a cluster-wide generated certificate to provide secured connections.

The integration with a functional ClusterIssuer can be configured using the following property:

ingressIssuer (Default: ""): Name of the ClusterIssuer that generates and issues certificates.

Example:

apiPortalServer:
  ingressIssuer: tap-ingress-selfsigned

By configuring this property, API portal will automatically:

Set any source URL that exposes an OpenAPI specification that also terminates in a TLS connection using a certificate issued by the same ClusterIssuer. This is achieved by including the certificate issued in the trust store of API portal's application.
Configure any exposed API portal service externally via HTTPProxy with a TLS connection. If you want to read more about how to automatically create and leverage Contour's HTTPProxy, read Automatic HTTPProxy creation.

Using TLS with a custom Certificate Authority

API portal allows the usage of self-signed certificates from custom Certification Authorities (CA) in order to establish trusted connections to source URLs serving the content via TLS (HTTPS).

The certificate can be configured using the following property:

caCertData (Default: ""): The certificate needs to be provided in PEM format

Example:

apiPortalServer:
  caCertData: |
    -----BEGIN CERTIFICATE-----
    MIIFujCCA6ICCQCWR6GMZy9sdDANBgkqhkiG9w0BAQsFADCBnjELMAkGA1UEyepe
    [...]
    SlEBuydoZmdxkB92wXAJzugjOt+jlT4+I7LYnhjm
    -----END CERTIFICATE-----

Make sure the property trustInsecureSourceUrls is not set to true if you want API portal to use properly the custom CA certificate.

Provide custom TLS to HTTPProxy [Only with Tanzu CLI installation]

As explained in the Automatic HTTPProxy creation section, API portal creates an HTTPProxy resource automatically for users that define the ingressDomain value. And if ingressIssuer is also defined, as documented in using cert-manager ClusterIssuer, the HTTPProxy resource is configured with TLS with a certificate requested from the specified ingress-issuer.

API portal allows overriding that TLS configuration for the HTTPProxy resource via this set of parameters:

ingressTls.secretName (Default: ""): Name of the Kubernetes TLS secret that contains the desired TLS certificate, its related key, and potentially the CA certificate that was used to sign the server certificate.
ingressTls.namespace (Default: ""): Namespace of the Kubernetes TLS secret. If left empty, the secret is assumed to be in the same namespace of the deployment of API portal.

Example:

apiPortalServer:
  ingressTls:
    secretName: tls-secret
    namespace: tls-secret-namespace
  ingressDomain: domain-used-by.me

Note: If the secret is located in a different namespace than API portal, a TLSCertificateDelegation resource is needed to delegate the usage of that certificate.
API portal will create this resource automatically alongside the HTTPProxy resource. Learn more about different use cases using this link: Contour Documentation - TLS Certificate Delegation.

Defining ingressIssuer in the values.yaml file of API portal automatically puts a Certificate in the configuration of the HTTPProxy resource. In order to leverage a custom cert-manager's Issuer to provide self-signed TLS with this configuration, these are the steps that you need to follow to generate a certificate to be used in API portal:

Create a certificate.yaml file that defines an issuer and a certificate. For example:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: ca-issuer
  namespace: api-portal
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: api-portal-cert
  namespace: api-portal
spec:
  secretName: api-portal-cert-secret
  dnsNames:
  - api-portal.INGRESS-DOMAIN
  issuerRef:
    name: ca-issuer

Where INGRESS-DOMAIN is the value that will match the ingressDomain value that will be used when installing API portal.

Add the issuer and certificate to your cluster by running:
```
kubectl apply -f certificate.yaml
```

Configure API portal to use the newly created certificate. Update the values used during installation to include the following:

apiPortalServer:
  ingressTls:
    secretName: api-portal-cert-secret
    secretNamespace: api-portal
  ingressDomain: INGRESS-DOMAIN
  # Additional configuration below this line as needed