# [RFC/POC] Evaluate work required to add KIC standalone support for v1alpha1 Kong Gateway entity CRDs

[mcarbonneaux]

🎯 Purpose of this PR

This is a proof-of-concept submission to evaluate the real work required to implement the feature requested in #3259.

This PR is not intended for merge but rather to:

• Assess the scope and complexity of enabling v1alpha1 CRDs in KIC standalone mode
• Identify all areas of the codebase that would need modification
• Demonstrate feasibility of the requested feature
• Gather feedback from maintainers on the proposed approach before investing in a full implementation

Status:

• ✅ Code compiles successfully
• ⚠️ AI-assisted implementation (not manually tested)
• ⚠️ No tests run - this is purely exploratory
• ⚠️ First draft to estimate real effort required

📈 Code Statistics

Lines of Code:

• +2,270 lines added
• -9 lines removed
• Net change: +2,261 lines
• 19 files changed

Breakdown by component:

• Documentation: +299 lines (KIC_STANDALONE_V1ALPHA1.md)
• Controllers (generated): +899 lines
• Translation layer: +574 lines
• Store layer: +243 lines (fake_store.go, store.go, zz_generated.cache_stores.go)
• Manager setup: +105 lines
• Dependency graph: +88 lines (net change)
• Feature gate: +41 lines (spec.go, feature_gates_keys.go)
• Translation integration: +14 lines
• API type validation: -9 lines (removed validation rules)

Background - Issue #3259

The issue requests removing artificial restrictions that prevent native Kong Gateway CRDs (KongService, KongRoute, KongUpstream, etc.) from functioning in KIC standalone mode. Currently blocked by validation rule: self.controlPlaneRef.type != 'kic'.

Work Assessment Summary

Based on this exploratory implementation, enabling this feature would require:

📊 Scope of Changes

Area	Files Modified	Lines Changed	Complexity
API Types	8 CRD type files	-9 lines	Low - Remove validation rules
Code Generation	1 generator spec	+41 lines	Low - Add store definitions
Store Layer	3 files	+243 lines	Medium - Add cache & methods
Controllers	1 generated file	+899 lines	High - 8 new reconcilers
Translation Layer	1 new file	+574 lines	High - Complex type conversion logic
Dependency Graph	1 file	+88 lines	Medium - Add dependency resolution
Feature Flags	1 file	+8 lines	Low - Add feature gate
Manager Setup	1 file	+105 lines	Low - Register controllers
Translator Integration	1 file	+14 lines	Low - Wire feature gate
Documentation	1 new file	+299 lines	N/A - Technical documentation

Total actual changes: +2,270 lines added, -9 lines removed across 19 files

🔧 Key Implementation Areas

1. Remove CRD Validation Restrictions (Simple)

• Remove self.controlPlaneRef.type != 'kic' from 8 CRD specs
• Run make manifests to regenerate CRDs

2. Store Layer (Medium Complexity)

• Add cache stores for 8 new types
• Implement List methods with ingress class filtering
• Update fake store for testing

3. Controller Reconcilers (High Complexity)

• 8 new reconcilers following KIC reconciliation pattern
• Each needs: watch setup, ingress class filtering, status updates
• ~900 lines of mostly boilerplate code

4. Translation Layer (Highest Complexity)

• Convert between sdk-konnect-go/components types and go-kong types
• Handle complex nested structures (e.g., Healthchecks, Circuit Breakers)
• Implement dependency resolution (Routes→Services, Targets→Upstreams, etc.)
• Handle certificate sourcing (inline vs secretRef)
• Plugin binding resolution and target attachment

5. Dependency Graph (Medium Complexity)

• Implement dependency resolution for fallback cache
• Handle cross-namespace references where applicable

6. Testing (Not Implemented - Would Be Required)

• Unit tests for translation logic
• Envtest tests for controllers
• Integration tests for end-to-end validation
• CRD validation tests

🤔 Technical Challenges Identified

1. Type Conversion: Need to bridge sdk-konnect-go and go-kong types

   • Current approach: JSON marshal/unmarshal
   • Question: Is there a better/more efficient approach?

