specops-orbstack-argocd

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 provisions a fully operational cluster with ingress, TLS certificates, secret management, and monitoring — all managed declaratively through ArgoCD's App-of-Apps pattern.

Stack

Component	Version	Purpose
OrbStack	Latest	Lightweight Kubernetes runtime for macOS ARM
Kubernetes	1.31.x	Container orchestration (single-node, local)
ArgoCD	3.1.9 (chart 9.0.1)	GitOps continuous delivery
ingress-nginx	4.14.3	Ingress controller with *.k8s.orb.local DNS
cert-manager	1.19.3	TLS certificate management (self-signed CA)
sealed-secrets	2.18.0	Git-safe encrypted secrets
kube-prometheus-stack	81.5.2	Monitoring (Prometheus + Grafana + Alertmanager)

Quick Start

# 1. Verify prerequisites
./scripts/prerequisites.sh

# 2. Bootstrap the entire platform (< 10 minutes)
./scripts/bootstrap.sh

# 3. Access services
open https://argocd.k8s.orb.local     # ArgoCD UI (admin / from argocd-initial-admin-secret)
open https://grafana.k8s.orb.local    # Grafana (admin / admin)

For detailed installation instructions, see docs/setup-guide.md.

Project Structure

.
├── argocd/
│   ├── applications/          # ArgoCD Application manifests (Helm with inline values)
│   │   ├── cert-manager.yaml
│   │   ├── ingress-nginx.yaml
│   │   ├── kube-prometheus-stack.yaml
│   │   ├── sealed-secrets.yaml
│   │   ├── root-app-of-apps.yaml      # (requires Git remote)
│   │   └── namespace-templates.yaml   # (requires Git remote)
│   ├── helm-values/           # Standalone Helm values (reference copies)
│   └── projects/              # ArgoCD AppProject definitions
├── kubernetes/
│   ├── cluster-config/        # Namespaces, ClusterIssuers, base config
│   ├── namespace-template/    # Kustomize: ResourceQuota + LimitRange + NetworkPolicy
│   └── apps/                  # Sample application manifests
├── scripts/
│   ├── bootstrap.sh           # 6-phase idempotent bootstrap script
│   └── prerequisites.sh       # Dependency checker
├── validation/
│   ├── pre-deploy/            # Cluster readiness & manifest validation
│   └── post-deploy/           # ArgoCD, component, and ingress checks
├── docs/
│   ├── setup-guide.md         # Installation guide (English)
│   ├── kurulum-rehberi.md     # Installation guide (Turkish)
│   ├── architecture.md        # Component diagrams & network topology
│   └── runbook.md             # Operations runbook & troubleshooting
└── specs/                     # SpecOps design documents
    └── 001-orbstack-argocd-bootstrap/

SpecOps Design Process

This project was designed and implemented using the SpecOps methodology — an AI-assisted, spec-driven development workflow. Each feature goes through a structured pipeline of phases, producing traceable artifacts that connect requirements to implementation.

Phase Pipeline

Constitution → Specify → Clarify → Research → Plan → Contracts → Tasks → Implement → Validate

Phase Artifacts

All design documents for this feature live under specs/001-orbstack-argocd-bootstrap/.

