# kong/kubernetes-ingress-controller architecture

> Architecture diagram of the GitHub repository kong/kubernetes-ingress-controller, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kong/kubernetes-ingress-controller
- Repository: https://github.com/kong/kubernetes-ingress-controller

## Overview

##### Main Components

a. Control Plane Components:
- Kubernetes API Server (external component)
- Kong Ingress Controller (main controller)
- Webhook Server (for validation and mutation)
- Metrics Server (for Prometheus metrics)
- Diagnostics Server
- Configuration Synchronizer

b. Data Plane Components:
- Kong Gateway Instances (managed by the controller)
- Admin API Interface
- Proxy Interface
- Database (optional, supports DB-less mode)

c. Custom Resources:
- Gateway API Resources (GatewayClass, Gateway, HTTPRoute, etc.)
- Kong-specific CRDs (KongPlugin, KongConsumer, etc.)
- Ingress Resources

##### Relationships and Interactions

- Controller watching Kubernetes resources
- Configuration flow from controller to Kong instances
- Traffic flow from clients through Kong proxy
- Webhook validation flow
- Metrics collection paths

##### Specific Implementation Details

- The separation between control plane (controller) and data plane (Kong gateways)
- Multiple Kong gateway support (multi-gateway architecture)
- Support for both Gateway API and Ingress resources
- Plugin management system
- Health checking and load balancing capabilities

##### Key Architectural Patterns

Highlight:
- Kubernetes operator pattern
- Controller-runtime based implementation
- Webhook-based validation
- Event-driven architecture
- Configuration translation pipeline

**Top Layer: Client Traffic**

**Middle Layer: Kong Gateway Instances (Data Plane)**

**Bottom Layer: Controller Components (Control Plane)**
- Kubernetes API Server and Resources

##### Essential Labels

- Version information
- Protocol support (TCP, UDP, HTTP, gRPC)
- Feature gates
- Enterprise vs. OSS components
- API versioning (v1, v1beta1, v1alpha1)

##### Additional Elements

Include:
- Notes about optional components (database, enterprise features)
- Scaling indicators for components that can be replicated
- Security boundaries and communication protocols

##### Technical Details to Capture

Show:
- Admission webhook paths
- Configuration update flows
- Status reporting paths
- Health check mechanisms
- Plugin injection points

Remember to include a reference to the Gateway API conformance level and supported Kubernetes versions, as these are critical aspects of the system's compatibility matrix.

This system design should help developers understand both the high-level architecture and the detailed interactions between components, facilitating both development and operational understanding of the Kong Ingress Controller.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client["Client Layer"]
        CLIENT((End Users))
        TRAFFIC[("External Traffic")]
    end

    subgraph DataPlane["Data Plane"]
        KONG[Kong Gateway Instances]:::gateway
        PROXY["Proxy Interface"]:::gateway
        ADMIN["Admin API Interface"]:::gateway
        DB[(Optional Database)]:::db
    end

    subgraph ControlPlane["Control Plane"]
        KIC[Kong Ingress Controller]:::controller
        WEBHOOK["Webhook Server"]:::controller
        METRICS["Metrics Server"]:::controller
        DIAG["Diagnostics Server"]:::controller
        SYNC["Configuration Synchronizer"]:::controller
        TRANS["Data Plane Translator"]:::controller
        STORE["Store/Cache Layer"]:::controller
        STATE["Kong State Management"]:::controller
        TELEM["Telemetry System"]:::controller
    end

    subgraph K8s["Kubernetes Layer"]
        API["Kubernetes API Server"]:::k8s
        subgraph Resources["Kubernetes Resources"]
            GATEWAY["Gateway API Resources"]:::resource
            CRD["Kong CRDs"]:::resource
            ING["Ingress Resources"]:::resource
        end
    end

    %% Relationships
    CLIENT --> TRAFFIC
    TRAFFIC --> PROXY
    PROXY --> KONG
    KONG --> DB
    KONG --> ADMIN

    KIC --> API
    KIC --> ADMIN
    WEBHOOK --> API
    API --> WEBHOOK

    GATEWAY --> KIC
    CRD --> KIC
    ING --> KIC

    KIC --> SYNC
    SYNC --> TRANS
    TRANS --> STATE
    STATE --> STORE
    STORE --> SYNC

    METRICS --> TELEM
    DIAG --> TELEM

    %% Click Events
    click KIC "https://github.com/Kong/kubernetes-ingress-controller/blob/main/internal/cmd/main.go"
    click WEBHOOK "https://github.com/Kong/kubernetes-ingress-controller/tree/main/internal/admission/"
    click METRICS "https://github.com/Kong/kubernetes-ingress-controller/blob/main/internal/metrics/prometheus.go"
    click DIAG "https://github.com/Kong/kubernetes-ingress-controller/blob/main/internal/diagnostics/server.go"
    click SYNC "https://github.com/Kong/kubernetes-ingress-controller/blob/main/internal/dataplane/synchronizer.go"
    click ADMIN "https://github.com/Kong/kubernetes-ingress-controller/tree/main/internal/adminapi/"
    click CRD "https://github.com/Kong/kubernetes-ingress-controller/tree/main/pkg/apis/configuration/"
    click TRANS "https://github.com/Kong/kubernetes-ingress-controller/tree/main/internal/dataplane/translator/"
    click GATEWAY "https://github.com/Kong/kubernetes-ingress-controller/tree/main/internal/controllers/gateway/"
    click STATE "https://github.com/Kong/kubernetes-ingress-controller/tree/main/internal/dataplane/kongstate/"
    click STORE "https://github.com/Kong/kubernetes-ingress-controller/tree/main/internal/store/"
    click TELEM "https://github.com/Kong/kubernetes-ingress-controller/tree/main/internal/manager/telemetry/"

    %% Styles
    classDef controller fill:#2374e1,color:#fff
    classDef gateway fill:#48a868,color:#fff
    classDef k8s fill:#326ce5,color:#fff
    classDef resource fill:#ffd351,color:#000
    classDef db fill:#666,color:#fff

    %% Legend
    subgraph Legend
        L1[Controller Components]:::controller
        L2[Gateway Components]:::gateway
        L3[Kubernetes Components]:::k8s
        L4[K8s Resources]:::resource
        L5[(Database)]:::db
    end
```
