> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy a Forge app to your own Kubernetes cluster

> Bind a Forge environment to a Kubernetes cluster you run, deploy a release to it with forge env deploy, and optionally hand delivery to an in-cluster Flux.

You will run the `shop` API from [Build a Go and React app](https://docs.reliantlabs.io/guides/forge/build-go-react-app-connect-rpc.md) 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](https://docs.reliantlabs.io/guides/hosting/deploy-go-api-managed-postgres.md) 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](https://docs.reliantlabs.io/guides/forge/build-go-react-app-connect-rpc.md), 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.

> [!TIP]
>
> 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:
>
> ```bash terminal theme={null}
> k3d cluster create guides-sandbox-k3d \
>   --registry-create k3d-guides-sandbox-registry:0.0.0.0:5051 \
>   --registry-config registries.yaml --kubeconfig-switch-context=false
> ```
>
> ```yaml registries.yaml theme={null}
> mirrors:
>   "localhost:5051":
>     endpoint:
>       - http://k3d-guides-sandbox-registry:5000
> ```

**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`:

```bash terminal theme={null}
reliant forge env new k8s --from prod --bind api=cluster --bind migrate=cluster
reliant forge generate
```

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

```kcl deploy/kcl/k8s/main.k theme={null}
import forge
import forge.workloads as fw

import ..workloads as wl
import ..base.env as envbase
import config_gen
import .config as appcfg

# The cluster: its kubectl context and the namespace this env owns.
_cluster = forge.ClusterTarget {
    cluster = "k3d-guides-sandbox-k3d"
    namespace = "shop-k8s"
    platform = "amd64"
}

# Where the image is pushed and pulled. A cluster workload names its registry.
_image = "localhost:5051/shop"

_cluster_resources = fw.Resources {
    cpuRequestMillicores = forge.cpu(0.25)
    memoryRequestBytes = forge.mib(256)
    cpuLimitMillicores = forge.cpu(1.0)
    memoryLimitBytes = forge.mib(512)
}
_cluster_replicas = 1
_on_cluster = lambda w: fw.Workload -> fw.Workload {
    envbase.on_cluster(w | {image = _image}, appcfg.app_config, _cluster, "k8s", _cluster_resources, _cluster_replicas)
}

_api = fw.Workload {
    name = "api"
    kind = "service"
    image = _image
    build = forge.GoBuild {cmd = "./cmd/shop", output_name = "shop"}
    args = ["server"]
    root = "server"
    ports = [fw.Port {name = "http", port = 8080, expose = True}]
    config_secrets = ["DATABASE_URL"]
}

_workloads = [
    _on_cluster(wl.migrate)
    _on_cluster(_api)
]

_bundle = forge.Bundle {
    project = "shop"
    env = "k8s"
    cluster_target = _cluster
    # forge applies this env from the machine that deploys it.
    applier = "forge"
    workloads = _workloads
    # The database URL is a Secret you create; forge checks it exists before
    # it applies anything, and never sees its value.
    required_secrets = [forge.ExternalSecret {
        name = "shop-secrets"
        namespace = _cluster.namespace
        keys = ["database_url"]
        reason = "the Postgres the API and the migration connect to"
    }]
}

output = forge.render(_bundle)
```

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**

```bash terminal theme={null}
reliant forge env render k8s --list
```

```text Output theme={null}
CLUSTER                 KIND            NAMESPACE  NAME      APP
k3d-guides-sandbox-k3d  Namespace       -          shop-k8s  -
k3d-guides-sandbox-k3d  Deployment      shop-k8s   api       api
k3d-guides-sandbox-k3d  Service         shop-k8s   api       api
k3d-guides-sandbox-k3d  ServiceAccount  shop-k8s   api       api
```

The migration is an init container in every API pod, so no pod serves an old schema. [What gets deployed](https://docs.reliantlabs.io/forge/deploy/what-gets-deployed.md#on-a-cluster-you-operate) 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:

```bash terminal theme={null}
kubectl --context k3d-guides-sandbox-k3d create namespace shop-k8s
kubectl --context k3d-guides-sandbox-k3d -n shop-k8s create secret generic shop-secrets \
  --from-literal=database_url='postgres://postgres:<password>@host.k3d.internal:15432/shop?sslmode=disable'
```

The deploy's preflight checks that the declared key exists before it applies anything.

**4. Deploy**

```bash terminal theme={null}
reliant forge env deploy k8s --yes
```

With no version it builds and pushes the image, cuts a release, plans and applies; `--yes` approves the plan. It took 90 seconds:

```text Output (trimmed) theme={null}
[deploy] cutting new release 20261120.110945-8aa85e8e97a3 because no release in /home/workspace/.forge/ledger/shop records this checkout's tree (8aa85e8e97a3)
[build] shop: docker push localhost:5051/shop:20261120.110945-8aa85e8e97a3
[build] Cut release 20261120.110945-8aa85e8e97a3 (1 image(s), 0 package(s), 0 file(s)): localhost:5051/shop
PLAN (approved — recording and publishing follow): promote env "k8s" → release 20261120.110945-8aa85e8e97a3
  direction INITIAL  FIRST PROMOTE — this environment has never been bound to a release, so there is nothing to move from
Applying k8s's newly recorded release (self-managed: no control plane converges it)
External prerequisites this env depends on (provisioned out-of-band; forge does NOT create them):
  - Secret shop-k8s/shop-secrets keys=[database_url] — the Postgres the API and the migration connect to
deployment.apps/api serverside-applied
deployment "api" successfully rolled out
Promoted env "k8s" → release 20261120.110945-8aa85e8e97a3
  shipped   [k8s-cluster] cluster=k3d-guides-sandbox-k3d ns=shop-k8s: migrate, api
```

It waits for every Deployment to become ready and exits non-zero if one does not. See [Releases and promotion](https://docs.reliantlabs.io/forge/deploy/releases-and-promotion.md).

**5. Verify it works**

```bash terminal theme={null}
kubectl --context k3d-guides-sandbox-k3d -n shop-k8s get pods
kubectl --context k3d-guides-sandbox-k3d -n shop-k8s logs deploy/api -c migrate --tail=1
kubectl --context k3d-guides-sandbox-k3d -n shop-k8s port-forward svc/api 18481:8080
```

In a second terminal:

```bash terminal theme={null}
curl -s localhost:18481/readyz
curl -s -X POST -H 'Content-Type: application/json' -d '{}' \
  localhost:18481/services.catalog.v1.CatalogService/ListProducts
```

```text Output theme={null}
NAME                  READY   STATUS    RESTARTS   AGE
api-8b45f4bdd-q4b5z   1/1     Running   0          19s
migrations applied: 0 -> 20261120063248
{"status":"ready","checks":[{"name":"db","ok":true},{"name":"api_listener","ok":true}]}
{"code":"unauthenticated","message":"missing Authorization header (procedure is not on the unauthenticated allow-list)"}
```

`readyz` reports the database connection; the RPC refuses an unsigned caller because authentication is fail-closed. Then compare the running digests with the release:

```bash terminal theme={null}
reliant forge env status k8s
```

```text Output (trimmed) theme={null}
  ✓ Cluster Workloads    1 workload(s), 1 pod(s) Ready — k3d-guides-sandbox-k3d/shop-k8s
Verifying environment k8s against release 20261120.110945-8aa85e8e97a3 (1 image(s))
  apply    SUCCEEDED (reported by forge)
  MATCH        localhost:5051/shop
1 match, 0 drifted, 0 missing, 0 untagged, 0 unreachable
  convergence   no reconciler for this env
```

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:

```bash terminal theme={null}
reliant forge env deploy k8s --target flux-delivery --yes
reliant forge env deploy k8s --yes
```

```text Output (trimmed) theme={null}
Env k8s's Flux is installed and its delivery ResourceSet forge-delivery-shop-k8s/delivery.k8s is waiting for its first release.

Pushing release 20261120.111239-3a175ffa7922's bundle sha256:4f5bfc625850 to localhost:5051/bundle.v1/k8s
Pointing env k8s's in-cluster Flux at release 20261120.111239-3a175ffa7922 (bundle sha256:4f5bfc625850, forge-delivery-shop-k8s/delivery.k8s)
  converged: 2/2 Kustomizations applied sha256:4f5bfc625850 in 20s
Promoted env "k8s": 20261120.110945-8aa85e8e97a3 → 20261120.111239-3a175ffa7922
  Shipped:  nothing from this machine — k8s's in-cluster Flux applies bundle sha256:4f5bfc625850, which this deploy pointed it at.
```

`env status` then names the Flux as the reconciler. Grants, pull secrets and exit 9: [Self-hosted delivery](https://docs.reliantlabs.io/forge/deploy/self-hosted-delivery.md).

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

```bash terminal theme={null}
k3d cluster delete guides-sandbox-k3d
```

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](https://docs.reliantlabs.io/guides/hosting/recover-from-bad-deploy.md)).
* 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](https://docs.reliantlabs.io/forge/deploy/what-gets-deployed.md#a-database-on-your-cluster)).
* 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](https://docs.reliantlabs.io/forge/deploy/environments.md)) or ship it elsewhere.

## Troubleshooting

> [accordion] 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).

> [accordion] 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`.

> [accordion] direct apply to it will be refused once F-REFUSE-DIRECT lands
>
> Declare `applier = "forge"` (direct apply) or `applier = "flux"`.

> [accordion] 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

> [card] [Self-hosted delivery](https://docs.reliantlabs.io/forge/deploy/self-hosted-delivery.md)
>
> Direct apply or an in-cluster Flux: grants, pull secrets, exit 9 and tuning.

> [card] [Promote to production](https://docs.reliantlabs.io/guides/hosting/promote-release-staging-to-production.md)
>
> Deploy the same release to a second environment by digest.

> [card] [Add a worker or cron job](https://docs.reliantlabs.io/guides/forge/background-worker-cron-job.md)
>
> Scaffold a cron worker, or a `kind = "cron"` workload for your cluster.

> [card] [Environments](https://docs.reliantlabs.io/forge/deploy/environments.md)
>
> Runtimes, binders and connecting a cluster to a hosted environment.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.