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
shopproject 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 atv1.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.
1
Declare an environment for your cluster
Derive an environment from the scaffolded With no
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
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
3
Create the database Secret
The API and the migration read The deploy’s preflight checks that the declared key exists before it applies anything.
DATABASE_URL from key database_url of the shop-secrets Secret:terminal
4
Deploy
terminal
--yes approves the plan. It took 90 seconds:Output (trimmed)
5
Verify it works
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)
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
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_replicasis a fixed floor. - It installs no platform. Ingress needs a Gateway API controller and the routes in
deploy/kcl/ingress.k; aforge.ManagedDatabaseon the cluster needs the CloudNativePG operator (What gets deployed). - No sign-in: set
jwt_issuerandoidc_client_idfor your own issuer indeploy/kcl/k8s/config.k; until then authenticated RPCs are refused. - No frontend: bind
webto your own bucket (Environments) or ship it elsewhere.
Troubleshooting
Secret "shop-secrets" mounted by "api" — no rendered Secret, KubeconfigSecret, or ExternalSecret declares it
Secret "shop-secrets" mounted by "api" — no rendered Secret, KubeconfigSecret, or ExternalSecret declares it
The preflight refuses an undeclared Secret even when it exists. Declare it in
required_secrets (step 1).secret_provider = forge.FileSecrets renders PLAINTEXT secrets, so it needs a local env
secret_provider = forge.FileSecrets renders PLAINTEXT secrets, so it needs a local env
Dev’s file-backed secrets are refused for a cluster forge did not create. Create the Secret and declare it in
required_secrets.direct apply to it will be refused once F-REFUSE-DIRECT lands
direct apply to it will be refused once F-REFUSE-DIRECT lands
Declare
applier = "forge" (direct apply) or applier = "flux".Pods stay in ImagePullBackOff
Pods stay in ImagePullBackOff
_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.