# lehuannhatrang/appbundle-operator architecture

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

- Interactive diagram: https://gitdiagram.com/lehuannhatrang/appbundle-operator
- Repository: https://github.com/lehuannhatrang/appbundle-operator

## Overview

##### Project Type and Purpose
- This is a Kubernetes Operator built with Kubebuilder in Go.
- Its purpose is to manage a new custom resource (AppBundle), orchestrate ordered deployments of grouped Kubernetes resources, integrate with Argo CD sync waves for GitOps, and optionally interact with Porch for package management.

##### File Structure Analysis
- Top-level
- cmd/main.go – Operator entrypoint launching the controller manager.
- api/v1alpha1 – CRD type definitions (Spec & Status) and generated deepcopy methods.
- internal/controller – Reconcile logic (AppBundleController) plus unit tests.
- internal/porch – Porch-client abstraction for package retrieval.
- config/ – kustomize manifests for CRDs, RBAC, manager deployment, network policies, Prometheus metrics.
- Dockerfile, .github/workflows – CI/CD and image build pipelines.
- test/e2e – End-to-end tests exercising the operator in a real cluster.
- Architectural Patterns
- Operator pattern with a control-loop (Reconcile function) watching AppBundle CRs.
- MVC style: API types (Model), Controller (Reconcile), and K8s resources (View/actuators).
- CRD + controller runtime for event-driven reconciliation.

##### Key Components
a. Kubernetes Cluster
- API Server (CRD storage & standard resources)
- etcd (state store)
b. AppBundle Operator
- Leader-election–enabled controller manager (cmd/main.go)
- AppBundleController (internal/controller/appbundle_controller.go)
- PorchClient (internal/porch/porch_client.go)
c. External Integrations
- Argo CD (watches resources and enforces sync waves)
- Porch (Package Orchestration service)
d. Supporting Infrastructure
- CRD definitions loaded into API Server (api/v1alpha1 & config/crd)
- RBAC, NetworkPolicy, MetricsService (config/rbac, config/network-policy, config/prometheus)
- GitHub Actions & Docker registry (CI/CD pipelines)

##### Relationships and Interactions
1. User applies AppBundle CR via kubectl or GitOps (Argo CD).
2. API Server stores the AppBundle CR.
3. Operator’s controller manager is notified (watch on AppBundle).
4. Reconcile loop:
- Read AppBundle Spec → Init Status.
- If Porch integration enabled → call PorchClient to fetch package contents.
- Sort Groups → For each Group (order):
– Sort Components → For each Component (order):
- Render K8s template, compute syncWave = group×100+component.
- Resource with syncWave & labels.
- Create/Update resource via API Server.
- Update Status (component and group statuses).
5. Kubernetes API Server stores created resources.
6. Argo CD sees annotations and enforces phased sync.
7. Metrics and status exposed via Prometheus & CR Status.

##### Architectural Patterns & Principles
- **Reconciliation Loop**: Desired vs actual state.
- **Declarative CRD-driven**: Users describe AppBundle, operator enforces it.
- **Single Responsibility**: Controller focuses on AppBundle; PorchClient isolates package logic.
- **Event-driven**: Watches on CRs and child resources.
- **Kustomize** for manifest generation and CRD packaging.

