kube-rs

The E2E suite contains two primary test applications:

1. boot: A simple executable that lists pods. It is used as a compilation target to verify that kube builds successfully with any k8s-openapi version feature selection greater than or equal to the project's MK8SV. It uses local authentication and is not dockerized.

2. job: An advanced containerized application functionally equivalent to the job_api example. It creates a no-op job, waits for completion, and then deletes it. It serves as a safety mechanism to verify that in-cluster authentication is functional and not hanging.

A reflector combines a watcher with a Store. It ensures the Store stays synchronized with the Kubernetes API. This allows you to query the current state of resources from a local reader while simultaneously listening to events via the writer.

let nodes: Api<Node> = Api::all(client);
let lp = Config::default().labels("kubernetes.io/arch=amd64");
let (reader, writer) = reflector::store();
let rf = reflector(writer, watcher(nodes, lp));

The watcher function provides a streaming interface that presents watcher::Events. It handles automatic relists and connection drops under the hood. You can use WatchStreamExt::applied_objects to get a stream of the actual objects that were applied.

let api = Api::<Pod>::default_namespaced(client);
let stream = watcher(api, Config::default()).default_backoff().applied_objects();

while let Some(event) = stream.try_next().await? {
    println!("Applied: {}", event.name_any());
}

Admission controllers are web servers that the API server communicates with. You do not strictly require a kube::Client unless you need to cross-reference data not present in the AdmissionRequest.

To run a local admission controller example, you must provide a private IP reachable by your cluster (e.g., k3d) via the ADMISSION_PRIVATE_IP environment variable and use appropriate certificates.

export ADMISSION_PRIVATE_IP=192.168.1.163
./admission_setup.sh
kubectl apply -f admission_crd.yaml
cargo run --example admission_controller

The kube-derive crate allows you to derive CustomResource for your types.

By default, it uses schemars to generate an OpenAPI v3 schema. If you opt out of the schema feature (using --no-default-features), you are responsible for providing a valid OpenAPI v3 schema, as the Kubernetes API server requires it for v1::CustomResourceDefinitions.

To use the #[derive(CustomResource)] macro, you must enable the derive feature in your kube dependency in Cargo.toml.

[dependencies]
kube = { version = "1.1.0", feature = ["derive"] }

The boot executable is used to ensure kube-rs builds correctly against various k8s-openapi version feature selections. To run these tests across all feature combinations using mink8s, use the following command:

just e2e-mink8s

To test the job application (which verifies in-cluster authentication and job lifecycle) locally, you must have a local Kubernetes cluster running. You can use just k3d to start a simple cluster. Once the cluster is running, you can execute the E2E tests for specific TLS implementations using the following commands:

just e2e-incluster openssl,latest
# OR
just e2e-incluster rustls,latest

A Controller is a high-level abstraction that uses a reflector and optional child watchers to schedule events through a reconciliation function. You define a reconcile function to handle resource changes and an error_policy to handle failures.

Controller::new(root_kind_api, Config::default())
    .owns(child_kind_api, Config::default())
    .run(reconcile, error_policy, context)
    .for_each(|res| async move {
        match res {
            Ok(o) => info!("reconciled {:?}", o),
            Err(e) => warn!("reconcile failed: {}", Report::from(e)),
        }
    })
    .await;

To use kube-rs, add it to your Cargo.toml along with matching versions of k8s-openapi and schemars to ensure Kubernetes structs and schemas are compatible. It is recommended to enable the runtime and derive features for full functionality.

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