Feat/argocd

.github/workflows/django.yml

@@ -5,6 +5,26 @@ on:
     branches: [ "main" ]
   pull_request:
     branches: [ "main" ]
+  workflow_dispatch:
+
+# Serializes the whole test -> lint -> manifests -> publish -> bump chain per
+# ref, not just the bump job. Without this, two pushes to main can race:
+# if commit A's pipeline starts first but commit B's finishes publish first,
+# job-level concurrency on bump alone would still process B's bump before
+# A's, letting A's bump overwrite B's newer image tag — an unintended
+# GitOps rollback. Keying by ref keeps PRs on different branches from
+# blocking each other.
+#
+# GitHub does not guarantee strict FIFO ordering across every trigger in a
+# concurrency group: with cancel-in-progress: false, the currently running
+# workflow is protected, but only the single most recently queued run is
+# kept — an older *queued* run is cancelled outright when a newer one
+# arrives, rather than waiting its turn. For this race that is actually the
+# property we want: a stale intermediate push never runs its bump after a
+# newer one, it just never runs at all.
+concurrency:
+  group: ahc-ci-${{ github.ref }}
+  cancel-in-progress: false
 
 jobs:
   lint:
@@ -83,11 +103,67 @@ jobs:
       - name: Run tests (pytest)
         run: uv run pytest -m "not slow"
 
+  manifests:
+    name: Kubernetes manifests
+    runs-on: ubuntu-latest
+    env:
+      KUSTOMIZE_VERSION: "5.8.1"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install pinned kustomize
+        run: |
+          curl -fsSL "https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize%2Fv${KUSTOMIZE_VERSION}/kustomize_v${KUSTOMIZE_VERSION}_linux_amd64.tar.gz" \
+            | tar xz -C /usr/local/bin kustomize
+          kustomize version
+
+      - name: Render base
+        run: kustomize build kubernetes/base > /tmp/base.yaml
+
+      - name: Render ArgoCD test overlay
+        run: kustomize build kubernetes/overlays/minikube-argocd > /tmp/minikube-argocd.yaml
+
+      # overlays/home joins once its sealed/ files exist (requires the home
+      # cluster's sealed-secrets controller key).
+
+      - name: Assert sync-wave present on SealedSecrets
+        run: |
+          python3 - <<'EOF'
+          import sys, yaml
+          docs = list(yaml.safe_load_all(open("/tmp/minikube-argocd.yaml")))
+          sealed = [d for d in docs if d and d.get("kind") == "SealedSecret"]
+          assert sealed, "no SealedSecrets rendered"
+          for d in sealed:
+              wave = d["metadata"].get("annotations", {}).get("argocd.argoproj.io/sync-wave")
+              assert wave == "-3", f"{d['metadata']['name']}: sync-wave={wave!r}, expected '-3'"
+          print(f"OK: {len(sealed)} SealedSecrets at wave -3")
+          EOF
+
+      # overlays/aws joins the render step above once its sealed/ files exist
+      # (same reasoning as overlays/home). Terraform is validated separately
+      # below — it needs neither AWS credentials nor sealed secrets.
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: "1.9.8"
+
+      - name: Terraform fmt check
+        run: terraform -chdir=terraform/aws fmt -check -recursive
+
+      - name: Terraform init (no backend, no cloud credentials needed)
+        run: terraform -chdir=terraform/aws init -backend=false
+
+      - name: Terraform validate
+        run: terraform -chdir=terraform/aws validate
+
   publish:
     name: Publish app image to GHCR
     runs-on: ubuntu-latest
-    needs: [test, lint]
-    if: github.event_name == 'push'
+    needs: [test, lint, manifests]
+    # workflow_dispatch allows publishing a sha- tag from a feature branch
+    # (e.g. to test the branch on minikube before merge).
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
     permissions:
       contents: read
       packages: write
@@ -105,12 +181,83 @@ jobs:
       - name: Set lowercase owner
         run: echo "OWNER=${GITHUB_REPOSITORY_OWNER,,}" >> $GITHUB_ENV
 
