Deploying the APIs (Flux GitOps → Talos)

Handoff doc. The APIs are not deployed by Gitea Actions — they are deployed by Flux running on the Talos Kubernetes cluster. The Gitea Actions in this repo only build the docs-site image, validate Flux manifests, and publish OpenAPI specs to RapidAPI.

How a deploy actually happens

API repo (e.g. leeworks-agents/zip-enrichment)
  └─ its own CI builds & pushes  registry.leeworks.dev/zip-enrichment/server:<tag>
       └─ Flux image-automation (flux/image-automation/) rewrites the
          {"$imagepolicy": "flux-system:<api>"} marker in flux/<api>/helmrelease.yaml
            └─ Flux GitRepository "api-company" (polls main every 5m)
                 └─ HelmRelease per API (flux/<api>/helmrelease.yaml, bedag/raw chart)
                      └─ Deployment rolls out in the cluster namespace

Each API has its own directory under flux/:

API	Namespace	HelmRelease path	Image
zip-enrichment	`zip-enrichment`	`flux/zip-enrichment/helmrelease.yaml`	`registry.leeworks.dev/zip-enrichment/server`
holidays	`holidays`	`flux/holidays/helmrelease.yaml`	`registry.leeworks.dev/holidays/server`
air-quality	`air-quality`	`flux/air-quality/helmrelease.yaml`	`registry.leeworks.dev/air-quality/server`
vin-decoder	`vin-decoder`	`flux/vin-decoder/helmrelease.yaml`	`registry.leeworks.dev/vin-decoder/server`

(Confirm each path's exact image with grep -r imagepolicy flux/.)

Prerequisite: the manifests must be live in the cluster's Flux source

flux/api-company-source/gitrepository.yaml is reference only. The authoritative copy must be committed to 0xWheatyz/Talos at:

testing1/first-cluster/cluster/flux/api-company/

If that path does not point Flux at this repo's flux/ directory, Flux never sees these HelmReleases and nothing deploys. Verify the Talos repo references this repo's main branch and that a Flux Kustomization includes the api-company path.

Per-API the cluster also needs (already templated under flux/<api>/):

namespace.yaml — the target namespace
the gitea-registry imagePullSecret in that namespace
externalsecret.yaml — pulls API keys (e.g. RapidAPI) via external-secrets
servicemonitor.yaml — Prometheus scraping (optional for deploy)

One-time local setup (machine with cluster access)

You need tools that are not installed on the dev machine yet:

# Talos kubeconfig — export from the Talos controlplane, e.g.:
#   talosctl kubeconfig ~/.kube/talos-leeworks
export KUBECONFIG=~/.kube/talos-leeworks
kubectl cluster-info        # must succeed before continuing

# Flux CLI
brew install fluxcd/tap/flux
# Helm (optional, for debugging charts)
brew install helm

flux check                  # confirm Flux is installed & healthy in-cluster

Deploy / sync all APIs

export KUBECONFIG=~/.kube/talos-leeworks

# 1. Pull the latest main into the cluster's Git source
flux reconcile source git api-company -n flux-system

# 2. Apply the manifests (name may differ — check: flux get kustomizations -A)
flux reconcile kustomization api-company -n flux-system

# 3. Reconcile each API's HelmRelease
flux reconcile helmrelease zip-enrichment -n zip-enrichment
flux reconcile helmrelease holidays       -n holidays
flux reconcile helmrelease air-quality    -n air-quality
flux reconcile helmrelease vin-decoder    -n vin-decoder

# 4. Verify everything is Ready
flux get helmreleases -A
kubectl get pods -A | grep -E 'zip-enrichment|holidays|air-quality|vin-decoder'

Troubleshooting

# Why is a release not Ready?
flux get helmrelease <name> -n <ns>
kubectl describe helmrelease <name> -n <ns>

# Is image automation picking up new tags?
flux get image policy -n flux-system
flux get image update -A

# Pod won't start (image pull / secret issues)
kubectl describe pod <pod> -n <ns>
kubectl get events -n <ns> --sort-by=.lastTimestamp | tail -20

Force a fresh deploy of a single API

flux suspend helmrelease <name> -n <ns>
flux resume  helmrelease <name> -n <ns>   # triggers a fresh reconcile
# or restart the workload directly:
kubectl rollout restart deployment/<name> -n <ns>

docs/operator-runbook.md — day-2 operations
docs/registry.md — container registry (registry.leeworks.dev) setup
docs/secrets-checklist.md — required cluster secrets
flux/image-automation/ — automatic image tag bumping

4.5 KiB Raw Blame History