Question: Support referencing existing Konnect Control Planes by name

[shambhand]

Question: How to reference existing Konnect Control Planes managed by Terraform?

Problem Statement

We're exploring using the Kong Gateway Operator in an environment where Konnect Control Planes are managed by Terraform (separate from Kubernetes). We'd like to use the operator only for managing KongService, KongRoute, and KongPluginBinding resources.

What We Tried

1. Created a KonnectGatewayControlPlane resource with the same name as our Terraform-managed control plane:

   apiVersion: konnect.konghq.com/v1alpha1
   kind: KonnectGatewayControlPlane
   metadata:
     name: my-control-plane
   spec:
     name: "my-control-plane"  # Same name as in Konnect
     konnect:
       authRef:
         name: konnect-api-auth

   Result: 409 Conflict - The operator tries to create a new control plane instead of adopting the existing one.

   {"status":409,"title":"Conflict","detail":"Key (org_id, name)=(xxx, my-control-plane) already exists."}

2. Tried using konnectID reference type to reference the control plane by UUID:

   controlPlaneRef:
     type: konnectID
     konnectID: "6ad62d79-856e-4976-add5-b086eca035e9"

   Result: 'konnectID' type is not supported

3. Tried cross-namespace reference with konnectNamespacedRef:

   Result: spec.controlPlaneRef cannot specify namespace for namespaced resource

Our Questions

1. Is there a way to "adopt" an existing Konnect control plane that was created outside of Kubernetes (e.g., by Terraform)? Perhaps an annotation or spec field we're missing?

2. Is there a supported way to reference a control plane by ID or name without needing a KonnectGatewayControlPlane K8s resource?

3. Are we using the operator incorrectly for this use case? Should we be using a different approach?

4. Is this use case on the roadmap if it's not currently supported?

---

Our Use Case

We have a multi-team architecture:

┌─────────────────────────────────────────────────────────────┐
│ PLATFORM TEAM (Terraform)                                    │
│   Manages: Control Planes, Data Planes, Certificates        │
│   Reason: Centralized infrastructure management             │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ APPLICATION TEAMS (Kubernetes + ArgoCD)                      │
│   Want to manage: Services, Routes, Plugins                 │
│   Reason: GitOps workflow, team autonomy                    │
└─────────────────────────────────────────────────────────────┘

We'd love to use the Kong Gateway Operator for the application layer while keeping infrastructure management in Terraform. Is this a supported pattern?

---

Proposed Solution

If this use case isn't currently supported, we'd like to suggest one of these approaches:

Idea A: Support konnectID reference type

controlPlaneRef:
  type: konnectID
  konnectID: "6ad62d79-856e-4976-add5-b086eca035e9"

Idea B: Support konnectName reference type

controlPlaneRef:
  type: konnectName
  konnectName: "my-control-plane"
  konnectAuthRef:
    name: konnect-api-auth

Idea C: Add "adopt" mode to KonnectGatewayControlPlane

metadata:
  annotations:
    konnect.konghq.com/adopt: "true"  # Don't create, sync with existing

---

Additional Information

Environment

• Kong Operator Version: v2.0.6 (latest)
• Kubernetes Version: 1.28+
• Konnect Region: US

Current Workaround

We're currently using decK via a Kubernetes Job, which works but loses the benefits of native K8s resource management:

deck gateway sync config.yaml --konnect-control-plane-name "my-control-plane"

Similar Patterns in Other Operators

We noticed other Kubernetes operators support similar patterns:

• AWS ACK: services.k8s.aws/adopted annotation
• Crossplane: External resource references
• Azure Service Operator: azureName for existing resources

---

Acceptance Criteria

• Documentation is updated with this new feature / enhancement
• Tests are added for this feature / enhancement
• Helm chart is updated to work with this feature / enhancement
• As a user, I can reference an existing Konnect control plane by name or ID
• As a user, I can use the operator with Terraform-managed control planes
• As a user, I do not need to create a KonnectGatewayControlPlane K8s resource to manage services/routes

---

Summary

We're trying to understand the best way to use the Kong Gateway Operator with externally-managed Konnect control planes.

If this is already supported, we'd appreciate any pointers to documentation or examples we might have missed.

If this is a feature gap, we'd love to understand if it's on the roadmap or if there are any workarounds we should consider.

Thank you for your time and any guidance you can provide! 🙏

---

[pmalek]

With 2.0 it's already possible to use the mirror control plane by reference via an ID.

If I'm reading your report correctly that would be exactly what you're looking for.

Exemplar manifest: https://github.com/Kong/kong-operator/blob/b264059b1c854b85f96ad8755b8c16cbf2a459ba/config/samples/konnect-control-plane-mirror.yaml

kind: KonnectGatewayControlPlane
apiVersion: konnect.konghq.com/v1alpha2
metadata:
  name: test
spec:
  source: Mirror
  mirror:
    konnect:
      id: 03b496a0-a38a-4370-8e50-111111111111
  konnect:
    authRef:
      name: konnect-api-auth

[shambhand]

@pmalek Thanks, I’ll try adopting our existing control planes with the operator YAML definition.

[github-actions[bot]]

This issue has been automatically marked as stale due to 60 days of inactivity. Please update or comment if this is still relevant.