Spin up helloworld container for POC

[nicklathe]

Here was the plan to create this change:

PLAN: Hello-world app driven by Kargo

Goal

Stand up a small, fully isolated app that Kargo watches and deploys, to prove out
the watch → promote → deploy → DNS pipeline without depending on the (currently broken)
code-dot-org image/chart.

• Image watched: docker.io/library/nginx (the official nginx image, serving its
  static "Welcome to nginx!" page on :80; public, so no pull credentials needed). It
  reflects no request data back, and publishes well-maintained immutable semver tags
  (e.g. 1.27.3), so the Warehouse uses the clean SemVer + cacheByTag: true form.
• URL: hello.k8s.code.org (single-level name, covered by the existing
  *.k8s.code.org wildcard ACM cert, so TLS is automatic).
• Isolation: a brand-new Kargo project (kargo-project-helloworld) and a brand-new
  ArgoCD app (helloworld). The existing codeai project is left completely untouched.

How it will work end to end

1. Merge these files to main.
2. ArgoCD's app-of-apps auto-discovers apps/helloworld/application.yaml; the parent
   kargo app (via a new source entry) bootstraps the new Kargo project.
3. ArgoCD syncs the helloworld app using the starting image already in
   values.yaml, so it's healthy immediately (before Kargo ever promotes).
4. The Warehouse polls Docker Hub, finds the newest matching nginx semver tag, produces Freight.
5. Auto-promotion (autoPromotionEnabled: true) runs the Stage: clone repo → write the
   tag into apps/helloworld/values.yaml → commit + push to main → argocd-update.
6. ArgoCD re-syncs; external-dns sees the code.ai/dns-name label on the Ingress and
   creates the hello.k8s.code.org Route53 record automatically.

---

Files to CREATE

A. Deployment target — apps/helloworld/

A small local Helm chart plus an ArgoCD Application, mirroring the multi-source
pattern codeai uses (chart from one source, image value from a $values file that Kargo
rewrites).

