Background Info: API binding propagation

note

This page contains background information that may be useful to gain a better understanding of the system or for debugging. This information is not needed for normal system operation.

Journey of an API

In this section we will cover the journey of an API definition through the stack. Initially, the API is defined in a Crossplane Configuration Package. When this package is installed to the Control Plane Cluster, the API definitions are extracted by Crossplane. To make the resource packages available for App Clusters, the Platform Operator defines an APIServiceExporttemplate. When a binding is created, either interactively or non-interactively, the App Cluster will create an APIServiceExportRequest on the Control Plane Cluster.

Upon creation of the APIServiceExportRequest the backend will grant the App Cluster's Service Account the necessary permissions to interact with the requested API and its related objects. Afterwards the backend creates an APIServiceExport object that contains a snapshot of the bound CRD at the time of binding.

The application developer then applies an APIServiceBinding object to their cluster. In the interactive binding process this is done by the kubectl bind command. In the non-interactive binding process the object's YAML is given to the user by the helper CLI, and applied out of band. This event is picked up by the Konnector installed in the App Cluster. The Konnector will read the APIServiceBinding object and attempt to find a matching APIServiceExport on the Control Plane Cluster. If a matching Object is found the Konnector reads the API schema from the APIServiceExport and creates a Custom Resource Definition (CRD) with a matching schema on the App Cluster. This process runs continuously and will pick up changes and new APIs as they are added.

Updating provider APIs

Updating of API major versions is currently not supported. Non breaking updates to the API are supported.

danger

Breaking API changes are not prevented automatically. Please make sure that the API you are updating does not have any breaking changes.

anynines will not introduce breaking changes to the Data Service APIs until safe migrations are supported.

The API definitions for anynines Data Services are contained in the Configuration package. To update the APIs, update the package. This updates the API on the provider cluster.

Coming soon, updates to APIs on the Control Plane Cluster will be automatically distributed to the App Clusters.

When a change to a CRD that is referenced by an APIServiceExportTemplate is detected, all APIServiceExports will be modified to include the new change. The Konnector on App Clusters will detect this change in the APIServiceExport and update the local CRDs accordingly.

Adding new APIs

Adding a new API, for example a new Data Service requires a new binding creation. This means the creation of a APIServiceExport on the Control Plane Cluster and the creation of a APIServiceBinding on the Tenant Cluster.

The easiest way to create them is to follow the process for new bindings. Either the interactive or non-interactive process will work. Remember to add the new service info to the non-interactive bind binding.json