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.
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
To identify a specific API portal instance provides, you can set the following fields to be displayed in the UI landing page:
description. By default,
title is set to "API portal" and
description is set to "API portal for
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"
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"
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|
||Time after which they will be refreshed (in seconds)||300 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
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.
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
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
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 220.127.116.11 80 2m51s
kubectl -n api-portal describe ingress api-portal-ingress Name: api-portal-ingress Namespace: api-portal Address: 18.104.22.168 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.
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.
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.
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
apiPortalServer: requestMemory: "512Mi" requestCpu: "100m" limitMemory: "1024Mi" limitCpu: "500m"
For more details, check the official Kubernetes documentation: Manage resources for Containers
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
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.