How lehuannhatrang/appbundle-operator works
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