# knative/serving architecture

> Architecture diagram of the GitHub repository knative/serving, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/knative/serving
- Repository: https://github.com/knative/serving

## Overview

##### Project type and purpose
- Knative Serving is a cloud-native serverless platform built on Kubernetes.
- It provides custom resource definitions (CRDs) for Service, Configuration, Revision, Route, DomainMapping, etc., and control-plane components that reconcile those resources.
- It also includes data-plane sidecars (queue-proxy) and control-plane microservices for autoscaling, activations, webhooks, domain defaulting, and schema tweaks.

##### File structure for architectural clues
- `cmd/…` directories each compile into a distinct microservice binary (activator, autoscaler, controller, webhook, default-domain, queue-proxy).
- `pkg/reconciler/…` contains reconcilers for each CRD type (Configuration, Revision, Route, Service, DomainMapping, etc.).
- `pkg/autoscaler/…` implements custom autoscaling logic.
- `pkg/queue/…` implements the queue-proxy sidecar for user workload pods.
- `config/…` holds Kubernetes YAMLs for CRD definitions, RoleBindings, Deployments, Webhooks.
- Test directories illustrate integration points with Kubernetes API and ingress.

##### Extract additional insights from the README
- Core features: automatic “scale-to-zero,” container routing, snapshots, custom domain mappings, extensibility via webhooks.
- The spec and documentation folders describe CRD schemas and the control-plane interactions.

##### Main components
a. Control Plane microservices (deployed as Kubernetes Deployments):
- API Server (Kubernetes) with Serving CRDs.
- Knative Webhook (Validating & Defaulting).
- Knative Controller (reconciles Service, Configuration, Route, ServerlessService, Certificate, etc.).
- Autoscaler / Autoscaler-HPA (monitors metrics, issues scale up/down requests).
- Activator (intercepts HTTP requests when pods are scaled to zero).
- Default-Domain service (injects cluster domain into Routes).
- Schema-Tweak (patches generated YAMLs as needed).
b. Data Plane components:
- User workload Pods, each with a sidecar queue-proxy (pkg/queue) to manage traffic flow, readiness, and observability.
c. External services:
- Ingress/Gateway layer (Istio / Kourier / Contour) for north-south routing.
- Certificate manager (e.g., cert-manager) for TLS provisioning.
- DNS / External domain providers.
d. Storage & state:
- etcd (backing the Kubernetes API Server).
- Kubernetes HPA resources (if using autoscaler-HPA).

##### Relationships and data flows
- Developers `kubectl apply` a `Service` CR → goes to Kubernetes API Server.
- Webhook mutates defaults (e.g., revision timeout, service account) and validates.
- Controller watches CR events → creates/updates Configuration, Revision, Route, ServerlessService, Certificates.
- Controller deploys Revision Pods (with queue-proxy).
- Autoscaler watches Revision metrics (via Prometheus HTTP scrape or custom stats) → decides desired replica count → updates Deployment or HPA.
- Activator stands in front of pods scaled to zero: traffic arrives from ingress → Activator buffers and triggers cold start.
- Ingress/Gateway routes HTTP traffic to either Activator (if no pods) or directly to queue-proxy sidecar.
- Queue-proxy forwards traffic to user container and emits metrics.
- Default-Domain microservice updates domain mappings for Routes.
- Schema-Tweak modifies YAML for config-management pipelines (optional).

##### Key architectural patterns & design principles
- Controller pattern (event-driven reconciliation loops via informers).
- Sidecar pattern (queue-proxy in each Revision Pod).
- Webhooks for validation & defaulting.
- CRD-based extensibility (each component focuses on its resource).
- Event-driven scaling (Autoscaler responds to metrics, Activator intercepts on cold start).
- Separation of control plane (knative components) vs data plane (queue-proxy & user container).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Control Plane
    subgraph "Control Plane"
        direction TB
        API["Kubernetes API Server"]:::controlplane
        Webhook["Knative Webhook"]:::controlplane
        Controller["Knative Controller"]:::controlplane
        Autoscaler["Autoscaler"]:::controlplane
        AutoscalerHPA["Autoscaler-HPA"]:::controlplane
        Activator["Activator"]:::controlplane
        DefaultDomain["Default-Domain"]:::controlplane
        SchemaTweak["Schema-Tweak"]:::controlplane
    end

    %% Data Plane
    subgraph "Data Plane"
        direction TB
        subgraph "Revision Pod"
            direction TB
            QueueProxy["Queue-Proxy Sidecar"]:::dataplane
            UserContainer["User Container"]:::dataplane
        end
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        Ingress["Ingress/Gateway"]:::external
        CertManager["Certificate Manager"]:::external
        DNS["DNS/External Domain Provider"]:::external
        Etcd["etcd"]:::external
        HPAResources["Kubernetes HPA Resources"]:::external
    end

    %% Developer Interaction
    Developer["Developer (kubectl apply)"]:::external

    %% Flows
    Developer -->|"apply Service CRD"| API
    API -->|"mutate & validate"| Webhook
    Webhook -->|"admission"| API
    API -->|"event"| Controller
    Controller -->|"create Deployments & CRs"| API
    Controller -->|"deploy Revision Pods"| QueueProxy
    QueueProxy -->|"forwards traffic"| UserContainer
    UserContainer -->|"exposes metrics"| Autoscaler
    Autoscaler -->|"scale decision"| API
    AutoscalerHPA -->|"HPA sync"| API
    Activator -->|"buffers requests"| API
    Ingress -->|"route HTTP"| Activator
    Ingress -->|"route HTTP"| QueueProxy
    DefaultDomain -->|"update Route domain"| API
    SchemaTweak -->|"patch YAML"| API
    CertManager -->|"provision TLS"| API
    DNS -->|"DNS updates"| API
    API -->|"store state"| Etcd
    HPAResources -->|"define|scale"| AutoscalerHPA

    %% Click Events
    click Webhook "https://github.com/knative/serving/blob/main/cmd/webhook/main.go"
    click Controller "https://github.com/knative/serving/blob/main/cmd/controller/main.go"
    click Autoscaler "https://github.com/knative/serving/blob/main/cmd/autoscaler/main.go"
    click AutoscalerHPA "https://github.com/knative/serving/blob/main/cmd/autoscaler-hpa/main.go"
    click Activator "https://github.com/knative/serving/blob/main/cmd/activator/main.go"
    click DefaultDomain "https://github.com/knative/serving/blob/main/cmd/default-domain/main.go"
    click SchemaTweak "https://github.com/knative/serving/blob/main/cmd/schema-tweak/main.go"
    click QueueProxy "https://github.com/knative/serving/blob/main/cmd/queue/main.go"

    %% Styles
    classDef controlplane fill:#D0E8FF,stroke:#0366d6,color:#0366d6,stroke-width:1px
    classDef dataplane fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10,stroke-width:1px
    classDef external fill:#FFE2A8,stroke:#D2691E,color:#D2691E,stroke-width:1px
```