1. apps/helloworld/application.yaml — ArgoCD Application named helloworld.

   • Multi-source: source 1 = local chart at apps/helloworld/chart with
     valueFiles: [$values/apps/helloworld/values.yaml]; source 2 = this repo as ref: values.
   • Destination namespace helloworld, syncOptions: [CreateNamespace=true, ServerSideApply=true],
     automated prune + selfHeal.
   • Critical Kargo wiring (so the Stage's argocd-update is authorized):
     • annotation kargo.akuity.io/authorized-stage: kargo-project-helloworld:dev
     • label kargo.akuity.io/project: kargo-project-helloworld

2. apps/helloworld/values.yaml — the file Kargo rewrites on each promotion.

   • image: docker.io/library/nginx:1.27.3 ← real (immutable) starting value so the
     app is healthy before the first promotion.
   • dnsName: hello

3. apps/helloworld/chart/Chart.yaml — minimal chart metadata (type: application).

4. apps/helloworld/chart/values.yaml — defaults: image, dnsName: hello, replicas: 1.

5. apps/helloworld/chart/templates/deployment.yaml — Deployment running the
   nginx container on containerPort: 80, with readiness/liveness httpGet / probes.

6. apps/helloworld/chart/templates/service.yaml — ClusterIP Service :80 → 80.

7. apps/helloworld/chart/templates/ingress.yaml — Ingress fronting the Service:

   • ingressClassName: aws-alb (the cluster default ALB class).
   • label code.ai/dns-name: {{ .Values.dnsName }} → external-dns creates hello.k8s.code.org.
   • host rule hello.k8s.code.org so the ALB auto-discovers the wildcard ACM cert for HTTPS.
   • ALB annotations as needed (see Open Question 1).

B. Kargo project — apps/kargo/projects/helloworld/

Mirrors apps/kargo/projects/codeai/ structure.

8. project.yaml — kind: Project, name kargo-project-helloworld.

9. namespace.yaml — namespace kargo-project-helloworld with the required
   kargo.akuity.io/project: "true" label.

10. project-config.yaml — promotionPolicies: [{ stage: dev, autoPromotionEnabled: true }].

11. application.yaml — ArgoCD Application named kargo-project-helloworld that
    recurses this dir (excluding application.yaml), modeled on codeai's project app.

12. warehouse.yaml — kind: Warehouse named kargo-project-helloworld:

    • repoURL: docker.io/library/nginx
    • imageSelectionStrategy: SemVer with semverConstraint: '>=1.27.0'
    • cacheByTag: true — nginx patch tags (e.g. 1.27.3) are immutable, so caching is safe.
    • (no git-<sha> regex or amd64/arm64 ignores — those are codeai-specific)

13. stages/dev.yaml — kind: Stage named dev, modeled on codeai's staging.yaml:

    • requestedFreight from Warehouse kargo-project-helloworld, direct: true.
    • Steps: git-clone → yaml-update (path ./gitops/apps/helloworld/values.yaml,
      key image, value docker.io/library/nginx:${{ imageFrom("docker.io/library/nginx").Tag }})
      → git-commit (message Promote helloworld dev to <tag> [skip ci]) → git-push
      → argocd-update (app helloworld, namespace argocd).
    • Every imageFrom(...) argument is docker.io/library/nginx — must exactly match
      the Warehouse repoURL or promotion fails.

---

File to EDIT (1)

apps/kargo/application.yaml — add a 4th source so the parent kargo app bootstraps
the new project's Application (same pattern as the existing codeai source):

- repoURL: https://github.com/code-dot-org/k8s-gitops.git
  targetRevision: main
  path: apps/kargo/projects/helloworld
  directory:
    include: application.yaml

This is the only non-auto-discovered registration step.

---

Open questions / risks to confirm during execution

1. EKS Auto Mode ALB annotations. The cluster uses the EKS Auto Mode ALB controller
   (eks.amazonaws.com/alb), not the standalone AWS Load Balancer Controller. The exact
   alb.ingress.kubernetes.io/* annotation set (and whether the ACM cert is auto-discovered
   by host vs. needs an explicit certificate-arn) should be confirmed against the
   code-dot-org base Ingress before relying on HTTPS. Plan: start minimal (default
   aws-alb class + host rule + dns-name label); if HTTPS doesn't come up, add the
   certificate-arn/listen-ports annotations to match the working codeai ingress.

2. Kargo git-push credentials. Promotion pushes to this repo using the shared
   cred-type: git secret in kargo-shared-resources. This works for codeai, which
   implies the controller treats that namespace as global credentials — so the new project
   should inherit it. Confirm the first promotion actually pushes; if it fails on auth,
   the fix is to make the git credential available to kargo-project-helloworld.

3. nginx tag format. Assumes the official nginx image publishes full X.Y.Z semver
   tags (it does, e.g. 1.27.3). With strictSemvers (default), partial tags like 1.27
   or 1 are ignored and the Warehouse picks the newest full-semver tag matching
   >=1.27.0 — produced on the first poll and auto-promoted.

---

Verification (after merge)

• ArgoCD (https://argocd.k8s.code.org): helloworld and kargo-project-helloworld
  apps go Synced/Healthy.
• Kargo (https://kargo.k8s.code.org): Warehouse produces Freight; dev Stage promotes;
  a Promote helloworld dev to <tag> [skip ci] commit lands on main.
• CLI:
  • kubectl -n helloworld get pods,svc,ingress
  • kubectl -n kargo-project-helloworld get warehouse,freight,stage
• URL: curl -i https://hello.k8s.code.org returns the nginx welcome page over HTTPS.

Rollback

Delete apps/helloworld/ and apps/kargo/projects/helloworld/, revert the
apps/kargo/application.yaml edit, merge. ArgoCD prunes all resources; external-dns
(policy: sync) removes the Route53 record automatically.

---

Execution order

1. Create apps/helloworld/ (chart + Application + values).
2. Create apps/kargo/projects/helloworld/ (project, namespace, config, app, warehouse, stage).
3. Edit apps/kargo/application.yaml (add the 4th source).
4. (Optional) helm template/kustomize build locally to sanity-check the chart renders.
5. Branch → PR → merge to main. ArgoCD + Kargo do the rest.