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 to true.

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:

 
flowchart BT

    subgraph Kong Konnect
        direction LR

        KonnectAPI(Konnect APIs)
    end

    subgraph Kubernetes cluster
        direction LR

        KGO(Kong Gateway Operator)
        K8sAPIServer( API server)
    end

    KGO -.-> |configuration synchronization| KonnectAPI
    K8sAPIServer -.-> |events| KGO

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

Below diagram illustrates the algorithm:

 
flowchart TB

classDef decision fill:#d0e1fb
classDef start fill:#545454,stroke:none,color:#fff

    k8sResourceCreated(Kubernetes resource created)
    k8sResourceUpdated(Kubernetes resource updated)
    rLoopStart[Operator reconciliation start]
    failure[Assign object's status conditions to indicate failure]
    resourceSpecChanged{Resource spec, annotations or labels changed?}
    waitForSync["Wait until sync period passes (default 1m)
    (Prevent API rate limiting)"]
    createSuccess[Assign object's ID, OrgID, ServerURL and status conditions]
    hasReferences{If object has references, are they all valid?}
    isAlreadyCreated{Object already created?}
    syncPeriodPassed[Sync period passed]
    updateKonnectEntity[Call Konnect API's update]
    wasUpdateSuccessful{Was update successful?}
    wasCreateSuccessful{Was create successful?}
    callCreate[Call Konnect API's create]

    k8sResourceCreated --> rLoopStart
    rLoopStart --> isAlreadyCreated
    isAlreadyCreated -->|Yes| waitForSync
    isAlreadyCreated -->|No| hasReferences
    hasReferences -->|Yes| callCreate
    hasReferences -->|No| failure
    callCreate --> wasCreateSuccessful
    wasCreateSuccessful -->|Yes| createSuccess
    wasCreateSuccessful -->|No| failure
    k8sResourceUpdated --> resourceSpecChanged
    resourceSpecChanged -->|Yes| updateKonnectEntity
    resourceSpecChanged -->|No| waitForSync
    createSuccess --> waitForSync
    waitForSync --> syncPeriodPassed
    syncPeriodPassed --> updateKonnectEntity
    updateKonnectEntity --> wasUpdateSuccessful
    wasUpdateSuccessful -->|Yes| waitForSync
    wasUpdateSuccessful -->|No| failure
    failure -->rLoopStart

class hasReferences,wasCreateSuccessful,wasUpdateSuccessful decision
class k8sResourceCreated,k8sResourceUpdated start

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