Skip to main content
You will run the shop API from Build a Go and React app on a Kubernetes cluster you operate, deploy it with one forge env deploy, and check that the pods run what the release recorded. An optional step hands delivery to an in-cluster Flux. An environment with no control plane is self-hosted: forge applies it with your kubectl context and records releases in your machine’s ledger. The release model is the one the hosted deploy uses; only one KCL file differs. Your cluster is also where the kinds Reliant hosting refuses run: kind = "cron" workloads and operators.

Before you begin

  • The shop project from Build a Go and React app, with every change committed.
  • Forge v1.6.1 or later in the project (reliant forge --version). This guide ran at v1.6.1-0.20261115024114-0ab7c562e817.
  • Docker, to build the image.
  • A cluster you have a kubectl context for, a registry your machine can push to and the cluster can pull from, and a Postgres the cluster can reach.
This guide used a local k3d cluster with its own registry (the mirror lets the nodes pull localhost:5051/...) and a Postgres container on port 15432:
terminal
registries.yaml
1

Declare an environment for your cluster

Derive an environment from the scaffolded prod with both workloads rebound to a cluster, then generate its config.k:
terminal
env new keeps prod’s hosted declarations and leaves _cluster = None. Replace deploy/kcl/k8s/main.k with your cluster’s facts; this guide deployed:
deploy/kcl/k8s/main.k
With no control_plane the environment is self-hosted. forge applies only to the context cluster names, never your shell’s current one. A cron workload or operator joins as _on_cluster(wl.<name>). Commit the change.
2

Check what it renders

terminal
Output
The migration is an init container in every API pod, so no pod serves an old schema. What gets deployed lists what each kind renders.
3

Create the database Secret

The API and the migration read DATABASE_URL from key database_url of the shop-secrets Secret:
terminal
The deploy’s preflight checks that the declared key exists before it applies anything.
4

Deploy

terminal
With no version it builds and pushes the image, cuts a release, plans and applies; --yes approves the plan. It took 90 seconds:
Output (trimmed)
It waits for every Deployment to become ready and exits non-zero if one does not. See Releases and promotion.
5

Verify it works

terminal
In a second terminal:
terminal
Output
readyz reports the database connection; the RPC refuses an unsigned caller because authentication is fail-closed. Then compare the running digests with the release:
terminal
Output (trimmed)
Its local-stack checks (App Health, pprof, ClickStack) show as undetermined; they describe forge env up, not a cluster.
6

Optional: hand delivery to Flux

Direct apply needs cluster write access wherever you deploy from, and nothing corrects drift between deploys. To have a reconciler own the cluster, set applier = "flux", commit, bootstrap once, then deploy:
terminal
Output (trimmed)
env status then names the Flux as the reconciler. Grants, pull secrets and exit 9: Self-hosted delivery.
7

Clean up

reliant forge env delete is for hosted environments only. On a cluster you keep, delete the shop-k8s namespace and what the Flux bootstrap installed (reliant forge env render k8s --target flux-delivery --list). Delete a trial cluster whole:
terminal
Releases stay in your machine’s ledger (reliant forge env releases list k8s).

What this does not do

  • No rollback: recover by deploying a fix or an earlier release (Recover from a bad deploy).
  • No autoscaling: _cluster_replicas is a fixed floor.
  • It installs no platform. Ingress needs a Gateway API controller and the routes in deploy/kcl/ingress.k; a forge.ManagedDatabase on the cluster needs the CloudNativePG operator (What gets deployed).
  • No sign-in: set jwt_issuer and oidc_client_id for your own issuer in deploy/kcl/k8s/config.k; until then authenticated RPCs are refused.
  • No frontend: bind web to your own bucket (Environments) or ship it elsewhere.

Troubleshooting

The preflight refuses an undeclared Secret even when it exists. Declare it in required_secrets (step 1).
Dev’s file-backed secrets are refused for a cluster forge did not create. Create the Secret and declare it in required_secrets.
Declare applier = "forge" (direct apply) or applier = "flux".
_image must resolve from your machine and from the nodes. On k3d, a localhost registry needs the mirror in the tip above.

Next steps

Self-hosted delivery

Direct apply or an in-cluster Flux: grants, pull secrets, exit 9 and tuning.

Promote to production

Deploy the same release to a second environment by digest.

Add a worker or cron job

Scaffold a cron worker, or a kind = "cron" workload for your cluster.

Environments

Runtimes, binders and connecting a cluster to a hosted environment.