Skip to main content

Konnector Control Plane Mode

Overview​

By default, the konnector (the controller that syncs Kubernetes resources between the app cluster and the control plane) runs on the app cluster. This facilitates trust for the user because they can verify that the exact code that is available open source is running in their cluster.

However, it can also be advantageous to run the konnector on the control plane instead. Benefits include:

  • Reduced footprint: Minimizes the number of components running in the app cluster
  • Enhanced security: Hides the privileged service account token that the konnector uses to authenticate to the control plane
  • Centralized management: Platform operators have more control over bindings and connectivity

Architecture​

Cluster Roles by Mode​

The binding cluster is a logical role and depends on the mode:

  • Default mode: binding cluster = app cluster
  • Control plane mode: binding cluster = control plane cluster

APIServiceBinding objects and the APIServiceBinding CRD always belong to the binding cluster.

Usage​

Command Line Flags​

Enable control plane mode with the following flags:

  • --control-plane-mode: Enable control plane mode
  • --app-cluster-kubeconfig-secret-name: Name of the secret containing the app cluster kubeconfig (required)
  • --app-cluster-kubeconfig-secret-namespace: Namespace of the secret (required)
  • --app-cluster-kubeconfig-secret-key: Key in the secret data containing the kubeconfig (default: "kubeconfig")

Example​

konnector \
  --control-plane-mode \
  --app-cluster-kubeconfig-secret-name=my-app-cluster \
  --app-cluster-kubeconfig-secret-namespace=klutch-system \
  --app-cluster-kubeconfig-secret-key=kubeconfig

Implementation Details​

Default Mode (konnector on app cluster)​

  1. Initialization: The konnector loads the app cluster kubeconfig (from in-cluster config or --kubeconfig flag)

  2. Resource Location:

    • APIServiceBinding CRD: binding cluster (app cluster in this mode)
    • APIServiceBinding CRs: binding cluster (app cluster in this mode)
    • Bound service CRDs (e.g. postgresqlinstances): app cluster
    • Provider kubeconfig secrets: app cluster

  3. Informers: The konnector sets up informers to:

    • Watch APIServiceBindings in the app cluster
    • Watch secrets (containing provider kubeconfigs) in the app cluster
    • Watch namespaces and CRDs in the app cluster

  4. Resource Syncing: Resources are synchronized between provider APIs (from secrets) and the app cluster

Control Plane Mode (konnector on control plane)​

When control plane mode is enabled:

  1. Initialization: The konnector loads the control plane kubeconfig (from in-cluster config or --kubeconfig flag) and fetches the app cluster kubeconfig from the specified secret

  2. Resource Location:

    • APIServiceBinding CRD: binding cluster (control plane cluster in this mode)
    • APIServiceBinding CRs: binding cluster (control plane cluster in this mode)
    • Bound service CRDs (e.g. postgresqlinstances): app cluster (always installed where resources are synced)
    • Provider kubeconfig secrets: control plane cluster

  3. Informers: The konnector sets up informers to:

    • Watch APIServiceBindings in the control plane
    • Watch secrets (containing provider kubeconfigs) in the control plane
    • Watch namespaces and CRDs in the app cluster

  4. Resource Syncing: Resources are synchronized between provider APIs (from secrets) and the app cluster

Security Considerations​

  • The app cluster kubeconfig secret should have restricted RBAC permissions (only the konnector should be able to read it)
  • The service account token in the app cluster kubeconfig should have minimal required permissions
  • Consider using short-lived tokens and implementing token rotation
  • Network policies should restrict access to the control plane appropriately