rules_k8s

bazel_dep(name = "rules_k8s", version = "0.0.3")

//crd/          k8s_crd_library · the CRD toolchain · K8sCrdInfo
//crd/private/  driver/ (the go/packages driver) · gen/ (controller-tools, as a library)
//k8s/          k8s_object · k8s_bundle · k8s_validate · k8s_diff
//k8s/private/  bundle/ (the aggregator) · schemas.bzl (the aspect)
//validate/     the kubeconform toolchain · crd2jsonschema
//kubectl/      the kubectl toolchain (PATH default + escape hatch)
//oci/          k8s_operator_image (+ the platform transition)
//docs/         stardoc reference, generated + committed + gated
//examples/smoke/  the end-to-end proof

Go type + markers → controller-gen → operator/config/crd/*.yaml  (committed)
                                   → [ an unautomated human `cp` ]
                                   → helm/<chart>/crds/*.yaml    (committed, byte-duplicated)

load("@aspect_bazel_lib//lib:write_source_files.bzl", "write_source_files")
load("@rules_k8s//crd:defs.bzl", "k8s_crd_library")

k8s_crd_library(
    name = "crds",
    deps = ["//api/v1:v1"],          # a plain rules_go go_library
    group = "platform.example.com",  # verified against the output, so it can't rot
)

# `bazel run //crd:update` regenerates both trees; `bazel test` gates them.
write_source_files(
    name = "update",
    files = {
        "//operator/config/crd": ":crds",
        "//helm/my-operator/crds": ":crds",   # <- this line replaces the human `cp`
    },
)

// controller-tools/pkg/loader/loader.go
l.cfg.Mode |= packages.NeedName | packages.NeedFiles |
              packages.NeedCompiledGoFiles | packages.NeedImports | packages.NeedTypesSizes

common --registry=https://registry.fastverk.com/
common --registry=https://bcr.bazel.build/

# Register the CRD toolchain. This goes in .bazelrc and NOT MODULE.bazel:
# register_toolchains() propagates to every consumer, which would drag a Go SDK
# into the Rust services that only ever READ CRD schemas.
common --extra_toolchains=@rules_k8s//crd:default_k8s_crd_toolchain

bazel_dep(name = "rules_k8s", version = "0.0.2")

# Only repos that actually RUN controller-gen need these.
bazel_dep(name = "rules_go", version = "0.60.0")
bazel_dep(name = "gazelle", version = "0.51.0")

build:operator-image --platforms=@rules_go//go/toolchain:linux_amd64

k8s_operator_image(
    name = "my-operator-image",
    binary = "//operator/cmd:manager",
    repository = "ghcr.io/example/my-operator",
)

go run sigs.k8s.io/controller-tools/cmd/controller-gen@v0.16.5 \
  crd paths=./examples/smoke/api/v1/... output:crd:artifacts:config=/tmp/stockcrd
diff /tmp/stockcrd/smoke.rules-k8s.dev_widgets.yaml \
     bazel-bin/examples/smoke/crds/smoke.rules-k8s.dev_widgets.yaml

env PATH=<bazel-only-dir>:/usr/bin:/bin GOROOT=/nonexistent \
    GOMODCACHE=/nonexistent GOPROXY=off \
  bazel build //examples/smoke:crds --disk_cache= --spawn_strategy=sandboxed

Real usage, taken from the module’s examples/.

examples/smoke/BUILD.bazel

load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
load("@rules_shell//shell:sh_test.bzl", "sh_test")
load("//crd:defs.bzl", "k8s_crd_library")
load("//k8s:defs.bzl", "k8s_bundle", "k8s_validate")

# The end-to-end proof: kubebuilder markers -> CRD YAML, as a sandboxed action.
#
# `bazel build //examples/smoke:crds` must succeed with no Go on PATH, no module
# cache, and no network. If it ever needs any of those, the ruleset does not work
# and this target is how you find out.
#
# The API package deliberately exercises what a naive driver gets wrong:
# cross-package types (metav1.Condition), a stdlib-typed field (metav1.Time wraps
# time.Time — the aspect's Imports map omits stdlib edges), validation markers,
# and a nested struct.
k8s_crd_library(
    name = "crds",
    group = "smoke.rules-k8s.dev",
    visibility = ["//visibility:public"],
    deps = ["//examples/smoke/api/v1:v1"],
)

# THE test of this whole ruleset.
#
# `testdata/expected_widgets.yaml` is not our own output blessed into a file — it
# is the verbatim output of STOCK `controller-gen v0.16.5` over the same package
# (`go run sigs.k8s.io/controller-tools/cmd/controller-gen@v0.16.5 crd
# paths=./examples/smoke/api/v1/...`). So this asserts equivalence with upstream,
# not self-consistency.
#
# That matters because a fleet has its CRDs committed to git and rendered into
# charts that ArgoCD server-side-applies. If this rule's output drifted from
# stock by so much as a line, adopting it would rewrite every schema and push
# the rewrite live. It has already caught one real instance: a Bazel-built binary
# has no debug.ReadBuildInfo(), so controller-tools stamped
# `controller-gen.kubebuilder.io/version: (unknown)` until //crd/private/gen's
# x_defs supplied the version.
#
# Regenerate ONLY from stock controller-gen, never from this rule's own output.
diff_test(
    name = "crds_match_stock_controller_gen",
    file1 = "testdata/expected_widgets.yaml",
    file2 = ":widgets_yaml",
)

genrule(
    name = "widgets_yaml",
    srcs = [":crds"],
    outs = ["widgets_actual.yaml"],
    cmd = "cp $(location :crds)/smoke.rules-k8s.dev_widgets.yaml $@",
)

# The listing rides in an output group so a write_source_files over :crds copies
# only CRD YAML. Golden-testing it turns "a Kind silently vanished from the CRD
# set" into a legible one-line failure.
filegroup(
    name = "crds_listing",
    srcs = [":crds"],
    output_group = "listing",
)

diff_test(
    name = "crds_listing_test",
    file1 = ":crds_listing",
    file2 = "testdata/expected_listing.txt",
)

# ── the manifest half: bundle + validate ──────────────────────────────────────

k8s_bundle(
    name = "manifests",
    srcs = glob(["manifests/*.yaml"]),
    # `deps` contributes SCHEMAS, not manifests: the bundle holds the Widget,
    # and k8s_validate resolves its schema from the CRD without a hand-written list.
    deps = [":crds"],
)

# Proves the whole chain: Go markers -> CRD (hermetic action) -> JSON Schema ->
# kubeconform -> a CR checked against a schema generated in the same build. The
# ConfigMap alongside the Widget proves core and custom schemas resolve together.
k8s_validate(
    name = "manifests_valid",
    bundle = ":manifests",
    # block-network is the assertion, not a precaution: kubeconform's own
    # "default" schema location is a raw GitHub URL, so it would be very easy to
    # ship a validate that silently fetches schemas at build time and dies on
    # RBE. If this rule ever regains a network dep, this test fails here first.
    tags = ["block-network"],
)

filegroup(
    name = "manifests_listing",
    srcs = [":manifests"],
    output_group = "listing",
)

diff_test(
    name = "manifests_listing_test",
    file1 = ":manifests_listing",
    file2 = "testdata/expected_manifests_listing.txt",
)

# A validator that only ever passes is not a test. This bundle holds a Widget
# with replicas=1000 (marker says Maximum=99) and mode=Sideways (not in the
# Enum); //examples/smoke:validate_rejects_bad_test asserts k8s_validate FAILS on
# it. Not a k8s_validate target itself — it is expected to fail.
k8s_bundle(
    name = "badmanifests",
    srcs = glob(["badmanifests/*.yaml"]),
    deps = [":crds"],
)

k8s_validate(
    name = "badmanifests_valid",
    bundle = ":badmanifests",
    tags = ["manual"],
)

sh_test(
    name = "validate_rejects_bad_test",
    srcs = ["validate_rejects_bad.sh"],
    data = [":badmanifests_valid"],
    env = {"VALIDATOR": "$(rootpath :badmanifests_valid)"},
)

examples/smoke/cmd/BUILD.bazel

load("@rules_go//go:def.bzl", "go_binary", "go_library")
load("@rules_python//python:defs.bzl", "py_test")
load("//oci:defs.bzl", "k8s_operator_image")

# gazelle:ignore

go_library(
    name = "cmd_lib",
    srcs = ["main.go"],
    importpath = "github.com/tomato-bazel/rules_k8s/examples/smoke/cmd",
)

# A PLAIN go_binary. Note what is absent: no goos/goarch, no `pure = "on"`, no
# second cross-compiled target. The fleet's operators each declare a separate
# `manager_linux_amd64` go_binary beside the real one purely to feed the image;
# the transition makes that unnecessary.
go_binary(
    name = "manager",
    embed = [":cmd_lib"],
)

# THE SPIKE. This must build a linux/amd64 image on a macOS host with NO
# --platforms flag and NO --config, and `:operator-image_push` must ANALYZE —
# which real repos cannot do today, hence their crane bypass.
k8s_operator_image(
    name = "operator-image",
    binary = ":manager",
    repository = "example.com/smoke/operator",
    visibility = ["//visibility:public"],
)

# The regression guard. A transition that silently stops firing still builds and
# still pushes — it just ships a host-arch binary that cannot exec in the cluster.
# Nothing else in the build would catch that.
py_test(
    name = "image_is_linux_amd64_test",
    srcs = ["assert_image.py"],
    main = "assert_image.py",
    # The transitioned IMAGE, not the layer target: a direct dep on the layer
    # resolves in the default configuration and hands back a host-arch binary.
    data = [":operator-image"],
    env = {"LAYOUT": "$(rootpath :operator-image)"},
)

examples/smoke/api/v1/BUILD.bazel

load("@rules_go//go:def.bzl", "go_library")

# gazelle:ignore

go_library(
    name = "v1",
    srcs = ["widget_types.go"],
    importpath = "github.com/tomato-bazel/rules_k8s/examples/smoke/api/v1",
    visibility = ["//visibility:public"],
    deps = [
        "@io_k8s_apimachinery//pkg/apis/meta/v1:meta",
        "@io_k8s_apimachinery//pkg/runtime",
        "@io_k8s_apimachinery//pkg/runtime/schema",
    ],
)

from docs/crd_providers.md

Providers for the CRD half of rules_k8s.

K8sCrdInfo

load("@rules_k8s//crd:providers.bzl", "K8sCrdInfo")

K8sCrdInfo(crds, group)

CRD schemas generated from kubebuilder markers in a Go API package.

Carries the schemas as a directory rather than a file list because the set of Kinds is not knowable at analysis time — controller-tools discovers it by type-checking the package, inside the action. Consumers that need per-Kind facts read the listing output group, which the action writes.

FIELDS

Name	Description
crds	File: a TreeArtifact directory of CRD manifests, one <group>_<plural>.yaml per Kind.
group	str: the API group these CRDs are in, e.g. ‘platform.example.com’. Declared on the rule and verified against the generated output, so it cannot rot.

K8sTransitiveSchemasInfo

load("@rules_k8s//crd:providers.bzl", "K8sTransitiveSchemasInfo")

K8sTransitiveSchemasInfo(schemas)

Transitive set of CRD schemas, threaded by the _k8s_schemas aspect.

Exists so k8s_validate can resolve what to validate a manifest against instead of making every caller hand-list the CRDs — including reaching through intermediate targets that don’t themselves speak k8s (a filegroup, a genrule), which is the part plain provider-threading can’t do.

FIELDS

Name	Description
schemas	depset[K8sCrdInfo]: every CRD set reachable through deps.

from docs/crd_toolchains.md

The CRD codegen toolchain: controller-tools plus the driver that feeds it.

k8s_crd_toolchain

load("@rules_k8s//crd:toolchains.bzl", "k8s_crd_toolchain")

k8s_crd_toolchain(name, driver, gen)

Declares a CRD codegen toolchain.

The default implementation (@rules_k8s//crd:default_k8s_crd_toolchain) builds controller-tools from the version pinned in rules_k8s’s go.mod. That pin is a schema decision — see the comment there — so an override should be a deliberate “we generate with a different controller-tools”, not a convenience.

Register with --extra_toolchains in .bazelrc, never register_toolchains() in MODULE.bazel: the latter propagates to every consumer, which would drag a Go SDK into the Rust services that only ever read CRD schemas.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
driver	The go/packages external driver. Must read its package-graph file list from K8S_CRD_DRIVER_PKG_JSON.	Label	required
gen	The CRD generator binary. Must accept -out DIR [-expect-group G] [-listing F] PATTERN....	Label	required

K8sCrdToolchainInfo

load("@rules_k8s//crd:toolchains.bzl", "K8sCrdToolchainInfo")

K8sCrdToolchainInfo(gen, driver)

The tools that turn kubebuilder markers into CRD YAML inside an action.

FIELDS

Name	Description
gen	FilesToRunProvider: the CRD generator — controller-tools’ genall driven as a library, writing to a named directory.
driver	FilesToRunProvider: the go/packages external driver. gen reaches it via GOPACKAGESDRIVER; it is never invoked directly.

from docs/k8s_defs.md

Public API for the manifest half of rules_k8s.

load(“@rules_k8s//k8s:defs.bzl”, “k8s_bundle”, “k8s_validate”)

k8s_bundle

load("@rules_k8s//k8s:defs.bzl", "k8s_bundle")

k8s_bundle(name, deps, srcs)

Collect Kubernetes manifests into one conflict-checked directory.

Fails the build if two manifests declare the same group/Kind/namespace/name. That is the whole point over a filegroup: applying such a pair keeps whichever came last, and which that is depends on ordering. Note identity excludes the API VERSION — Foo/v1 and Foo/v1beta1 with the same name are the same object.

Manifests are placed, never rewritten: source bytes are copied verbatim, so key order and comments survive. A bundle that round-tripped YAML through a marshaller would silently rewrite the API surface it is supposed to be checking.

deps composes bundles without needing an aspect; the _k8s_schemas aspect is there to reach CRD schemas through targets that don’t speak k8s.

k8s_bundle(name = "apps", srcs = glob(["argocd/apps/*.yaml"]))
k8s_bundle(name = "fleet", deps = [":apps", "//op-a:bundle"])

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	Other bundles, k8s_object targets, k8s_crd_library targets, or plain file-providing targets.	List of labels	optional	[]
srcs	Manifest files to include directly.	List of labels	optional	[]

k8s_diff

load("@rules_k8s//k8s:defs.bzl", "k8s_diff")

k8s_diff(name, bundle)

bazel run to diff a bundle against the live cluster. Read-only.

bazel run //argocd:apps_diff -- --context=my-cluster

Extra arguments after -- pass through to kubectl diff. Exits non-zero when there is a difference, which is kubectl’s own convention.

Uses whatever kubectl is on your PATH — see //kubectl/toolchains.bzl for why pinning one would be wrong.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
bundle	The k8s_bundle to compare against the cluster.	Label	required

k8s_object

load("@rules_k8s//k8s:defs.bzl", "k8s_object")

k8s_object(name, srcs, expect_api_version, expect_kind)

Adopt checked-in Kubernetes manifests into the build graph.

No codegen and no rewriting — it types the graph so k8s_bundle and k8s_validate can consume the files, and optionally asserts that a manifest is what the BUILD file says it is.

Reach for k8s_bundle(srcs = ...) directly unless you want the assertion; this rule earns its place when a manifest’s identity is load-bearing elsewhere.

k8s_object(
    name = "myresource",
    srcs = ["myresource.yaml"],
    expect_kind = "MyResource",
    expect_api_version = "platform.example.com/v1",
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
srcs	Manifest files. Each may hold multiple documents.	List of labels	required
expect_api_version	If set, every object in srcs must be this apiVersion, or the build fails.	String	optional	""
expect_kind	If set, every object in srcs must be this Kind, or the build fails.	String	optional	""

K8sBundleInfo

load("@rules_k8s//k8s:defs.bzl", "K8sBundleInfo")

K8sBundleInfo(dir, files)

A collected, conflict-checked set of Kubernetes objects.

FIELDS

Name	Description
dir	File: TreeArtifact of the manifests, one file per object, named from its identity.
files	depset[File]: the source manifests that composed it.

K8sObjectInfo

load("@rules_k8s//k8s:defs.bzl", "K8sObjectInfo")

K8sObjectInfo(files)

Kubernetes manifests contributed by a target.

Carries files and nothing else. Identity (group/version/kind, name, namespace) is resolved by the bundle ACTION, not here — Starlark cannot read files, so a rule that adopts a checked-in manifest has no way to know its Kind at analysis time. Duplicate detection and the listing therefore live in the tool. (rules_cloudformation’s stack aggregator makes the same trade for the same reason: it can’t load many hundreds of per-kind providers, so it reads the shards.)

FIELDS

Name	Description
files	depset[File]: manifest YAMLs. Each may hold multiple documents.

k8s_validate

load("@rules_k8s//k8s:defs.bzl", "k8s_validate")

k8s_validate(name, **kwargs)

Validate a k8s_bundle against its CRD schemas. See _k8s_validate_test.

A macro only because Bazel requires test rule classes to end in _test.

PARAMETERS

Name	Description	Default Value
name	-	none
kwargs	-	none

k8s_schemas_aspect

load("@rules_k8s//k8s:defs.bzl", "k8s_schemas_aspect")

k8s_schemas_aspect()

Collect K8sCrdInfo from a target and everything reachable via deps/srcs.

Exists so k8s_validate resolves its own schemas instead of making callers hand-list every CRD set a bundle might contain:

k8s_bundle(name = "fleet", deps = ["//op-a:bundle", "//op-b:bundle"])
k8s_validate(name = "fleet_valid", bundle = ":fleet")   # finds both operators' CRDs

Plain provider-threading would cover that much. What needs an aspect is reaching THROUGH a target that doesn’t speak k8s at all — a filegroup or genrule wrapping several k8s_crd_library targets. Those return neither of our providers, so nothing would propagate; an aspect visits them anyway.

srcs is walked as well as deps because a filegroup carries its contents there.

ASPECT ATTRIBUTES

Name	Type
deps	String
srcs	String

ATTRIBUTES