2. Serviceless Routes: Routes without serviceRef require placeholder service

   • Current approach: Create 0.0.0.0:1 placeholder
   • Question: Is this the correct pattern?

3. Feature Gate: Disabled by default to avoid breaking changes

   • Question: Should this be enabled by default in a future release?

4. KongKey/KongKeySet: Not implemented (no native go-kong support)

   • Question: Are these critical for v1 release?

Proposed Architecture

K8s CRDs (v1alpha1)
       │
       ├── [Pipeline 1 – KIC standalone] NEW ✨
       │       KIC watches CRs → Store → Translator → KongState → POST /config (db-less)
       │
       └── [Pipeline 2 – Konnect] UNCHANGED
               reconciler_generic reads CRs → sdk-konnect-go → Konnect REST API

Key Design Decision: Both pipelines remain independent. Konnect path untouched.

Feature Gate (Opt-in)

This feature is disabled by default and controlled by the KongServiceV1Alpha1 feature gate:

feature-gates: KongServiceV1Alpha1=true

Supported CRDs

CRD	Dependencies	Kong Entity
KongService	none	Service
KongRoute	KongService	Route
KongUpstream	none	Upstream
KongTarget	KongUpstream	Target
KongCertificate	optional Secret	Certificate
KongCACertificate	optional Secret	CA Certificate
KongSNI	KongCertificate	SNI
KongPluginBinding	KongPlugin/KongClusterPlugin	Plugin

Note: KongKey and KongKeySet are not supported in this implementation (no native field in standard go-kong KongState).

Usage Example

apiVersion: configuration.konghq.com/v1alpha1
kind: KongUpstream
metadata:
  name: my-upstream
  namespace: default
spec:
  name: my-upstream
  algorithm: round-robin
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongService
metadata:
  name: my-service
  namespace: default
spec:
  host: my-upstream
  port: 80
  protocol: http
---
apiVersion: configuration.konghq.com/v1alpha1
kind: KongRoute
metadata:
  name: my-route
  namespace: default
spec:
  serviceRef:
    type: namespacedRef
    namespacedRef:
      name: my-service
  protocols:
    - http
  paths:
    - /api

Files Changed (Detailed Statistics)

Click to expand detailed file statistics

Complete Change Statistics

File	Lines Added	Lines Removed	Net Change
KIC_STANDALONE_V1ALPHA1.md	+299	0	+299
ingress-controller/internal/controllers/configuration/zz_generated.controllers.go	+899	0	+899
ingress-controller/internal/dataplane/kongstate/kongservices_v1alpha1.go	+574	0	+574
ingress-controller/internal/manager/controllerdef.go	+105	0	+105
ingress-controller/internal/store/store.go	+98	0	+98
ingress-controller/internal/dataplane/fallback/graph_dependencies.go	+88	0	+88
ingress-controller/internal/store/zz_generated.cache_stores.go	+80	0	+80
ingress-controller/internal/store/fake_store.go	+65	0	+65
hack/generators/cache-stores/spec.go	+41	0	+41
ingress-controller/internal/dataplane/translator/translator.go	+14	0	+14
ingress-controller/pkg/manager/config/feature_gates_keys.go	+8	0	+8
api/configuration/v1alpha1/kongcacertificate_types.go	0	-1	-1
api/configuration/v1alpha1/kongcertificate_types.go	0	-1	-1
api/configuration/v1alpha1/kongdataplaneclientcertificate_types.go	0	-1	-1
api/configuration/v1alpha1/kongkey_types.go	0	-1	-1
api/configuration/v1alpha1/kongkeyset_types.go	0	-1	-1
api/configuration/v1alpha1/kongroute_types.go	0	-1	-1
api/configuration/v1alpha1/kongservice_types.go	0	-1	-1
api/configuration/v1alpha1/kongupstream_types.go	0	-1	-1
TOTAL	+2,270	-9	+2,261

Files Changed (High-Level)

Click to expand categorized file list

API Definitions:

