.rbs/bin/ — and the apply is a deliberate
run-time side effect:
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:
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:
At least one of
manifests or manifest_content must be non-empty.
The substitution model
Placeholders are${VAR}, resolved in two phases:
- Build time —
substitutions(static strings) render into the output manifests under.rbs/bin/. Anything unresolved stays as-is. - Deploy time —
images(push targets or literal refs),uses(exported values of applied infra resources), andenv(names read from the deploying shell). Substituted manifests are piped to kubectl on stdin, never written to disk — which is exactly why secrets flow throughenv.
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_contextapplies to exactlycontext. An override that names another context fails before kubectl runs; it never redirects the deploy.require_new_namespacemakes the namespace the deploy’s own. Apply runskubectl createon 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_bylets 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_byapplies 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.
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.
PATHis never consulted — whatever kubectl a machine happens to have is exactly the non-hermeticity the pin removes. No kubectl installation is a prerequisite. KUBECONFIGpasses through untouched; the cluster you talk to is the one your kubeconfig selects.RBS_KUBE_CONTEXToverrides the target’scontextattribute per invocation.RBS_K8S_ACTION=deleteturns the run intokubectl delete(with--ignore-not-found), tearing down everything the target applied. Onlyapplyanddeleteare accepted.- The target
namespaceis created idempotently before the apply. RBS_KUBECTLis 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 inWORKSPACE.rbs:
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):RBS_K8S_ACTION=delete rbs run //deploy:<target>.
PersistentVolumeClaims survive deletion — remove them explicitly if you mean to
lose the data.