Phase	Artifact	Description
Constitution	.specops/memory/constitution.md	Project-wide principles and standards. Defines GitOps-first approach, Helm-first deployment strategy, resource budgets, naming conventions, and technology choices. Acts as a governance document that all features must comply with.
Specify	specs/.../spec.md	Feature specification with 4 infrastructure scenarios (IS1–IS4): cluster verification, ArgoCD bootstrap, infrastructure components, and namespace onboarding. Captures assumptions, constraints, and acceptance criteria.
Clarify	Inline in spec.md	Clarification Q&A sessions recorded directly in the spec. Resolved decisions like ArgoCD version (3.1.x vs 2.13.x), CNI choice (Flannel via OrbStack), and DNS strategy (*.k8s.orb.local).
Research	specs/.../research.md	Phase 0 technical research. Covers ArgoCD 3.x breaking changes, OrbStack Kubernetes internals (Flannel CNI, CoreDNS, wildcard DNS), Helm chart version compatibility, and resource sizing for local clusters.
Plan	specs/.../plan.md	Implementation plan with tech stack decisions, deployment component matrix, file structure, resource budget (~1.4 CPU / 2.8 GiB RAM), constitution compliance gate, and phased execution strategy.
Contracts	specs/.../contracts/	API contracts and interface specifications: • argocd-app-of-apps.md — App-of-Apps sync-wave ordering, Application manifest schema • bootstrap-script.md — Bootstrap script phases, CLI flags, exit codes
Checklists	specs/.../checklists/	Pre-implementation requirement checklists that must pass before coding begins. Covers prerequisites, configuration, security, and validation requirements.
Quickstart	specs/.../quickstart.md	Integration scenarios and validation test cases (VS1–VS8): fresh bootstrap, idempotent re-run, self-heal, certificate issuance, ingress routing, namespace templates, monitoring, and sealed secrets.
Tasks	specs/.../tasks.md	31 implementation tasks (T001–T031) organized in 7 phases with dependency tracking, parallel execution markers [P], and scenario mapping. Each task includes exact file paths.
Implementation	Project root	The actual code — scripts, manifests, Kustomize overlays, and Helm values — produced by executing the task plan.
Validation	VS1–VS8 in quickstart.md	Live cluster validation scenarios executed against the deployed infrastructure. All 8 scenarios passed.

How to Read the Specs

1. Start with the Constitution to understand project-wide principles
2. Read the Spec for what this feature does and why
3. Check Research for technical decisions and trade-offs
4. Review the Plan for architecture and component choices
5. Browse Contracts for API and interface specifications
6. Follow Tasks for the step-by-step implementation order

Bootstrap Phases

The bootstrap.sh script executes 6 phases in order:

Phase	Action	Idempotent
1	Prerequisites — Verify OrbStack, kubectl, helm, kubeseal	Yes
2	Cluster — Check OrbStack K8s is running, nodes are Ready	Yes
3	ArgoCD Install — Helm install/upgrade ArgoCD into argocd namespace	Yes
4	ArgoCD Ready — Wait for ArgoCD server to be available	Yes
5	Applications — Apply ArgoCD Application manifests + namespaces + ClusterIssuers	Yes
6	Verification — Confirm all Applications are Synced and Healthy	Yes

# Full bootstrap
./scripts/bootstrap.sh

# Skip prerequisite checks (faster re-runs)
./scripts/bootstrap.sh --skip-prereq

# Dry run (show what would happen)
./scripts/bootstrap.sh --dry-run

Deployed Services

After bootstrap, these services are accessible without port-forwarding (OrbStack provides automatic DNS):

Service	URL	Credentials
ArgoCD UI	https://argocd.k8s.orb.local	admin / kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d
Grafana	https://grafana.k8s.orb.local	admin / admin
Prometheus	kubectl -n monitoring port-forward svc/prometheus-prometheus 9090:9090	—
Alertmanager	kubectl -n monitoring port-forward svc/prometheus-alertmanager 9093:9093	—

Namespace Onboarding

Create a new project namespace with resource quotas, limit ranges, and network policies:

# Copy the template
cp -r kubernetes/namespace-template/overlays/local kubernetes/namespace-template/overlays/my-project

# Edit kustomization.yaml — update namespace name and resource limits
vim kubernetes/namespace-template/overlays/my-project/kustomization.yaml

# Apply
kustomize build kubernetes/namespace-template/overlays/my-project | kubectl apply -f -

Validation

# Pre-deploy: Validate all manifests (Helm + Kustomize + shellcheck)
./validation/pre-deploy/validate-manifests.sh

# Post-deploy: Check cluster components
./validation/post-deploy/check-argocd.sh
./validation/post-deploy/check-components.sh
./validation/post-deploy/check-ingress.sh

Documentation

Document	Description
Setup Guide (English)	Step-by-step installation and configuration guide
Kurulum Rehberi (Türkçe)	Turkish installation guide
Architecture	Component diagrams, network topology, sync-wave ordering
Runbook	Operations handbook — common tasks, troubleshooting, cluster reset

License

Private — internal use only.