# apache/apisix-ingress-controller architecture

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

- Interactive diagram: https://gitdiagram.com/apache/apisix-ingress-controller
- Repository: https://github.com/apache/apisix-ingress-controller

## Overview

This project is Apache APISIX Ingress Controller – a Kubernetes control plane component that converts Kubernetes Ingress and custom resources (CRDs) into Apache APISIX configurations. The goal is to manage the Apache APISIX data plane using Kubernetes declarative configurations.

##### Main Components
- Ingress Controller Main Binary – represented by the “cmd” directory (e.g., cmd/ingress). This is the entry point where the controller’s main logic is initialized.
- API and Validation Layer – under pkg/api, which handles HTTP endpoints (e.g., health checks, webhook endpoints) and request validation.
- Configuration and ID Generation – found in pkg/config and pkg/id; these modules handle configuration management and unique identifier generation.
- APISIX Translation/Provider Modules – in pkg/apisix, pkg/providers (including submodules for “apisix”, “ingress”, “gateway”, etc.). These packages convert Kubernetes CRDs (e.g., ApisixRoute, ApisixConsumer, etc.) into resources understood by Apache APISIX.
- Kubernetes Integration – in pkg/kube and pkg/providers/k8s, managing the connection to and interaction with Kubernetes resources. This includes client sets, informers, listers, and event handling to watch for CRD changes.
- Caching Layer – in pkg/apisix/cache, which handles in-memory caching (with modules like memdb) to optimize read/write operations.
- Logging and Metrics – in pkg/log and pkg/metrics, for recording controller events and exposing Prometheus metrics.
- Utility Modules – for common functionality, error handling, and code generation.

##### External and Internal Interactions
- Apache APISIX Data Plane: Even though it’s an external system, this is where the controller pushes the translated configurations. Represent this external service as the backend that receives configuration updates.
- Internal Processing Pipeline: Illustrate how changes go from the Kubernetes integration layer into the provider/translation layers (e.g., APISIX resource conversion) before reaching the API logic that communicates with Apache APISIX.

##### Architectural Patterns and Principles
- Event-driven Architecture: Emphasize that the controller uses watchers/informers to react to changes in the K8s API, and then processes these events.
- Modular Provider Architecture: The provider submodules (for APISIX and gateway) show how the project can extend or adapt to multiple deployment scenarios and custom resources.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Systems
    subgraph "External Systems"
        K8s_API["Kubernetes API & CRDs"]:::external
        APISIX_DP["Apache APISIX Data Plane"]:::external
    end

    %% Kubernetes Watchers & Informers
    subgraph "Kubernetes Watchers & Informers"
        KUBE_INT["Kube Integration (pkg/kube)"]:::watchers
        K8S_PROV["K8s Provider (pkg/providers/k8s)"]:::watchers
    end

    %% APISIX Translation & Provider
    subgraph "APISIX Translation & Provider"
        APIX_TRANS["APISIX Translation (pkg/apisix)"]:::translation
        PROV_APIX["Provider APISIX (pkg/providers/apisix)"]:::translation
        PROV_GW["Provider Gateway (pkg/providers/gateway)"]:::translation
        PROV_ING["Provider Ingress (pkg/providers/ingress)"]:::translation
        PROV_TRANS["Provider Translation (pkg/providers/translation)"]:::translation
    end

    %% Controller Core & API
    subgraph "Controller Core & API"
        MAIN_BINARY["Ingress Controller Main (cmd/ingress)"]:::core
        API_VALID["API & Validation (pkg/api)"]:::core
        CONFIG["Configuration (pkg/config)"]:::core
        ID_GEN["ID Generation (pkg/id)"]:::core
    end

    %% Supporting Services
    subgraph "Supporting Services"
        CACHE["Caching (pkg/apisix/cache)"]:::services
        LOG["Logging (pkg/log)"]:::services
        METRICS["Metrics (pkg/metrics)"]:::services
        UTILS["Utility Modules (pkg/utils)"]:::services
    end

    %% External to Kubernetes Integration
    K8s_API -->|"watchEvents"| KUBE_INT
    K8s_API -->|"watchEvents"| K8S_PROV

    %% Kubernetes Integration to APISIX Translation
    KUBE_INT -->|"resourceConversion"| APIX_TRANS
    K8S_PROV -->|"resourceConversion"| APIX_TRANS

    %% Internal Translation Flow
    APIX_TRANS -->|"prepareConfig"| PROV_APIX
    PROV_APIX -->|"enhance"| PROV_GW
    PROV_GW -->|"process"| PROV_ING
    PROV_ING -->|"finalize"| PROV_TRANS

    %% Translation to Core flow
    PROV_TRANS -->|"configurationUpdate"| API_VALID

    %% Core pushes configuration to Apache APISIX Data Plane
    API_VALID -->|"pushConfig"| APISIX_DP

    %% Core Initialization
    MAIN_BINARY -->|"initialize"| API_VALID
    CONFIG -->|"provideSettings"| API_VALID
    ID_GEN -->|"generateIDs"| API_VALID

    %% Supporting Services integration with Core
    API_VALID ---|"cacheUsage"| CACHE
    API_VALID ---|"logEvents"| LOG
    API_VALID ---|"exportMetrics"| METRICS
    API_VALID ---|"utilSupport"| UTILS

    %% Click Events
    click MAIN_BINARY "https://github.com/apache/apisix-ingress-controller/tree/master/cmd/ingress"
    click API_VALID "https://github.com/apache/apisix-ingress-controller/tree/master/pkg/api"
    click CONFIG "https://github.com/apache/apisix-ingress-controller/tree/master/pkg/config"
    click ID_GEN "https://github.com/apache/apisix-ingress-controller/tree/master/pkg/id"
    click APIX_TRANS "https://github.com/apache/apisix-ingress-controller/tree/master/pkg/apisix"
    click PROV_APIX "https://github.com/apache/apisix-ingress-controller/tree/master/pkg/providers/apisix"
    click PROV_GW "https://github.com/apache/apisix-ingress-controller/tree/master/pkg/providers/gateway"
    click PROV_ING "https://github.com/apache/apisix-ingress-controller/tree/master/pkg/providers/ingress"
    click PROV_TRANS "https://github.com/apache/apisix-ingress-controller/tree/master/pkg/providers/translation"
    click KUBE_INT "https://github.com/apache/apisix-ingress-controller/tree/master/pkg/kube"
    click K8S_PROV "https://github.com/apache/apisix-ingress-controller/tree/master/pkg/providers/k8s"
    click CACHE "https://github.com/apache/apisix-ingress-controller/tree/master/pkg/apisix/cache"
    click LOG "https://github.com/apache/apisix-ingress-controller/tree/master/pkg/log"
    click METRICS "https://github.com/apache/apisix-ingress-controller/tree/master/pkg/metrics"
    click UTILS "https://github.com/apache/apisix-ingress-controller/tree/master/pkg/utils"

    %% Styles
    classDef external fill:#FFE0B2,stroke:#BF360C,stroke-width:2px;
    classDef core fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef watchers fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef translation fill:#FFCDD2,stroke:#B71C1C,stroke-width:2px;
    classDef services fill:#E1BEE7,stroke:#4A148C,stroke-width:2px;
```