+      - name: Set image tags
+        # The prod tag moves ONLY on main: Watchtower deploys whatever prod
+        # points at, so a branch dispatch must never touch it.
+        run: |
+          TAGS="ghcr.io/${OWNER}/ahc-app:sha-${{ github.sha }}"
+          if [ "${{ github.ref }}" = "refs/heads/main" ]; then
+            TAGS="${TAGS},ghcr.io/${OWNER}/ahc-app:prod"
+          fi
+          echo "TAGS=${TAGS}" >> $GITHUB_ENV
+
       - name: Build and push ahc-app
         uses: docker/build-push-action@v6
         with:
           context: .
           file: docker/Dockerfile-app
           push: true
-          tags: |
-            ghcr.io/${{ env.OWNER }}/ahc-app:prod
-            ghcr.io/${{ env.OWNER }}/ahc-app:sha-${{ github.sha }}
+          tags: ${{ env.TAGS }}
+
+  bump:
+    name: Bump image tag in home overlay
+    runs-on: ubuntu-latest
+    needs: publish
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    permissions:
+      contents: write
+    env:
+      KUSTOMIZE_VERSION: "5.8.1"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: main
+
+      - name: Install pinned kustomize
+        run: |
+          curl -fsSL "https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize%2Fv${KUSTOMIZE_VERSION}/kustomize_v${KUSTOMIZE_VERSION}_linux_amd64.tar.gz" \
+            | tar xz -C /usr/local/bin kustomize
+          kustomize version
+
+      - name: Set lowercase owner
+        run: echo "OWNER=${GITHUB_REPOSITORY_OWNER,,}" >> $GITHUB_ENV
+
+      - name: Set image tag in home overlay
+        run: |
+          cd kubernetes/overlays/home
+          kustomize edit set image "ghcr.io/${OWNER}/ahc-app=ghcr.io/${OWNER}/ahc-app:sha-${{ github.sha }}"
+
+      - name: Commit and push
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add kubernetes/overlays/home/kustomization.yaml
+          if git diff --cached --quiet; then
+            echo "No image tag change to commit."
+            exit 0
+          fi
+          git commit -m "chore(deploy): bump ahc-app to sha-${{ github.sha }} [skip ci]"
+          git push
+
+  deploy-workflow:
+    name: Submit deploy-smoke Argo Workflow
+    runs-on: ubuntu-latest
+    needs: bump
+    # Self-disabled until an Argo Server is reachable from CI (self-hosted
+    # runner or tunnel). ArgoCD auto-sync remains the primary deploy path.
+    if: github.event_name == 'push' && vars.ARGO_SERVER_URL != ''
+    steps:
+      - name: Submit workflow via Argo Server API
+        run: |
+          curl -fsS -X POST \
+            -H "Authorization: Bearer ${{ secrets.ARGO_TOKEN }}" \
+            -H "Content-Type: application/json" \
+            "${{ vars.ARGO_SERVER_URL }}/api/v1/workflows/argo/submit" \
+            -d '{
+              "resourceKind": "WorkflowTemplate",
+              "resourceName": "ahc-deploy-smoke",
+              "submitOptions": {
+                "parameters": ["image-tag=sha-${{ github.sha }}"]
+              }
+            }'

.gitignore

@@ -65,6 +65,10 @@ CLAUDE.md
 /tars/
 /kubernetes/**/*.tar
 secret.yaml
