# fluxcd/flagger architecture

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

- Interactive diagram: https://gitdiagram.com/fluxcd/flagger
- Repository: https://github.com/fluxcd/flagger

## Overview

##### Project Type and Purpose
- Flagger is a Kubernetes-native tool for progressive delivery that automates canary, A/B testing, blue/green, and mirroring deployments. Its purpose is to gradually shift traffic from one version of an application to another while assessing performance through metrics and tests.
- The tool integrates with multiple service meshes (e.g., Istio, App Mesh, Linkerd, Kuma), ingress controllers (e.g., NGINX, Traefik, Skipper, Contour, Gloo), and now even with Gateway API and SMI.
- The README outlines how Flagger watches for custom Canary CRDs, triggers tests or webhooks, and interacts with monitoring solutions, meaning it is centrally an orchestration/control loop for release automation.

##### File Structure Analysis Indicates
- Presence of the “cmd/flagger” directory suggests a main executable.
- The “pkg” directory is organized into several sub-components:
- APIs: Definitions for various providers (appmesh, istio, linkerd, etc.) and the custom resource definitions (CRDs) around canary analysis.
- Controller: The main reconciliation loop that watches Kubernetes resources (like Canary CRD) and triggers promotions or rollbacks.
- Client: Custom client sets and informers to communicate with Kubernetes APIs and observe resource changes.
- Metrics and Notifiers: Integration with Prometheus and multiple external metric providers (such as Datadog, Cloudwatch) and notification channels (Slack, Teams, etc.).
- Router: Abstractions for various ingress and service mesh routing implementations.
- Loadtester: A component for running conformance and load tests.
- Additional directories like “charts” and “kustomize” indicate deployment resources enabling Helm and GitOps-based configuration management.

1. A high-level Kubernetes cluster boundary that contains custom resources (Canary CRD, Deployments, HPA, Service definitions).
- Custom Resource Definitions (CRDs for Canary deployments).
- Client/Informer loops that watch for changes.
3. Surround the controller with its functional modules:
- Metrics Analysis Module (link this to external Prometheus/other metric providers).
- Routing Module (show branching into different integrations like Istio, NGINX, etc.).
- Testing / Webhooks Module (show connectivity to load testers and other validation services).
- Notification Module (illustrate integration with Slack, Teams, Discord).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level Deployment Configurations
    D["Deployment Configurations (Helm/Kustomize)"]:::deployment

    %% Kubernetes Cluster Subgraph
    subgraph "Kubernetes Cluster"
        A["Canary CRD & Definitions"]:::k8s
        B["Flagger Controller"]:::controller
        C["Kubernetes Workloads"]:::k8s
    end

    %% Functional Modules Subgraph
    subgraph "Functional Modules"
        T["Traffic Routing"]:::module
        M["Metrics Providers"]:::module
        N["Notifiers & Webhook Handlers"]:::module
        L["Load Tester"]:::module
    end

    %% Traffic Routing Subgraph (Integrations)
    subgraph "Traffic Routing Integrations"
        I1["Istio Integration"]:::module
        I2["App Mesh Integration"]:::module
        I3["Other Integrations"]:::module
    end

    %% Flow Connections
    D -->|"deploys"| B
    A -->|"triggers"| B
    B -->|"controls"| C
    B -->|"adjusts"| T
    T --> I1
    T --> I2
    T --> I3
    B -->|"analyzes"| M
    M -->|"feeds"| B
    B -->|"alerts"| N
    B -->|"validates"| L
    L -->|"reports"| B

    %% Click Events for Deployment Configurations
    click D "https://github.com/fluxcd/flagger/tree/main/charts/flagger"
    click D "https://github.com/fluxcd/flagger/tree/main/kustomize/base/flagger"

    %% Click Events for Kubernetes Cluster Components
    click A "https://github.com/fluxcd/flagger/blob/main/artifacts/flagger/crd.yaml"
    click A "https://github.com/fluxcd/flagger/blob/main/pkg/apis/flagger/v1beta1/canary.go"
    click B "https://github.com/fluxcd/flagger/blob/main/cmd/flagger/main.go"
    click B "https://github.com/fluxcd/flagger/blob/main/pkg/controller/controller.go"
    click C "https://github.com/fluxcd/flagger/blob/main/charts/flagger/templates/deployment.yaml"
    click C "https://github.com/fluxcd/flagger/blob/main/artifacts/flagger/deployment.yaml"

    %% Click Events for Traffic Routing Integrations
    click I1 "https://github.com/fluxcd/flagger/blob/main/pkg/apis/istio/v1beta1/virtual_service.go"
    click I1 "https://github.com/fluxcd/flagger/blob/main/pkg/router/istio.go"
    click I2 "https://github.com/fluxcd/flagger/blob/main/pkg/apis/appmesh/v1beta1/types.go"
    click I2 "https://github.com/fluxcd/flagger/blob/main/pkg/router/appmesh.go"
    click I3 "https://github.com/fluxcd/flagger/blob/main/pkg/apis/smi/v1alpha1/traffic_split.go"
    click I3 "https://github.com/fluxcd/flagger/blob/main/pkg/router/traefik.go"

    %% Click Events for Metrics Providers
    click M "https://github.com/fluxcd/flagger/blob/main/pkg/metrics/providers/prometheus.go"

    %% Click Events for Notifiers & Webhook Handlers
    click N "https://github.com/fluxcd/flagger/blob/main/pkg/notifier/notifier.go"

    %% Click Events for Load Tester
    click L "https://github.com/fluxcd/flagger/blob/main/cmd/loadtester/main.go"
    click L "https://github.com/fluxcd/flagger/blob/main/pkg/loadtester/server.go"

    %% Styles for Classes
    classDef k8s fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef controller fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef module fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef deployment fill:#DA70D6,stroke:#000,stroke-width:2px;
```
