Architecture
In this guide you’ll learn how your Kubernetes resources are synchronized against Kong Konnect.
Overview
Kong Gateway Operator 1.4.0 introduced support for managing Kong Konnect entities. It is designed to allow users drive their Konnect configuration through Kubernetes CRDs.
Note: Kong Konnect entities management is an opt-in feature. You must enable it by setting
GATEWAY_OPERATOR_ENABLE_CONTROLLER_KONNECT
environment variable totrue
.
At a high level Kong Gateway Operator, watches for changes in the Kubernetes cluster and synchronizes them against Kong Konnect.
Below diagram illustrates high level overview, how Konnect configuration is synchronized from Kubernetes resources to Konnect:
How it works
Kong Gateway Operator watches for changes in the Kubernetes cluster and synchronizes them against Konnect.
The synchronization is performed in a loop, where the operator reconciles the state of the cluster with the state of Konnect.
The algorithm is as follows:
- When a Kubernetes resource is created:
- The operator checks if it has references and whether they are valid, if not it assigns a failure condition to the resource.
- If the resource has references and they are valid, the operator calls the Konnect API’s create method.
- If the creation was unsuccessful, the operator assigns a failure condition to the resource.
- If the creation was successful, the operator assigns the resource’s ID, OrgID, ServerURL and status conditions.
- The operator enqueues the resource for update after the configured sync period passes.
- When a Kubernetes resource is updated:
- The operator checks if the resource’s spec, annotations or labels have changed.
- If the spec, annotations or labels have changed:
- The operator calls the Konnect API’s update method.
- If the update was unsuccessful, the operator assigns a failure condition to the resource.
- If the update was successful, the operator waits for the configured sync period to pass.
- The operator calls the Konnect API’s update method.
- If the spec, annotations or labels have not changed:
- If sync period has not passed, the operator enqueues the resource for update.
- If sync period has passed, the operator calls the Konnect API’s update method.
- If the update was unsuccessful, the operator assigns a failure condition to the resource.
- If the update was successful, the operator enqueues the resource for update.
- When a Kubernetes resource is deleted:
- The operator calls the Konnect API’s delete method.
- If the deletion was unsuccessful, the operator assigns a failure condition to the resource.
- If the deletion was successful, the operator removes the resource from the cluster.
- The operator calls the Konnect API’s delete method.
Below diagram illustrates the algorithm:
Kubernetes resources
Each Kubernetes resource that is mapped to a Konnect entity has several fields that indicate its status in Konnect.
Konnect native objects
Objects that are native to Konnect - they exist only in Konnect - have the following status
fields:
-
id
is the unique identifier of the Konnect entity as assigned by Kong Konnect API. If it’s unset (empty string), it means the Kong Konnect entity hasn’t been created yet. -
serverURL
is the URL of the Kong Konnect server in which the entity exists. -
organizationID
is ID of Kong Konnect Org that this entity has been created in.
You can observe these fields by running:
kubectl get <resource> <resource-name> -o yaml | yq '.status'
You should see the following output:
conditions:
...
id: 7dcf6756-b2e7-4067-a19b-111111111111
organizationID: 5ca26716-02f7-4430-9117-111111111111
serverURL: https://us.api.konghq.com
These objects are defined under konnect.konghq.com
API group.
Objects configuring Kong Gateway
Some objects can be used to configure Kong Gateway and are not native to Konnect.
These are for example KongConsumer
, KongService
, KongRoute
and KongPlugin
. They are defined under configuration.konghq.com
API group.
They can also be used in other contexts like for instance: be used for reconciliation with Kong Ingress Controller.
These objects have their Konnect status related fields nested under konnect
field. These fields are:
-
controlPlaneID
is the ID of the Control Plane this entity is associated with. -
id
is the unique identifier of the Konnect entity as assigned by Kong Konnect API. If it’s unset (empty string), it means the Kong Konnect entity hasn’t been created yet. -
serverURL
is the URL of the Kong Konnect server in which the entity exists. -
organizationID
is ID of Kong Konnect Org that this entity has been created in.
You can observe these fields by running:
kubectl get <resource> <resource-name> -o yaml | yq '.status.konnect'
You should see the following output:
controlPlaneID: 7dcf6756-b2e7-4067-a19b-111111111111
id: 7dcf6756-b2e7-4067-a19b-111111111111
organizationID: 5ca26716-02f7-4430-9117-111111111111
serverURL: https://us.api.konghq.com