How cnoe-io/idpbuilder works
Project Type and Purpose
• This is a Go-based CLI tool that doubles as a Kubernetes operator. Its primary function (“idpbuilder create”) is to spin up a complete internal developer platform (IDP) on a local Kubernetes cluster (via Docker/Kind). It defines three custom resources (CustomPackage, GitRepository, LocalBuild) and reconciles them to deploy Argo CD, Gitea, Ingress‐NGINX, CoreDNS, Backstage, etc.
Top-Level Components (from the file tree)
• CLI layer (pkg/cmd + main.go)
• Builder engine (pkg/build + hack/ manifests)
• Kubernetes cluster management (pkg/kind)
• Kubernetes API clients & CRD definitions (api/v1alpha1, pkg/k8s, pkg/util)
• Controller-manager (pkg/controllers/*)
• Utility libraries (pkg/util, pkg/logger, pkg/printer)
Runtime Workflow & Interactions
a. User invokes idpbuilder create (Cobra CLI)
→ CLI parses flags, calls builder code (pkg/build)
→ Optionally spins up a Kind cluster (pkg/kind)
→ Applies CRD manifests (api/v1alpha1 + hack/) via Kubernetes API client (pkg/k8s)
→ Creates custom resource instances (GitRepository, CustomPackage, LocalBuild)
b. Controller-manager (run via idpbuilder run or embedded in create) watches CRDs
→ pkg/controllers/gitrepository: clones or mirrors repositories (GitHub/Gitea adapter)
→ pkg/controllers/custompackage: materializes application sets, Helm charts, Kustomize apps
→ pkg/controllers/localbuild: bootstraps local services (Argo CD server, Gitea server, NGINX ingress)
c. Controllers reconcile desired state by generating Kubernetes manifests (templates under pkg/build/templates & hack/**), then apply them through the Kubernetes API
d. The platform components (Argo CD, Gitea, Ingress controller, CoreDNS) come up in the cluster
Key Architectural Patterns & Technologies
• Operator pattern: controllers built with Kubebuilder conventions, reconciling CRDs
• CLI pattern: Cobra commands under pkg/cmd, with “create”, “delete”, “get”, “version”
• Local cluster provisioning: Kind (pkg/kind)
• Kubernetes API interactions: client-go abstractions in pkg/k8s & pkg/util/k8s
• Templating: Go‐text templates for manifests (pkg/build/templates, hack/)
• Test harness: e2e tests (tests/e2e), unit tests alongside each package
• User Terminal (CLI)
• idpbuilder binary
• pkg/cmd (Cobra)
• Builder Engine
• pkg/build (manifest generation)
• hack/ (static YAML templates)
• Kind Cluster Manager
• pkg/kind: cluster create/delete
• Kubernetes Control Plane
• API server, etcd (external Docker-hosted Kind)
• CRD registrations (api/v1alpha1)
• Controller Manager (pkg/controllers)
• gitrepository controller
• custompackage controller
• localbuild controller
• Deployed Workloads in Cluster
• Argo CD components
• Gitea server
• Ingress-NGINX
• CoreDNS
• Backstage (if included in templates)
• External Services
• Docker daemon (prerequisite)
• GitHub/Gitea endpoints (for Git mirroring)