+# Filled plain Secrets (templates stay tracked; SealedSecrets in sealed/ stay tracked)
+kubernetes/overlays/*/secrets/*.yaml
+# Fetched sealed-secrets controller certificates
+*.pem
 
 # Volumes
 /db/

README.md

@@ -81,11 +81,20 @@ The stack exposes: Django app on `:8000`, Flower (Celery monitor) on `:5555`.
    uv run python manage.py runserver
    ```
 
-### Kubernetes Deploy (alternative)
-
-An alternative to Docker Compose for production-like environments.
-See [`kubernetes/`](kubernetes/) for kustomization files and secret templates.
-Build and load images, then apply with `kubectl apply -k kubernetes/`.
+### Kubernetes Deploy (GitOps via ArgoCD)
+
+Kubernetes manifests live in `kubernetes/` as a kustomize base with four overlays
+(`minikube-local` for a plain `kubectl apply -k` dev loop, `minikube-argocd` for the GitOps
+rehearsal, `home` for the production k3s cluster synced by ArgoCD, `aws` for an EKS demo target
+provisioned by Terraform). Images are pulled from GHCR; the deployed tag for `home` is committed
+to git by CI, other overlays are bumped manually.
+
+- Operational runbook (local run, sealing secrets, rehearsal, home bootstrap, backups):
+  [`kubernetes/README.md`](kubernetes/README.md)
+- AWS EKS runbook (Terraform bootstrap, cost, **mandatory teardown**):
+  [`kubernetes/README-aws.md`](kubernetes/README-aws.md)
+- Architecture decision records: [`doc/13_adr_gitops_argocd.md`](doc/13_adr_gitops_argocd.md),
+  [`doc/14_adr_aws_eks_deployment.md`](doc/14_adr_aws_eks_deployment.md)
 
 ## Testing
 

argocd/ahc-aws.yaml

@@ -0,0 +1,22 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: ahc-aws
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://github.com/Cybernetic-Ransomware/Animals_Healthcare_Application.git
+    targetRevision: main
+    path: kubernetes/overlays/aws
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: ahc
+  # Deliberately no automated sync policy: this is a new cluster type (EKS +
+  # ALB Controller + EBS CSI) with its own untested failure modes. Syncs are
+  # manual until a full drift/prune/sealed-secret-recovery pass has been
+  # done here, same bar ahc-home was held to before it got automation
+  # (see argocd/ahc-minikube-test.yaml for the precedent).
+  syncPolicy:
+    syncOptions:
+      - CreateNamespace=true

argocd/ahc-home.yaml

@@ -0,0 +1,26 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: ahc-home
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://github.com/Cybernetic-Ransomware/Animals_Healthcare_Application.git
+    targetRevision: main
+    path: kubernetes/overlays/home
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: ahc
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true
+    retry:
+      limit: 3
+      backoff:
+        duration: 30s
+        factor: 2
+        maxDuration: 5m

argocd/ahc-minikube-test.yaml

@@ -0,0 +1,20 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: ahc-minikube-test
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://github.com/Cybernetic-Ransomware/Animals_Healthcare_Application.git
+    targetRevision: main
+    path: kubernetes/overlays/minikube-argocd
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: ahc
+  # Deliberately no automated sync policy: syncs are manual, without prune
+  # and without selfHeal, until drift/prune/sealed-secret-recovery tests
+  # pass on minikube. Automation belongs to ahc-home after the merge.
+  syncPolicy:
+    syncOptions:
+      - CreateNamespace=true

argocd/ahc-workflows.yaml

@@ -0,0 +1,20 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: ahc-workflows
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://github.com/Cybernetic-Ransomware/Animals_Healthcare_Application.git
+    targetRevision: main
+    path: workflows
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: argo
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true

argocd/argo-workflows.yaml

@@ -0,0 +1,26 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: argo-workflows
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://argoproj.github.io/argo-helm
+    chart: argo-workflows
+    targetRevision: 0.45.11
+    helm:
+      values: |
+        server:
+          # Homelab-grade auth: the server acts with its own service account.
+          authModes:
+            - server
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: argo
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true

argocd/sealed-secrets.yaml

@@ -0,0 +1,22 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: sealed-secrets
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://bitnami-labs.github.io/sealed-secrets
+    chart: sealed-secrets
+    targetRevision: 2.17.3
+    helm:
+      values: |
+        # Default name expected by the kubeseal CLI discovery.
+        fullnameOverride: sealed-secrets-controller
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: kube-system
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true