This topic explains key concepts you use with API Auto Registration.
You can use the full potential of API Auto Registration by using a distributed environment, as shown in the following diagrams:
The workloads that expose APIs through the supply chains cause generated APIDescriptors
. This triggers API Auto Registration’s Kubernetes controller to generate and register API entities in Tanzu Developer Portal.
Aggregate one or more CuratedAPIDescriptor
into a curated API by using APIDescriptors
. Optionally, this can trigger Spring Cloud Gateway routing resource generation for the referenced APIs.
To initiate API registration, the supply chain must create the custom resource of type APIDescriptor
automatically or through other processes. The information from this custom resource constructs an API entity in Tanzu Developer Portal.
This custom resource exposes the following text boxes:
apiVersion: apis.apps.tanzu.vmware.com/v1alpha1
kind: APIDescriptor
metadata:
name: # name of your APIDescriptor
namespace: # optional: namespace of your APIDescriptor
spec:
type: # type of the API spec. oneOf(openapi, grpc, asyncapi, graphql)
description: # description for the API exposed
system: # system that the API is part of
owner: # person/team that owns the API
location:
apiSpec:
path: # sub-path where the API spec is available (previously `location.path`)
url: # optional: static absolute base URL for the API spec
server: # base URL object where the API spec is available. oneOf(url, ref) (previously `location.baseURL`)
url: # optional: static absolute base URL for the API server
ref: # optional: object ref to oneOf(HTTPProxy, Knative Service, Ingress)
apiVersion:
kind:
name:
namespace:
The text boxes cause specific behavior in Tanzu Developer Portal:
system: my-namespace/my-other-system
or owner: my-namespace/my-other-team
text boxes.default
namespace. For example, system: default/my-default-system
Important
spec.location.path
is deprecated in favor ofspec.location.apiSpec.path
, andspec.location.baseURL
is deprecated in favor ofspec.location.server
. This change supports having a different API server location from the specification’s location. These deprecated fields will be removed in Tanzu Application Platform 1.8.
To create an APIDescriptor with a static server.url
, you must apply the following YAML to your cluster.
apiVersion: apis.apps.tanzu.vmware.com/v1alpha1
kind: APIDescriptor
metadata:
name: sample-absolute-url
spec:
type: openapi
description: A set of API endpoints to manage the resources within the petclinic app.
system: spring-petclinic
owner: team-petclinic
location:
apiSpec:
path: "/v3/api-docs.yaml"
server:
url: https://myservice.mynamespace.svc.cluster.local:6789
You can use an object reference, instead of hard coding the URL, to point to a HTTPProxy, Knative Service, or Ingress. VMware does not support referencing Kubernetes Service
with Object Ref. To point to your Kubernetes Service
directly, you can use the static URL with cluster DNS address. For example, https://myservice.mynamespace.svc.cluster.local:6789
.
This section includes an example YAML that points to an HTTPProxy from which the controller extracts the .spec.virtualhost.fqdn
as the baseURL.
apiVersion: apis.apps.tanzu.vmware.com/v1alpha1
kind: APIDescriptor
metadata:
name: sample-contour-ref
spec:
type: openapi
description: A set of API endpoints to manage the resources within the petclinic app.
system: spring-petclinic
owner: team-petclinic
location:
apiSpec:
path: "/test/openapi"
server:
ref:
apiVersion: projectcontour.io/v1
kind: HTTPProxy
name: my-httpproxy
namespace: my-namespace # optional
To use a Knative Service, your controller reads the status.url
as the baseURL. For example:
# all other fields similar to the above example
server:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: my-knative-service
namespace: my-namespace # optional
To use an Ingress instead, your controller reads the URL from the jsonPath specified. When jsonPath is left empty, your controller reads the "{.spec.rules[0].host}"
as the URL. For example:
# all other fields similar to the above example
server:
ref:
apiVersion: networking.k8s.io/v1
kind: Ingress
name: my-ingress
jsonPath: "{.spec.rules[1].host}"
namespace: my-namespace # optional
When API Auto Registration processes an APIDescriptor, it adds several fields describing the progress to the status
. Including conditions
, which provides information useful for troubleshooting. For information about the conditions, see Troubleshoot API Auto Registration.
In addition to conditions
, the status
contains other useful fields showing the resolved API’s details. The following is a list of these fields with a brief explanation of what they contain.
status:
registeredEntityURL: # Url of the corresponding API Entity in Tanzu Developer Portal
registeredTapUID: # Unique identifier for the corresponding API Entity in Tanzu Developer Portal
resolvedAPIServerURL: # Url to the API runtime server
resolvedAPISpecURL: # Url used to retrieve the full API Spec by Api Auto Registration
resolvedAPISpec: # Full API Spec as retrieved by Api Auto Registration
resolvedAPISpecHash: # Hash value of the `resolvedAPISpec`. This field can be used to see whether the spec has been updated or not.
apiSpecLastUpdateTime: # Timestamp representing the server time when API Spec was last updated. It is not guaranteed to be set in happens-before order across separate operations. It is represented in RFC3339 form and is in UTC.
To curate one or more Workload OpenAPI specifications into a single aggregated API, create a custom resource of type CuratedAPIDescriptor
. The information from this custom resource references a list of APIDescriptors and how path-based routing aggregates them.
If you specify a valid route provider, for example, spring-cloud-gateway
for Spring Cloud Gateway for Kubernetes (SCG), the API Auto Registration controller finds the SpringCloudGateway resource and automatically creates the following routing resources for you to expose your curated APIs as:
This custom resource exposes the following text boxes:
apiVersion: apis.apps.tanzu.vmware.com/v1alpha1
kind: CuratedAPIDescriptor
metadata:
name: # name of your CuratedAPIDescriptor
namespace: # optional: namespace of your CuratedAPIDescriptor
annotations:
"apis.apps.tanzu.vmware.com/route-provider": "spring-cloud-gateway" # specify route provider
spec:
type: openapi # type of the API spec. oneOf(openapi, grpc, asyncapi, graphql)
title: # title of the curated API
description: # description of the curated API spec
documentation: # documentation for the curated API spec
groupId: # groupID of the curated API.
version: # version of the curated API
apiDescriptors:
- name: # name of a APIDescriptor to include in this curated API
namespace: # namespace of the APIDescriptor
pathPrefix: # Path prefix that the API endpoints from the linked APIDescriptor should have
routeConfig:
ssoEnabled: # whether to enable SSO on the gateway to perform authentication for users
tokenRelay: # whether to enable TokenRelay on the gateway to pass along the SSO ID token to the upstream service. This setting depends on `ssoEnabled`.
filters: # additional service lever filters to set on all the endpoints in this API
- ...
There are some key behaviors generated from the text boxes:
apis.apps.tanzu.vmware.com/route-provider
annotation specified how you want to provide routing to the curated API. VMware only supports spring-cloud-gateway
.groupId
is a concept that’s aligned with API portal to group APIs from different high-availability zones/locations or with different version
.groupId
and version
identify a matching gateway that route traffic for the curated APIrouteConfig
section specifies service level configuration you add when generating the routing resource for the API. For information about spring-cloud-gateway fields, see OpenAPI route conversion.
tokenRelay: true
setting only works with SCG v2.1.3 and above.routeConfig.filters
section specifies service level filters for all the routes exposed in each API. You can add modifications to your endpoints, such as RateLimit=5,10s
or RemoveRequestHeader=X-Request-Foo
. For information about available filters, see SCG commercial filters.pathPrefix
you specified for each APIDescriptor, and adds the StripPrefix
filter to the end of the filter list to facilitate a successful path-based redirect. Additionally, you can add more StripPrefix
filters to the service level filters to skip common paths in your specifications that are not in your service.When processing an CuratedAPIDescriptor, several fields are added to the status
. One of these is conditions
, which provide information useful for troubleshooting. The conditions are explained in the Troubleshooting Guide.
In addition to conditions
the status
contains a couple of other useful fields. The following is a list of these fields with a brief explanation of what they contain.
status:
ResolvedBaseURL: # Base url to access the curated API. Empty if no route provider is configured.
ResolvedAPISpecURL: # Url to the generated aggregated API spec
AggregatedAPISpec: # Generated full API Spec as aggregated by Api Auto Registration
AggregatedAPISpecHash: # Hash of the aggregated API Spec. This field can be used to see whether the spec has been updated or not.
LastUpdateTime: # Timestamp representing the server time when API Spec was last updated. It is not guaranteed to be set in happens-before order across separate operations. It is represented in RFC3339 form and is in UTC.
MatchedGateway: # The Gateway resource the curated API is matched on. We currently only support SCG.