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:

  1. You may specify configuration in a yaml file and supply it to the installation script with --values tag. (See Additional Configuration During Installation)

  2. 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:

  1. 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"
    
  2. 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:

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

    apiPortalServer:
      sourceUrls: "https://my-untrusted.url"
      trustInsecureSourceUrls: true
    
  2. 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 provides, 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"

Disable 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.

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:

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

  2. 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.

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

  4. 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.

  5. 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.

  6. 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:

  1. Open the server URL in a new Safari tab
  2. In the dialogue, click "Visit site anyway" and enter password
  3. 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 killed 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 killed

Example:

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

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

Custom CA Certificates

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-----
    MIIFujCCA6ICCQCWR6GMZy9sdDANBgkqhkiG9w0BAQsFADCBnjELMAkGA1UEBhMC
    [...]
    SlEBuydoZmdxkB92wXAJzugjOt+jlT4+I7LYnhjm
    -----END CERTIFICATE-----

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

check-circle-line exclamation-circle-line close-line
Scroll to top icon