# pulumi/pulumi-kubernetes-operator architecture

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

- Interactive diagram: https://gitdiagram.com/pulumi/pulumi-kubernetes-operator
- Repository: https://github.com/pulumi/pulumi-kubernetes-operator

## Overview

##### Project Type & Purpose
- This repository implements an open‐source Kubernetes Operator––the Pulumi Kubernetes Operator––plus a companion Agent service.
- Purpose: Expose Pulumi Stacks as first‐class Kubernetes Custom Resources, enabling a GitOps‐style CI/CD workflow inside any Kubernetes cluster.

##### File/Package Structure
- Top‐level:
- deploy/helm & deploy/crds → Helm chart and CRD definitions for operator deployment
- operator/ → the core operator code (controllers, webhooks, CRD API types, Kustomize configs, e2e tests)
- agent/ → standalone gRPC service (and CLI) that actually executes Pulumi programs
- examples/, stack-examples/ → sample Stack CRs and Pulumi programs
- docs/ → architecture/design, metrics, workflows, troubleshooting
- Patterns:
- Kubernetes Operator pattern: separate controller loops per CRD (Stack, Workspace, Update, Program)
- Microservice split: operator (in‐cluster controller & webhook) vs. agent (gRPC executor)
- Helm/Kustomize for deployment manifests

##### Key Architectural Components
a. Kubernetes API Server & CustomResourceDefinitions
- CRDs: Stacks, Workspaces, Programs, Updates (deploy/crds & operator/config)
- Operator’s Admission Webhooks for defaulting/validation on Workspace CRs

b. Pulumi Operator Deployment
- manager Deployment (operator/cmd, operator/internal/controller, operator/internal/webhook)
- Controller modules:
- auto controller (Workspace & Update CRs)
- pulumi controller (Stack & Program CRs)
- RBAC, Leader Election, Metrics Service for Prometheus (operator/config/)

c. Agent Service
- agent/cmd & agent/pkg/server → gRPC server that runs Pulumi CLI under the hood
- agent/pkg/client → gRPC client used by controllers to invoke the agent
- Designed to isolate Pulumi executions from the in‐cluster operator process

d. External Integrations
- Pulumi Cloud (state backend, access tokens in Kubernetes Secrets)
- Git repos, Flux sources, custom sources (examples/…)
- Prometheus metrics endpoint scraped from operator manager

##### Component Interactions & Data Flows
1. User commits Infrastructure as Code or creates a Stack CR (via kubectl/Helm/Pulumi)
2. CR posted to Kubernetes API Server
3. Operator controller (watching CRs) receives the event → reconciliation loop
4. Controller builds a gRPC request → calls Agent Service (in‐cluster or remote)
5. Agent authenticates to Pulumi Cloud / backends → runs `pulumi up` / `pulumi destroy`
6. Pulumi providers (AWS/Azure/GCP/K8s) are invoked → resources created/updated
7. Agent streams logs & results back to Operator via gRPC
8. Operator updates CR status & emits Prometheus metrics
9. GitOps feedback loop: Git commits ↔ Kubernetes CRs

##### Architectural Patterns & Design Principles
- Kubernetes Operator pattern: use controllers, finalizers, status subresources
- Webhook pattern for CR defaulting & validation
- Separation of concerns: operator orchestrates, agent executes (isolation & scalability)
- Declarative infra as data: CRDs represent desired state, controllers converge on it

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        direction TB
        APIS["API Server + etcd"]:::k8s
        CRDs["CustomResourceDefinitions (Stack, Workspace, Program, Update)"]:::k8s
        Secrets["Kubernetes Secrets"]:::k8s

        subgraph "Operator Manager"
            direction TB
            OMain["Operator Entrypoint"]:::k8s
            Webhook["Admission Webhook"]:::k8s
            WC1["Workspace Controller"]:::k8s
            UC1["Update Controller"]:::k8s
            SC1["Stack Controller"]:::k8s
            PC1["Program Controller"]:::k8s
        end

        subgraph "Agent Deployment"
            direction TB
            AServe["Agent gRPC Server"]:::k8s
            Server["Server Logic"]:::k8s
        end
    end

    %% External Systems
    Git["Git / Flux Repos"]:::external
    PulumiCloud["Pulumi Cloud"]:::pulumi
    CloudProv["Cloud Providers"]:::pulumi
    Prom["Prometheus"]:::external

    %% Flows
    Git -->|"GitOps sync"| CRDs
    CRDs -->|"Kubernetes API"| APIS
    APIS -->|"reconcile"| WC1
    WC1 -->|"invoke (gRPC)"| AServe
    AServe -->|"pulumi up/destroy"| PulumiCloud
    AServe -->|"pulumi up/destroy"| CloudProv
    AServe -->|"stream results"| WC1
    WC1 -->|"update status"| APIS
    WC1 -->|"emit metrics"| Prom

    OMain --> Webhook
    OMain --> WC1
    OMain --> UC1
    OMain --> SC1
    OMain --> PC1
    AServe --> Server

    %% Click Events
    click OMain "https://github.com/pulumi/pulumi-kubernetes-operator/blob/master/operator/cmd/main.go"
    click Webhook "https://github.com/pulumi/pulumi-kubernetes-operator/blob/master/operator/internal/webhook/auto/v1alpha1/workspace_webhook.go"
    click WC1 "https://github.com/pulumi/pulumi-kubernetes-operator/blob/master/operator/internal/controller/auto/workspace_controller.go"
    click UC1 "https://github.com/pulumi/pulumi-kubernetes-operator/blob/master/operator/internal/controller/auto/update_controller.go"
    click SC1 "https://github.com/pulumi/pulumi-kubernetes-operator/blob/master/operator/internal/controller/pulumi/stack_controller.go"
    click PC1 "https://github.com/pulumi/pulumi-kubernetes-operator/blob/master/operator/internal/controller/pulumi/program_controller.go"
    click AServe "https://github.com/pulumi/pulumi-kubernetes-operator/blob/master/agent/cmd/serve.go"
    click Server "https://github.com/pulumi/pulumi-kubernetes-operator/blob/master/agent/pkg/server/server.go"

    %% Styles
    classDef k8s fill:#F0A30A,stroke:#333,stroke-width:1px
    classDef pulumi fill:#1F77B4,stroke:#333,stroke-width:1px
    classDef external fill:#2CA02C,stroke:#333,stroke-width:1px
```
