kube-rs

A Rust client for Kubernetes in the style of a more generic client-go, a runtime abstraction inspired by controller-runtime, and a derive macro for CRDs inspired by kubebuilder. Hosted by CNCF as a Sandbox Project.

These crates build upon Kubernetes apimachinery + api concepts to enable generic abstractions. These abstractions allow Rust reinterpretations of reflectors, controllers, and custom resource interfaces, so that you can write applications easily.

Select a version of kube along matching versions of k8s-openapi and schemars for Kubernetes structs and matching schemas. See also historical Kubernetes versions.

[dependencies]
kube = { version = "4.2.0", features = ["runtime", "derive"] }
k8s-openapi = { version = "0.28.0", features = ["latest", "schemars"] }
schemars = { version = "1" }

See features for a quick overview of default-enabled / opt-in functionality. You can remove schemars parts if you do not need the kube/derive feature.

See kube.rs/upgrading. Noteworthy changes are highlighted in releases, and archived in the changelog.

See the examples directory for how to use any of these crates.

• kube API Docs
• kube.rs

Official examples:

• version-rs: lightweight deployment reflector using axum
• controller-rs: Controller of a crd inside actix

For real world projects see ADOPTERS.

The Api is what interacts with Kubernetes resources, and is generic over Resource:

use k8s_openapi::api::core::v1::Pod;
let pods: Api<Pod> = Api::default_namespaced(client);

let pod = pods.get("blog").await?;
println!("Got pod: {pod:?}");

let patch = json!({"spec": {
    "activeDeadlineSeconds": 5
}});
let pp = PatchParams::apply("kube");
let patched = pods.patch("blog", &pp, &Patch::Apply(patch)).await?;
assert_eq!(patched.spec.active_deadline_seconds, Some(5));

pods.delete("blog", &DeleteParams::default()).await?;

See the examples ending in _api examples for more detail.

Working with custom resources uses automatic code-generation via proc_macros in kube-derive.

You need to add #[derive(CustomResource, JsonSchema)] and some #[kube(attrs..)] on a spec struct:

#[derive(CustomResource, Debug, Serialize, Deserialize, Default, Clone, JsonSchema)]
#[kube(group = "kube.rs", version = "v1", kind = "Document", namespaced)]
pub struct DocumentSpec {
    title: String,
    content: String,
}

Then you can use the generated wrapper struct Document as a kube::Resource:

let docs: Api<Document> = Api::default_namespaced(client);
let d = Document::new("guide", DocumentSpec::default());
println!("doc: {:?}", d);
println!("crd: {:?}", serde_saphyr::to_string(&Document::crd()));

There are a ton of kubebuilder-like instructions that you can annotate with here. See the documentation or the crd_ prefixed examples for more.

NB: #[derive(CustomResource)] requires the derive feature enabled on kube.

The runtime module exports the kube_runtime crate and contains higher level abstractions on top of the Api and Resource types so that you don't have to do all the watch/resourceVersion/storage book-keeping yourself.