##### Technologies & Frameworks
- Go + controller-runtime + Kubebuilder
- Kubernetes API Server & CRD mechanism
- Argo CD sync-wave annotations
- Porch API (optional external service)
- Kustomize (config/ directory)
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Plane
    subgraph "Kubernetes Control Plane"
        direction TB
        APIServer["API Server"]:::controlplane
        ETCD["etcd (state store)"]:::controlplane
    end

    APIServer --> ETCD

    %% Operator Components
    subgraph "AppBundle Operator" 
        direction TB
        OpEntry["Leader Election & Controller Manager"]:::operator
        AppCtrl["AppBundleController"]:::operator
        PorchClient["PorchClient"]:::operator
    end

    %% External Integrations
    subgraph "External Systems"
        direction TB
        ArgoCD["Argo CD"]:::external
        PorchService["Porch Service"]:::external
        CI["CI/CD (GitHub Actions & Docker Registry)"]:::external
    end

    %% Supporting Config & Resources
    subgraph "Config & Manifests"
        direction TB
        CRDDefs["CRD Definitions & Deepcopy Generators"]:::config
        KustomizeCRD["Kustomize CRD Packaging"]:::config
        RBAC["RBAC Definitions"]:::config
        NetPol["NetworkPolicy for Metrics"]:::config
        MetricsService["Prometheus Metrics Service"]:::config
        ManagerDeploy["Manager Deployment Manifest"]:::config
        Samples["Sample AppBundle CRs"]:::config
        CIWorkflows["CI/CD Workflows"]:::config
        DockerfileNode["Dockerfile"]:::config
    end

    %% Flows
    User["User / GitOps"]:::external -->|applies AppBundle CR| APIServer
    CRDDefs -->|loaded into| APIServer
    KustomizeCRD -->|packages CRDs| CRDDefs
    RBAC -->|applied to| APIServer
    NetPol -->|applied to| APIServer
    MetricsService -->|exposes metrics| APIServer
    ManagerDeploy -->|deploys operator| APIServer
    Samples -->|used by| User

    CIWorkflows -->|build & push| CI
    DockerfileNode -->|defines image| CI
    CI -->|image stored in| DockerRegistry["Docker Registry"]:::external
    DockerRegistry -->|image pulled by| ManagerDeploy

    APIServer -->|watch event| OpEntry
    OpEntry -->|manages controllers| AppCtrl
    AppCtrl -->|calls if enabled| PorchClient
    PorchClient -->|fetch package| PorchService
    AppCtrl -->|create/update resources| APIServer
    AppCtrl -->|update CR Status & metrics| MetricsService
    APIServer -->|stores resources| ETCD
    APIServer -->|notifies| ArgoCD
    ArgoCD -->|enforces sync waves| APIServer

    %% SyncWave Annotation Note
    NoteSync["syncWave = group*100 + component"]:::note
    AppCtrl -->|annotate resources| NoteSync

    %% Click Events
    click OpEntry "https://github.com/lehuannhatrang/appbundle-operator/blob/main/cmd/main.go"
    click AppCtrl "https://github.com/lehuannhatrang/appbundle-operator/blob/main/internal/controller/appbundle_controller.go"
    click internal/controller/appbundle_controller_test.go "https://github.com/lehuannhatrang/appbundle-operator/blob/main/internal/controller/appbundle_controller_test.go"
    click PorchClient "https://github.com/lehuannhatrang/appbundle-operator/blob/main/internal/porch/porch_client.go"
    click CRDDefs "https://github.com/lehuannhatrang/appbundle-operator/blob/main/api/v1alpha1/appbundle_types.go"
    click api/v1alpha1/zz_generated.deepcopy.go "https://github.com/lehuannhatrang/appbundle-operator/blob/main/api/v1alpha1/zz_generated.deepcopy.go"
    click api/v1alpha1/groupversion_info.go "https://github.com/lehuannhatrang/appbundle-operator/blob/main/api/v1alpha1/groupversion_info.go"
    click CRDDefs "https://github.com/lehuannhatrang/appbundle-operator/blob/main/config/crd/bases/app.example.com_appbundles.yaml"
    click KustomizeCRD "https://github.com/lehuannhatrang/appbundle-operator/blob/main/config/crd/kustomization.yaml"
    click KustomizeCRD "https://github.com/lehuannhatrang/appbundle-operator/blob/main/config/crd/kustomizeconfig.yaml"
    click RBAC "https://github.com/lehuannhatrang/appbundle-operator/blob/main/config/rbac/leader_election_role.yaml"
    click NetPol "https://github.com/lehuannhatrang/appbundle-operator/blob/main/config/network-policy/allow-metrics-traffic.yaml"
    click MetricsService "https://github.com/lehuannhatrang/appbundle-operator/blob/main/config/prometheus/monitor.yaml"
    click ManagerDeploy "https://github.com/lehuannhatrang/appbundle-operator/blob/main/config/manager/manager.yaml"
    click MetricsService "https://github.com/lehuannhatrang/appbundle-operator/blob/main/config/default/metrics_service.yaml"
    click MetricsService "https://github.com/lehuannhatrang/appbundle-operator/blob/main/config/default/manager_metrics_patch.yaml"
    click Samples "https://github.com/lehuannhatrang/appbundle-operator/blob/main/config/samples/app_v1alpha1_appbundle_with_porch.yaml"
    click DockerfileNode "https://github.com/lehuannhatrang/appbundle-operator/tree/main/Dockerfile"
    click CIWorkflows "https://github.com/lehuannhatrang/appbundle-operator/blob/main/.github/workflows/docker-build-push.yml"
    click CIWorkflows "https://github.com/lehuannhatrang/appbundle-operator/blob/main/.github/workflows/test.yml"
    click CIWorkflows "https://github.com/lehuannhatrang/appbundle-operator/blob/main/.github/workflows/test-e2e.yml"
    click CIWorkflows "https://github.com/lehuannhatrang/appbundle-operator/blob/main/.github/workflows/lint.yml"
    click DockerRegistry "https://github.com/lehuannhatrang/appbundle-operator/tree/main/Dockerfile"
    click CI "https://github.com/lehuannhatrang/appbundle-operator/blob/main/.github/workflows/docker-build-push.yml"

    %% Styles
    classDef controlplane fill:#a2f5a2,stroke:#333,stroke-width:1px
    classDef operator fill:#a2c8f5,stroke:#333,stroke-width:1px
    classDef external fill:#f5d76a,stroke:#333,stroke-width:1px
    classDef config fill:#f5a2a2,stroke:#333,stroke-width:1px
    classDef note fill:#ffffff,stroke:#000,stroke-dasharray: 2 2,stroke-width:1px,font-style:italic
```
