| name | divyam-deploy |
| description | The end-to-end deployment workflow for the Divyam platform in THIS repo — what to run, in what order, with which checks — from a clean machine to a running stack, across GCP or Azure. Use to drive or explain a full or partial deploy, decide the next step, or recover when a step fails. TRIGGER on: "deploy Divyam end to end", "provision then deploy", "what's the next step", "set up a new environment", layer ordering questions, Phase 1 → Phase 2 handoff, kubeconfig→helmfile sequence, CI/CD for the fork. Pairs with divyam-tooling (command/flag details) and divyam-platform-engineer (safety mindset).
|
Divyam deployment workflow
Two phases: Phase 1 provisions cloud infra incl. the GKE/AKS cluster (iac/, via make iac);
Phase 2 deploys the whole app stack onto it (k8s/, via make k8s). Phase 1 ends by writing
k8s/helm-values/provider.yaml, which Phase 2 consumes. Run Phase 2 from the bastion created in
Phase 1. Always preview (plan/diff) before mutating; see divyam-platform-engineer for the safety
rules and divyam-tooling for exact flags.
The path (happy path, condensed)
Run everything through the Makefile entrypoint — make iac -- <args> / make k8s -- <args> (the --
passes flags through). Add -n to any step to preview the command without running it.
make prereqs # 0. toolchain (once)
# user runs: ! az login / ! gcloud auth login + gcloud auth application-default login
make iac -- config -c <gcp|azure> -e <env> # 1. remember cloud+env
make iac -- secrets # 2. generate iac/values/secrets.env, then FILL real values (creds, registry, webhooks)
make iac -- creds # 3. validate cloud auth
make iac -- plan -l 0-foundation && make iac -- apply -l 0-foundation # 4. foundation (LOCAL state — careful)
make iac -- plan -l 1-platform && make iac -- apply -l 1-platform # 5. platform (k8s before monitoring = automatic)
make iac -- plan -l 2-app && make iac -- apply -l 2-app # 6. app (writes provider.yaml)
# review k8s/helm-values/provider.yaml # 7. Phase-1 handoff check
make k8s -- kubeconfig && kubectl get ns # 8. auth + kubeconfig
# ensure k8s/helm-values/resources.yaml + artifacts (ARTIFACTS_VERSION) are set # 9.
make k8s -- diff # 10. preview
make k8s -- install -a <version> # 11. FIRST install (helmfile sync)
make k8s -- status # 12. verify (helm ls -A / pods)
# later, routine changes:
make k8s -- diff && make k8s -- upgrade -l <chart> # helmfile apply, only changed
The make iac/k8s -- commands forward verbatim to ./scripts/iac.sh / ./scripts/k8s.sh, which are
identical and run directly without -- (used by the slash commands and CI). See divyam-tooling
for the full flag reference and divyam-platform-engineer for the safety rules.
Decision points
- Cloud:
-c gcp vs -c azure (set once via config). Differences (project vs RG, auth,
get-credentials) → divyam-tooling/references/clouds.md.
- Whole layer vs sub-unit:
apply -l 1-platform is correct (DAG orders sub-units). Use
-l 1-platform.1-k8s when iterating on just the cluster.
- Observability backend: cloud-native (default) vs Datadog (
datadog.enabled=true + TF_VAR_datadog_*).
- First install vs upgrade:
install (=sync, all releases) only the first time; then upgrade (=apply).
- Single chart:
make k8s -- upgrade -l router → helmfile -l name=router-<env> apply.
Reference guide — load for detail
| Need | Reference |
|---|
| Phase 1 detail: layer/sub-layer contents, ordering, LOCAL-state caveat, secrets, observability deploy | references/phase1-infra.md |
| Phase 2 detail: kubeconfig, values files, artifacts resolution, helmfile ops, single-chart, destroy | references/phase2-stack.md |
Forked-repo CI/CD: PR-gated diff, post-merge apply | references/cicd.md |
| When a step fails: already-exists, state, missing layer, filter misses, kubeconfig/auth, image pull | references/troubleshooting.md |
| Adopting a prior/lost-state deployment, imports, cluster-recreate workload-identity rebind | divyam-tooling/references/recovery-and-imports.md |
| Known blockers + fixes (Helm 4, env allowlist + org/env name-length, NAP NodePools, Kafka RF, App-GW subnet, state-key fork) | divyam-tooling/references/known-gotchas.md |
| Read cloud ground truth without az/gcloud (verify a handoff, count resources, inspect a subnet) | divyam-tooling/references/ground-truth-rest.md |
Human handoffs in this flow (delegate → pause → verify)
This flow is run with a DevOps/SRE/dev team (see divyam-platform-engineer). Treat these as
action items you hand off and then verify before resuming, not steps you silently do or assume:
cloud login (step 0/1 → verify make iac -- creds); filling real secrets incl. the Azure GAR
docker-auth file (step 2 → verify file exists + jq empty); approving each layer/stack apply (steps
4-6, 11); reviewing provider.yaml (step 7); kubeconfig if az/gcloud is interactive (step 8 →
verify kubectl get ns). On AKS, apply -l 2-app must include 0-nap_configs (NAP NodePools) or
all pods stay Pending — see known-gotchas. For a large first install, prefer staged: ESO →
verify ExternalSecrets SecretSynced → rest (/deploy-stack-staged).
Guardrails
- Never skip the
plan/diff before apply/install/upgrade; never sync after first install.
0-foundation is LOCAL state — never blindly re-apply/destroy; coordinate.- Don't proceed to Phase 2 until
provider.yaml exists and looks right (env, cloud, storage).
- Cloud login is the user's step — pause, ask them to run it, then verify; don't attempt interactive login yourself.
- Phase 2 needs Helm 3 (Helm 4 breaks helmfile/diff) — see known-gotchas / prerequisites.
