Shared Kubernetes manifests, GitHub Actions workflows, and the nginx runtime image that power Astro deployments. Projects consume this repo via a Git ref; updates here flow into projects on their next ref bump.
The Symfony equivalent is symfony-k8s-deployment-kit — same shape, same naming, same workflow contract.
Layout
base/ # kustomize: always included
deployment.yaml # single web container, non-root, read-only rootfs
service.yaml # app Service (port 80 -> http)
nginx-default.conf # nginx server block (brotli/gzip static, SPA-free routing)
kustomization.yaml
components/ # kustomize: opt-in per project
ssr/ # swap the nginx pod for a Node (@astrojs/node) pod
hpa/ # CPU HorizontalPodAutoscaler (+ removes spec.replicas)
pdb/ # PodDisruptionBudget
docker/
nginx/Dockerfile # the shared nginx + ngx_brotli runtime image
.github/workflows/
build-nginx.yaml # builds + publishes the shared nginx image (runs here)
deploy-production.yaml # REUSABLE — projects call via `uses:`
deploy-staging.yaml # REUSABLE — projects call via `uses:`
cleanup-staging.yaml # REUSABLE — projects call via `uses:`
examples/
overlay-production/ # consume the template for production
overlay-staging/ # consume for staging, with per-branch generator/
overlay-ssr/ # the SSR variant
docker/ # project Dockerfiles (static + SSR) and .dockerignore
workflows/ # caller stubs — copy into your project's .github/workflows/Naming convention
Generic resource names — app, app-config, app-secret, app-nginx-config,
app-hpa, app-pdb. The project's overlay sets namePrefix: (e.g. mysite-)
and kustomize rewrites every in-graph reference.
Always include the trailing dash in namePrefix — kustomize concatenates
it literally, so namePrefix: mysite produces mysiteapp.
The image placeholder is app-image. Overlays point it at the project's own
GHCR package, or Flux image automation rewrites the tag in the fleet repo.
Shared nginx image
docker/nginx/Dockerfile is the unprivileged nginx image plus the ngx_brotli
dynamic modules. It is built by .github/workflows/build-nginx.yaml and pushed
as a multi-arch image to this repo's GHCR package. Project Dockerfiles use it
as their runtime stage:
FROM ghcr.io/nickmous/astro-k8s-deployment-kit:nginx-latest AS runtime
COPY --from=build /app/dist /usr/share/nginx/htmlPin nginx-sha-<commit> instead of nginx-latest for reproducible builds.
The server config is not baked into the image — base/nginx-default.conf
ships as a ConfigMap and is mounted at /etc/nginx/conf.d/default.conf. Config
fixes therefore reach every project through a ?ref= bump, with no image
rebuild, and a config change rolls the pods (the generated name carries a
content hash).
What the config does that a default nginx doesn't:
brotli_static/gzip_staticserve the.br/.gzsiblings the build step writes, so compression costs nothing per request.try_files $uri $uri/index.html $uri/resolves Astro's directory routes (/en/sponsorship→.../index.html) with a 200 instead of a redirect, so the served URL stays canonical.- Cache-Control comes from a
map, not per-locationadd_header. Anadd_headerinside a location silently drops every header inherited from the server block — which is how security headers usually go missing on exactly the asset responses you cache hardest. /_astro/is immutable for a year, other static files a month, HTML always revalidates.
Consuming the template
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: mysite-production
namePrefix: mysite-
resources:
- github.com/NickMous/astro-k8s-deployment-kit//base?ref=v1.0.0
components:
- github.com/NickMous/astro-k8s-deployment-kit//components/hpa?ref=v1.0.0
- github.com/NickMous/astro-k8s-deployment-kit//components/pdb?ref=v1.0.0Each project pins its own ?ref=, so a change here never forces every project
to upgrade at once. See examples/overlay-production/ for a full overlay:
kubectl kustomize examples/overlay-productionRequired overlay pieces
1. namePrefix with a trailing dash
2. Traefik name references
If your ingress is a Traefik IngressRoute, copy kustomizeconfig.yaml from
the example overlay and list it under configurations:. Without it namePrefix
renames the Service to mysite-app while the IngressRoute keeps pointing at
app, and the route 404s with everything looking correct.
3. Ingress / certificate / middlewares
Project-specific (hostnames, TLS issuer, basic-auth). Copy and adapt from the example overlays.
Note that Certificate.spec.secretName and IngressRoute.spec.tls.secretName
are not rewritten by namePrefix — cert-manager creates that Secret at
runtime, so it never enters the kustomize graph. The two values match literally;
rename them together.
4. The image
images:
- name: app-image
newName: ghcr.io/nickmous/mysite
newTag: v1.0.05. A pull secret, if the package is private
The base references ghcr-login-secret — the name fleet-infra's
general-secrets creates in every app namespace. Patch it if yours differs.
Static vs SSR
The base is a static build served by nginx. For output: 'server' with
@astrojs/node in standalone mode, add the ssr component:
components:
- github.com/NickMous/astro-k8s-deployment-kit//components/ssr?ref=v1.0.0It rewrites the pod to run Node: uid 1000, envFrom app-config + app-secret,
TCP probes instead of /health, and the nginx config/cache volumes removed.
Port stays 8080, so the Service, ingress and probes are unchanged.
The overlay must supply an app-config ConfigMap containing at least
HOST=0.0.0.0 and PORT=8080 — without HOST the Astro node server binds
localhost and the kubelet's probes never reach it. It is not generated by the
component because behavior: merge only works against generators declared in a
resource base, never one declared in a component; generating it in the overlay
also means the name hash rolls the pods when config changes. See
examples/overlay-ssr/.
Build the SSR image from examples/docker/Dockerfile.ssr, which runs as the
node user (uid 1000) to match.
SITE_URL
Astro bakes the site URL into its output — canonical links, sitemap, RSS. That makes it a build-time value, not a deploy-time one, which is the main way an Astro pipeline differs from a Symfony one.
Both deploy workflows pass SITE_URL as a build arg: the production URL, or
https://<branch-slug>.staging.example.com for a branch deploy. Read it in
astro.config.mjs:
export default defineConfig({
site: process.env.SITE_URL || 'https://example.com',
});The fallback keeps local npm run build working — an unset build arg arrives
as an empty string, which is falsy.
Per-branch staging
deploy-staging.yaml renders a self-contained kustomization per branch into the
Flux fleet repo, under apps/<app-name>/staging-branches/<slug>/:
- The staging overlay is copied verbatim (including
patches/), minusgenerator/. - Every host from the
staging-domainsinput is rewritten to<slug>.<host>, and anysecretName: *-staging-tlsis prefixed with the slug so branches don't fight over one certificate. - Every
*.tmplingenerator/is rendered withenvsubstand written without the suffix; anything else there is copied as-is. Placeholders:${BRANCH_SLUG},${COMMIT_SHA},${STAGING_URL},${IMAGE},${APP_NAME}. - The root
staging-branches/kustomization.yamlis regenerated from whatever directories exist, and the result is committed and pushed (with rebase retries, since branches deploy concurrently).
Two ways the generated kustomization can find the base:
- Mode A (this template is public): its
resources:referencesgithub.com/NickMous/astro-k8s-deployment-kit//base?ref=…and Flux fetches it directly. Default. - Mode B (template is private): set
sync-base: trueon the workflow; it copies yourk8s/base/into the fleet repo and the template references../../base.
generator/kustomization.yaml.tmpl ships both, one commented out.
Two things the generated overlay must get right, both shown in the example:
labels: [..., includeSelectors: true]with abranch: ${BRANCH_SLUG}pair. Every branch ships a Deployment and Service carrying identicalapp.kubernetes.iolabels into one namespace; withoutbranchin the selectors, one branch's Service load-balances across every branch's pods.- No
Namespaceresource inside a branch directory. All branch directories are merged into one kustomization, and two of them declaring the same Namespace is a duplicate-resource error. Create the staging namespace once in the fleet repo, outside the branch directories.
Cleanup runs from cleanup-staging.yaml on branch deletion. Its slug rule is
identical to the deploy workflow's on purpose — if they ever diverge, cleanup
looks for a directory that was never created under that name.
Project workflows
The deploy logic lives here as reusable workflows — projects invoke them via
uses:, like a third-party action. Bumping the @ref upgrades every project.
Caller stubs live in examples/workflows/.
Two gotchas:
- Permissions cascade. A reusable workflow inherits the caller's
GITHUB_TOKENpermissions and can only further restrict them. If the caller doesn't grantpackages: write, the run fails withstartup_failureand no log output. Set them at the caller's job level. inputscontext. It only exists forworkflow_dispatch/workflow_call. Referencing${{ inputs.x }}under apushorreleasetrigger fails at startup — use${{ github.event.inputs.x || '' }}.
deploy-production.yaml
Builds linux/amd64 + linux/arm64 on native runners, joins them into one
manifest, tags :<version> and :production-latest, optionally cuts a Sentry
release. It does not touch the fleet repo — Flux image automation picks up the
new tag.
| Input | Required | Description |
|---|---|---|
version |
yes | Image tag to build (e.g. v1.0.0) |
prod-url |
no | Production URL — environment link and SITE_URL build arg |
site-url |
no | Overrides the SITE_URL build arg when it differs from prod-url |
dockerfile, build-context |
no | Default Dockerfile / . |
build-args |
no | Extra build args, one KEY=value per line |
sentry-org, sentry-project, sentry-url |
no | Blank skips Sentry |
deploy-staging.yaml
| Input | Required | Description |
|---|---|---|
app-name |
yes | Fleet repo path apps/<app-name>/ |
fleet-repo |
yes | OWNER/repo of the Flux fleet repo |
staging-domains |
yes | Comma-separated hosts to rewrite to {slug}.<host> |
staging-domain-base |
no | Branch URL base; defaults to the first staging-domains entry |
branch |
no | Override the ref the workflow ran on |
overlay-path |
no | Default k8s/overlays/staging |
base-path, sync-base |
no | Mode B: sync k8s/base into the fleet repo |
dockerfile, build-context, build-args |
no | As above |
platforms |
no | Default linux/amd64 |
sentry-* |
no | As above |
Outputs url — the branch's staging URL.
cleanup-staging.yaml
| Input | Required | Description |
|---|---|---|
app-name, fleet-repo |
yes | As above |
branch-name |
yes | Branch / environment name to remove |
Secrets in the project repo
| Secret | Required for | Notes |
|---|---|---|
GITHUB_TOKEN |
all | Provided automatically |
FLEET_REPO_TOKEN |
staging + cleanup | Fine-grained PAT, Contents: write on the fleet repo |
SENTRY_AUTH_TOKEN |
optional | Only when sentry-org is set |
FLUX_WEBHOOK_URL |
optional | Activated by the repo variable FLUX_WEBHOOK_ENABLED=true |
secrets: inherit in the caller passes them all through.
Local validation
# Render every example overlay
kubectl kustomize examples/overlay-production
kubectl kustomize examples/overlay-staging
kubectl kustomize examples/overlay-ssr
# Build and smoke-test the shared nginx image the way the cluster runs it:
# non-root, read-only rootfs, config from the ConfigMap.
docker build -t astro-nginx:local docker/nginx
docker run --rm -p 8080:8080 \
--read-only --tmpfs /tmp --tmpfs /var/cache/nginx \
--user 101:101 --cap-drop ALL \
-v "$PWD/base/nginx-default.conf:/etc/nginx/conf.d/default.conf:ro" \
-v "$PWD/some-astro-dist:/usr/share/nginx/html:ro" \
astro-nginx:local
curl -sI localhost:8080/ # 200, no-cache
curl -sI -H 'Accept-Encoding: br' localhost:8080/_astro/… # Content-Encoding: br
curl -s localhost:8080/health # healthyFleet-infra side
Production rollouts are Flux's job, not CI's. Per app you need a
GitRepository + Kustomization pointing at the project's
k8s/overlays/production, and an ImagePolicy + ImageUpdateAutomation that
bumps the tag in the images: block. The name: there must match the base
placeholder, app-image.
Versioning
Tag releases (v1.0.0, v1.1.0, …); projects pin ?ref=vX.Y.Z and
uses: …@vX.Y.Z. Renames and structural shifts get a major bump, additive
changes a minor one.