# 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:

```bash
# 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

```bash
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

```bash
# 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

```bash
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>
```

## Related docs in this repo
- `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