Branch: 001-orbstack-argocd-bootstrap | Date: 2026-02-10 | Spec: spec.md
Input: Feature specification from /specs/001-orbstack-argocd-bootstrap/spec.md
Bootstrap a local Kubernetes development platform on macOS ARM using OrbStack as the cluster runtime and ArgoCD 3.1.x as the GitOps controller. The bootstrap script verifies the cluster, installs ArgoCD via Helm, and uses an App-of-Apps pattern to deploy all infrastructure components (ingress-nginx, cert-manager, sealed-secrets, kube-prometheus-stack). A namespace template with ResourceQuotas, LimitRanges, and NetworkPolicies prepares the cluster for multi-project application onboarding.
Cloud Provider: Local (macOS ARM / Apple Silicon — no cloud provider)
IaC Tools: Helm 3.16.x, Kustomize 5.5.x, shell scripts (bootstrap only)
Kubernetes: OrbStack Kubernetes 1.31.x (single-node, local development)
GitOps: ArgoCD 3.1.x (Helm chart argo-cd 9.0.1)
Deployment Strategy: Helm-first with Kustomize fallback (per constitution)
State Backend: N/A — no Terraform; Git is the single source of truth for all K8s state
Secrets Management: Sealed Secrets (kubeseal) for Git-safe secrets
Validation: helm template + kubeconform, kustomize build + kubeconform, shellcheck for scripts
Target Environment: Local development (single developer workstation)
Deployment Type: Single-node local cluster
Performance Goals: Bootstrap < 10 min, ArgoCD sync < 3 min, cluster rebuild < 15 min
Constraints: No budget (local), no formal compliance, limited by local machine resources (4-8 CPU, 8-16 GiB RAM)
Scale/Scope: ~6 system namespaces, ~20 max project namespaces, ~100 max pods
| Component | Required | Chart Version | App Version | Repository |
|---|---|---|---|---|
| ArgoCD | Yes (bootstrap via Helm) | 9.0.1 | v3.1.9 | https://argoproj.github.io/argo-helm |
| ingress-nginx | Yes (ArgoCD Application) | 4.14.3 | 1.14.3 | https://kubernetes.github.io/ingress-nginx |
| cert-manager | Yes (ArgoCD Application) | 1.19.3 | v1.19.3 | https://charts.jetstack.io |
| sealed-secrets | Yes (ArgoCD Application) | 2.18.0 | 0.34.0 | https://bitnami-labs.github.io/sealed-secrets |
| kube-prometheus-stack | Yes (ArgoCD Application) | 81.5.2 | v0.88.1 | https://prometheus-community.github.io/helm-charts |
Custom Applications: Namespace template (Kustomize), sample validation app (Kustomize)
GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.
| # | Gate | Status | Evidence |
|---|---|---|---|
| 1 | GitOps First: All state in Git, no manual applies outside bootstrap | PASS | ArgoCD App-of-Apps manages all post-bootstrap resources. Bootstrap script is the only manual apply (allowed by constitution). |
| 2 | Zero-YAML Development: Agent generates all manifests | PASS | All ArgoCD Applications, Helm values, Kustomize overlays, and namespace templates are agent-generated. |
| 3 | Validation Before Application: Pre-commit validation gates | PASS | helm template + kubeconform for Helm, kustomize build + kubeconform for Kustomize, shellcheck for scripts. scripts/validate.sh runs all checks. |
| 4 | Multi-Project Namespace Isolation: Namespace isolation enforced | PASS | Namespace template includes ResourceQuota, LimitRange, deny-all NetworkPolicy. Each component gets its own namespace. Note: Flannel CNI on OrbStack does not enforce NetworkPolicies — policies exist for portability to production clusters. |
| 5 | Deployment Validation Checkpoints: Mandatory post-deploy checks | PASS | Bootstrap script validates each phase: cluster ready → ArgoCD healthy → components synced → sample app reachable. |
| 6 | Observability & Monitoring: Prometheus + Grafana available | PASS | kube-prometheus-stack deployed via ArgoCD. Grafana accessible at grafana.k8s.orb.local. |
| 7 | Security Baseline: No secrets in Git, pinned images, NetworkPolicies | PASS | Sealed Secrets for Git-safe secrets. All chart versions pinned. NetworkPolicies defined per namespace (not enforced by Flannel on OrbStack — portability-ready). No :latest tags. |
| 8 | Reproducibility & Portability: Idempotent bootstrap from clean machine | PASS | Prerequisites script installs all tools. Bootstrap script is idempotent. Full rebuild < 15 min. |
| 9 | Helm-first deployment strategy: Check Helm before custom YAML | PASS | All 5 infrastructure components use official Helm charts. Only namespace template and sample app use Kustomize (no Helm chart exists for these). |
| 10 | Chart versions pinned: No floating versions | PASS | All chart versions explicitly pinned in ArgoCD Application targetRevision. |
Result: ALL GATES PASS — no violations, no complexity tracking needed.
Post-Phase 1 re-evaluation (2026-02-10): All 10 gates confirmed PASS after DNS correction (*.k8s.orb.local) and CNI/NetworkPolicy clarification (Flannel — no enforcement, policies for portability). No gate status changed.
specs/001-orbstack-argocd-bootstrap/
├── plan.md # This file
├── research.md # Phase 0: Helm chart research, ArgoCD 3.1.x patterns
├── quickstart.md # Phase 1: Validation scenarios
├── contracts/ # Phase 1: Service interfaces (bootstrap script, ArgoCD apps)
│ ├── bootstrap-script.md
│ └── argocd-app-of-apps.md
└── tasks.md # Phase 2 output (/specops.tasks command)
scripts/
├── bootstrap.sh # Idempotent bootstrap: install ArgoCD, apply App-of-Apps
└── prerequisites.sh # Check/install OrbStack, kubectl, helm, kustomize, kubeseal, kubeconform
argocd/
├── projects/
│ └── infrastructure.yaml # ArgoCD AppProject for infrastructure components
├── applications/
│ ├── root-app-of-apps.yaml # Root Application (manages all children)
│ ├── ingress-nginx.yaml # ArgoCD Application → Helm chart
│ ├── cert-manager.yaml # ArgoCD Application → Helm chart
│ ├── sealed-secrets.yaml # ArgoCD Application → Helm chart
│ ├── kube-prometheus-stack.yaml # ArgoCD Application → Helm chart
│ └── namespace-templates.yaml # ArgoCD Application → Kustomize (this repo)
└── helm-values/
├── argocd/
│ └── values.yaml # ArgoCD Helm overrides (used during bootstrap)
├── ingress-nginx/
│ └── values.yaml
├── cert-manager/
│ └── values.yaml
├── sealed-secrets/
│ └── values.yaml
└── kube-prometheus-stack/
└── values.yaml
kubernetes/
├── cluster-config/
│ ├── namespaces/ # System namespace definitions
│ │ ├── kustomization.yaml
│ │ ├── ingress-nginx.yaml
│ │ ├── cert-manager.yaml
│ │ ├── sealed-secrets.yaml
│ │ └── monitoring.yaml
│ ├── cert-manager/
│ │ ├── kustomization.yaml
│ │ └── cluster-issuer-selfsigned.yaml
│ └── policies/
│ └── kustomization.yaml
├── namespace-template/ # Reusable template for new project namespaces
│ ├── base/
│ │ ├── kustomization.yaml
│ │ ├── namespace.yaml
│ │ ├── resource-quota.yaml
│ │ ├── limit-range.yaml
│ │ └── network-policy.yaml
│ └── overlays/
│ └── local/
│ ├── kustomization.yaml
│ └── patches/
└── apps/
└── sample-app/ # Validation sample application
├── base/
│ ├── kustomization.yaml
│ ├── deployment.yaml
│ ├── service.yaml
│ └── ingress.yaml
└── overlays/
└── local/
├── kustomization.yaml
└── patches/
└── replicas.yaml
validation/
├── pre-deploy/
│ ├── check-cluster.sh # Verify OrbStack K8s is running
│ └── validate-manifests.sh # kubeconform + helm template validation
└── post-deploy/
├── check-argocd.sh # Verify ArgoCD health + sync status
├── check-components.sh # Verify all infrastructure pods Running
└── check-ingress.sh # Verify ingress routing works
docs/
├── architecture.md # Component diagram, network topology
└── runbook.md # Common operations, troubleshooting
Structure Decision: Multi-tool structure (ArgoCD + Kubernetes manifests + Helm values). No Terraform — OrbStack manages the cluster lifecycle. ArgoCD manages all Kubernetes resources via Git. The argocd/ directory holds all ArgoCD-specific configs (applications, projects, helm-values). The kubernetes/ directory holds Kustomize-based resources (namespace templates, cluster config, custom apps). The scripts/ directory holds bootstrap and validation scripts.
No constitution violations detected. No complexity justifications required.