# nginxinc/kubernetes-ingress architecture

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

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

## Overview

NGINX Ingress Controller watches Kubernetes routing resources and turns them into NGINX load-balancer configuration. Users configure standard Ingress, VirtualServer/VirtualServerRoute, and TransportServer resources; the controller reconciles changes, generates configuration, and applies it through the NGINX manager. Additional branches cover certificate management, external DNS, App Protect security, and telemetry. The README documents product capabilities; source excerpts are partial, so some orchestration links are shown as unverified rather than asserted as direct calls.

Main entry points: [`internal/k8s/controller.go`](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/k8s/controller.go) (Kubernetes Reconciler), [`internal/nginx/manager.go`](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/nginx/manager.go) (NGINX Manager), [`pkg/apis/configuration/v1/types.go`](https://github.com/nginxinc/kubernetes-ingress/blob/main/pkg/apis/configuration/v1/types.go) (Routing Resources), [`internal/configs/virtualserver.go`](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/configs/virtualserver.go) (Route Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Controller"]
  node_k8scontroller["Kubernetes Reconciler<br/>[controller.go]"]
end

subgraph group_routing["Routing Configuration"]
  node_resources["Routing Resources<br/>[types.go]"]
  node_validation["Policy Validation<br/>[policy.go]"]
  node_configurator["Route Configuration<br/>[virtualserver.go]"]
  node_configmaps["Global Settings<br/>[configmaps.go]"]
end

subgraph group_runtime["NGINX Runtime"]
  node_nginxmanager["NGINX Manager<br/>[manager.go]"]
  node_rollback["Config Rollback"]
  node_nginx(("NGINX Process"))
end

subgraph group_integrations["Extensions"]
  node_certmanager["Certificate Controller<br/>[cm_controller.go]"]
  node_externaldns["External DNS<br/>[controller.go]"]
  node_wafbundle["WAF Bundles<br/>[fetch.go]"]
  node_appsecurity["App Protect<br/>[appprotect_waf.go]"]
  node_dossecurity["DoS Protection<br/>[appprotect_dos.go]"]
  node_dnsservice(("DNS Provider"))
end

subgraph group_observability["Observability"]
  node_health["Health Checks<br/>[healthcheck.go]"]
  node_metrics["Metrics<br/>[manager.go]"]
  node_telemetry["Telemetry<br/>[collector.go]"]
end

node_operator(("Cluster Operator"))

node_operator -->|"configures"| node_resources
node_resources -->|"reconciled by"| node_k8scontroller
node_k8scontroller -.->|"validates"| node_validation
node_k8scontroller -.->|"reconciles routes"| node_configurator
node_k8scontroller -.->|"reads settings"| node_configmaps
node_configurator -.->|"produces config"| node_nginxmanager
node_nginxmanager -.->|"uses rollback"| node_rollback
node_nginxmanager -.->|"manages process"| node_nginx
node_k8scontroller -->|"coordinates"| node_certmanager
node_k8scontroller -->|"coordinates"| node_externaldns
node_externaldns -.->|"publishes records"| node_dnsservice
node_k8scontroller -->|"coordinates"| node_wafbundle
node_k8scontroller -->|"coordinates"| node_appsecurity
node_k8scontroller -->|"coordinates"| node_dossecurity
node_k8scontroller -.->|"starts checks"| node_health
node_k8scontroller -.->|"feeds metrics"| node_metrics
node_k8scontroller -->|"feeds telemetry"| node_telemetry

click node_resources "https://github.com/nginxinc/kubernetes-ingress/blob/main/pkg/apis/configuration/v1/types.go"
click node_k8scontroller "https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/k8s/controller.go"
click node_validation "https://github.com/nginxinc/kubernetes-ingress/blob/main/pkg/apis/configuration/validation/policy.go"
click node_configurator "https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/configs/virtualserver.go"
click node_configmaps "https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/configs/configmaps.go"
click node_nginxmanager "https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/nginx/manager.go"
click node_rollback "https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/nginx/rollback_manager.go"
click node_certmanager "https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/certmanager/cm_controller.go"
click node_externaldns "https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/externaldns/controller.go"
click node_wafbundle "https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/configs/wafbundle/fetch.go"
click node_appsecurity "https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/k8s/appprotect_waf.go"
click node_dossecurity "https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/k8s/appprotect_dos.go"
click node_health "https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/healthcheck/healthcheck.go"
click node_metrics "https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/metrics/collectors/manager.go"
click node_telemetry "https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/telemetry/collector.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_k8scontroller toneBlue
class node_resources,node_validation,node_configurator,node_configmaps toneAmber
class node_nginxmanager,node_rollback,node_nginx toneMint
class node_certmanager,node_externaldns,node_wafbundle,node_appsecurity,node_dossecurity,node_dnsservice toneRose
class node_health,node_metrics,node_telemetry,node_operator toneIndigo
```

## Components

### Controller

- [Kubernetes Reconciler](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/k8s/controller.go): `internal/k8s/controller.go`

### Routing Configuration

- [Routing Resources](https://github.com/nginxinc/kubernetes-ingress/blob/main/pkg/apis/configuration/v1/types.go): `pkg/apis/configuration/v1/types.go`
- [Policy Validation](https://github.com/nginxinc/kubernetes-ingress/blob/main/pkg/apis/configuration/validation/policy.go): `pkg/apis/configuration/validation/policy.go`
- [Route Configuration](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/configs/virtualserver.go): `internal/configs/virtualserver.go`
- [Global Settings](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/configs/configmaps.go): `internal/configs/configmaps.go`

### NGINX Runtime

- [NGINX Manager](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/nginx/manager.go): `internal/nginx/manager.go`
- [Config Rollback](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/nginx/rollback_manager.go): `internal/nginx/rollback_manager.go`
- **NGINX Process**

### Extensions

- [Certificate Controller](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/certmanager/cm_controller.go): `internal/certmanager/cm_controller.go`
- [External DNS](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/externaldns/controller.go): `internal/externaldns/controller.go`
- [WAF Bundles](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/configs/wafbundle/fetch.go): `internal/configs/wafbundle/fetch.go`
- [App Protect](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/k8s/appprotect_waf.go): `internal/k8s/appprotect_waf.go`
- [DoS Protection](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/k8s/appprotect_dos.go): `internal/k8s/appprotect_dos.go`
- **DNS Provider**

### Observability

- [Health Checks](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/healthcheck/healthcheck.go): `internal/healthcheck/healthcheck.go`
- [Metrics](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/metrics/collectors/manager.go): `internal/metrics/collectors/manager.go`
- [Telemetry](https://github.com/nginxinc/kubernetes-ingress/blob/main/internal/telemetry/collector.go): `internal/telemetry/collector.go`

### Other components

- **Cluster Operator**

## Connections

- Cluster Operator → Routing Resources: configures (evidence: `README.md`)
- Routing Resources → Kubernetes Reconciler: reconciled by (evidence: `README.md`)
- Kubernetes Reconciler → Policy Validation: validates
- Kubernetes Reconciler → Route Configuration: reconciles routes
- Kubernetes Reconciler → Global Settings: reads settings
- Route Configuration → NGINX Manager: produces config
- NGINX Manager → Config Rollback: uses rollback
- NGINX Manager → NGINX Process: manages process
- Kubernetes Reconciler → Certificate Controller: coordinates (evidence: `internal/k8s/controller.go`)
- Kubernetes Reconciler → External DNS: coordinates (evidence: `internal/k8s/controller.go`)
- External DNS → DNS Provider: publishes records
- Kubernetes Reconciler → WAF Bundles: coordinates (evidence: `internal/k8s/controller.go`)
- Kubernetes Reconciler → App Protect: coordinates (evidence: `internal/k8s/controller.go`)
- Kubernetes Reconciler → DoS Protection: coordinates (evidence: `internal/k8s/controller.go`)
- Kubernetes Reconciler → Health Checks: starts checks
- Kubernetes Reconciler → Metrics: feeds metrics
- Kubernetes Reconciler → Telemetry: feeds telemetry (evidence: `internal/k8s/controller.go`)