• api/configuration/v1alpha1/kongservice_types.go
• api/configuration/v1alpha1/kongroute_types.go
• api/configuration/v1alpha1/kongupstream_types.go
• api/configuration/v1alpha1/kongtarget_types.go
• api/configuration/v1alpha1/kongcertificate_types.go
• api/configuration/v1alpha1/kongcacertificate_types.go
• api/configuration/v1alpha1/kongsni_types.go
• api/configuration/v1alpha1/kongpluginbinding_types.go
• api/configuration/v1alpha1/kongdataplaneclientcertificate_types.go
• api/configuration/v1alpha1/kongkey_types.go
• api/configuration/v1alpha1/kongkeyset_types.go

Store & Cache:

• hack/generators/cache-stores/spec.go
• ingress-controller/internal/store/store.go
• ingress-controller/internal/store/fake_store.go
• Generated: ingress-controller/internal/store/zz_generated.cache_stores.go

Controllers:

• Generated: ingress-controller/internal/controllers/configuration/zz_generated.controllers.go
• ingress-controller/internal/manager/controllerdef.go

Translation:

• NEW: ingress-controller/internal/dataplane/kongstate/kongservices_v1alpha1.go
• ingress-controller/internal/dataplane/translator/translator.go

Dependency Resolution:

• ingress-controller/internal/dataplane/fallback/graph_dependencies.go

Feature Gates:

• ingress-controller/pkg/manager/config/feature_gates_keys.go

Documentation:

• NEW: KIC_STANDALONE_V1ALPHA1.md (detailed technical documentation)

What Was NOT Changed

• Konnect reconciliation pipeline (controller/konnect/) - completely untouched
• No new CRD schemas introduced
• Existing v1alpha1 CRD functionality preserved
• No changes to Gateway API or Ingress resource handling

Estimated Real Work Required

Based on this exploration:

Development Time Estimate

• Implementation: 2-3 weeks (with proper testing)
• Testing: 1-2 weeks (unit, envtest, integration)
• Documentation: 3-5 days
• Code review iterations: 1 week
• Total: 4-6 weeks for a production-ready implementation

Testing Requirements

• Unit tests for all translation functions
• Controller reconciliation tests (envtest)
• Integration tests with real Kong Gateway
• CRD validation tests
• Backward compatibility tests (feature gate disabled)
• Konnect pipeline regression tests

Documentation Requirements

• User-facing documentation
• Migration guide
• API reference updates
• Example manifests

Questions for Maintainers

1. Is this architectural approach acceptable?

   • Separate pipeline for KIC vs Konnect
   • Feature gate to control activation

2. Type conversion strategy:

   • Is JSON marshal/unmarshal acceptable for type conversion?
   • Or should we implement manual field mapping?

3. Generated code:

   • Should reconcilers be generated or hand-written?
   • Current approach follows existing KongCustomEntity pattern

4. Scope:

   • Is KongKey/KongKeySet support required for v1?
   • Should we support all 8 types in first release or phase it?

5. Testing:

   • What level of test coverage is expected?
   • Any specific scenarios to validate?

6. Timeline:

   • Is this feature targeted for a specific release?
   • What priority does it have?

Next Steps (If Approach Approved)

1. Maintainer review of proposed architecture
2. Implement proper unit tests
3. Implement envtest tests
4. Manual testing with real Kong Gateway
5. Run full test suite
6. Code review and iteration
7. Documentation
8. Integration tests
9. Prepare for release

Certificate Sourcing

Both KongCertificate and KongCACertificate support two source types:

• inline: Certificate data provided directly in CR spec
• secretRef: Certificate data read from Kubernetes Secret

Documentation

A comprehensive technical document has been added: KIC_STANDALONE_V1ALPHA1.md

This document details:

• Architecture and design decisions
• Complete list of files changed with explanations
• Translation logic and type conversion approach
• Feature gate configuration
• Usage examples

Breaking Changes

None. This is an opt-in feature controlled by a feature gate (disabled by default).

Related Issues

Addresses #3259

---

This PR demonstrates that the requested feature is technically feasible but requires significant effort across multiple layers of the codebase. Feedback from maintainers will help determine if this approach is worth pursuing.