Skip to main content
The Kubernetes rules follow the same split as container pushes: the build is pure — manifests render into .rbs/bin/ — and the apply is a deliberate run-time side effect:
There is no rbs deploy subcommand; deploying is running a deploy target. Two rules cover the surface:
  • k8s_workload — a typed wrapper that generates correct YAML for the common shapes: Deployment + Service, StatefulSet + volume claims + headless Service, a Secret populated from your environment, and an Ingress.
  • k8s_deploy — the underlying rule: hand-written manifest templates with ${VAR} substitution. Anything beyond the wrapper’s shapes belongs here.

Declaring a workload

k8s_workload generates the YAML and declares a k8s_deploy target named <name>_deploy carrying it:
A stateful example — a database with persistent storage:

k8s_workload parameters

The wrapper is deliberately small: kinds beyond deployment/statefulset, extra pod settings, network policies, or multi-path ingresses belong in hand-written YAML passed to k8s_deploy — not in more wrapper options.

Hand-written manifests with k8s_deploy

When you need full control, write the YAML yourself and declare it:
In the YAML, reference the image by its placeholder:
At least one of manifests or manifest_content must be non-empty.

The substitution model

Placeholders are ${VAR}, resolved in two phases:
  1. Build time — substitutions (static strings) render into the output manifests under .rbs/bin/. Anything unresolved stays as-is.
  2. Deploy time — images (push targets or literal refs), uses (exported values of applied infra resources), and env (names read from the deploying shell). Substituted manifests are piped to kubectl on stdin, never written to disk — which is exactly why secrets flow through env.
Substitution is one pass with no nesting, and a placeholder still unresolved at apply time fails loudly, naming the manifest and the placeholders. Manifests apply in sorted filename order. k8s_workload prefixes its generated files (00-secret, 05-pvc-*, 10-deployment, 20-service, 30-ingress) so Secrets land before the pods that mount them — name hand-written files the same way when ordering matters.
Image references that point at an oci_push target resolve through the same repository resolution the push itself uses (explicit repository, or infra state via uses). Push and deploy therefore cannot disagree about which registry an image lives in.

Owned test environments

A test fixture often goes into a cluster where other work also lives, such as a local Kind cluster beside your development one. A wrong context or a reused namespace would then touch someone else’s resources. These attributes check the selected context and recorded namespace ownership. Use a dedicated fixture context; the remaining race with other writers is described below.
  • strict_context applies to exactly context. An override that names another context fails before kubectl runs; it never redirects the deploy.
  • require_new_namespace makes the namespace the deploy’s own. Apply runs kubectl create on it, so a namespace that already exists is refused in the same call. It labels the namespace with a run id and records its UID under .rbs/k8s-deploy/, and only then applies the manifests. Every apply creates a new namespace: if this workspace already has a record for it, apply is refused (“delete it first, or deploy with a new run id”).
  • If namespace creation may have succeeded but cannot be confirmed, no workload manifests are applied. rbs keeps the run-scoped record so a later delete can reconcile it; apply does not resume or adopt it.
  • Delete (RBS_K8S_ACTION=delete) needs this workspace’s record for the namespace. When the record holds the namespace’s UID, the live namespace must still have that UID and the run label; a different UID is refused. When the creation was never confirmed, the record has no UID yet: the live namespace must carry the record’s run label, and its current UID is used. Either way rbs deletes only the namespace, with a server-side UID precondition, and everything inside goes with it. A namespace that is already gone just has its record removed.
  • What the manifests may contain. The manifests are parsed, and only namespaced built-in kinds in that namespace are accepted. A Namespace object, a cluster-scoped kind or a custom resource is refused before anything runs. Put the namespace’s labels in namespace_labels.
  • owned_by lets another target apply into a namespace an owning target created. It applies only while the owner’s record names this context and namespace and the live namespace still has the recorded UID and run label. It never creates or deletes the namespace: a mistyped run id is refused, not created, and a delete through it is refused with the owning target to use instead.
  • One at a time. Each apply or delete of one owned namespace, including owned_by applies into it, holds a lock, and a second one is refused rather than queued. The record lives in the workspace that created the namespace, so only that workspace’s owning target can delete it.
An owned deploy is meant for a dedicated fixture context. Nothing on the rbs side stops another party from replacing a namespace between rbs reading it and applying to it.

How the apply actually runs

rbs run on a deploy target builds it (rendering manifests), resolves the deploy-time substitutions, then drives kubectl:
  • kubectl is hermetically pinned. rbs downloads its pinned kubectl release on first deploy and verifies it against the SHA-256 Kubernetes publishes. PATH is never consulted — whatever kubectl a machine happens to have is exactly the non-hermeticity the pin removes. No kubectl installation is a prerequisite.
  • KUBECONFIG passes through untouched; the cluster you talk to is the one your kubeconfig selects.
  • RBS_KUBE_CONTEXT overrides the target’s context attribute per invocation.
  • RBS_K8S_ACTION=delete turns the run into kubectl delete (with --ignore-not-found), tearing down everything the target applied. Only apply and delete are accepted.
  • The target namespace is created idempotently before the apply.
  • RBS_KUBECTL is an explicit operator override (air-gapped mirrors, test shims). The executor logs loudly whenever it is in effect.

Pinning a kubectl version

rbs embeds a default kubectl version, so nothing is required for deploys to work. To pin a different release, register the toolchain in WORKSPACE.rbs:
Any release published on dl.k8s.io works; the download is verified against its published checksum.

A full deploy sequence

A realistic order for a stack of services (images first, then data layer, then services, then edge):
Tear any piece down with RBS_K8S_ACTION=delete rbs run //deploy:<target>. PersistentVolumeClaims survive deletion — remove them explicitly if you mean to lose the data.