Expand description
Kube is an umbrella-crate for interacting with Kubernetes in Rust.
Overview
Kube contains a Kubernetes client, a controller runtime, a custom resource derive, and various tooling required for building applications or controllers that interact with Kubernetes.
The main modules are:
clientwith the KubernetesClientand its layersconfigfor clusterConfigapiwith the generic KubernetesApiderivewith theCustomResourcederive for building controllers typesruntimewith aController/watcher/reflector/Storecorewith generics fromapimachinery
You can use each of these as you need with the help of the exported features.
Using the Client
use futures::{StreamExt, TryStreamExt};
use kube::{Client, api::{Api, ResourceExt, ListParams, PostParams}};
use k8s_openapi::api::core::v1::Pod;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Infer the runtime environment and try to create a Kubernetes Client
let client = Client::try_default().await?;
// Read pods in the configured namespace into the typed interface from k8s-openapi
let pods: Api<Pod> = Api::default_namespaced(client);
for p in pods.list(&ListParams::default()).await? {
println!("found pod {}", p.name());
}
Ok(())
}For details, see:
Clientfor the extensible Kubernetes clientApifor the generic api methods available on Kubernetes resources- k8s-openapi for documentation about the generated Kubernetes types
Using the Runtime with the Derive macro
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use serde_json::json;
use validator::Validate;
use futures::{StreamExt, TryStreamExt};
use k8s_openapi::apiextensions_apiserver::pkg::apis::apiextensions::v1::CustomResourceDefinition;
use kube::{
api::{Api, DeleteParams, ListParams, PatchParams, Patch, ResourceExt},
core::CustomResourceExt,
Client, CustomResource,
runtime::{watcher, utils::try_flatten_applied, wait::{conditions, await_condition}},
};
// Our custom resource
#[derive(CustomResource, Deserialize, Serialize, Clone, Debug, Validate, JsonSchema)]
#[kube(group = "clux.dev", version = "v1", kind = "Foo", namespaced)]
pub struct FooSpec {
info: String,
#[validate(length(min = 3))]
name: String,
replicas: i32,
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::try_default().await?;
let crds: Api<CustomResourceDefinition> = Api::all(client.clone());
// Apply the CRD so users can create Foo instances in Kubernetes
crds.patch("foos.clux.dev",
&PatchParams::apply("my_manager"),
&Patch::Apply(Foo::crd())
).await?;
// Wait for the CRD to be ready
tokio::time::timeout(
std::time::Duration::from_secs(10),
await_condition(crds, "foos.clux.dev", conditions::is_crd_established())
).await?;
// Watch for changes to foos in the configured namespace
let foos: Api<Foo> = Api::default_namespaced(client.clone());
let lp = ListParams::default();
let mut apply_stream = try_flatten_applied(watcher(foos, lp)).boxed();
while let Some(f) = apply_stream.try_next().await? {
println!("saw apply to {}", f.name());
}
Ok(())
}For details, see:
CustomResourcefor documentation how to configure custom resourcesruntime::watcherfor how to long-running watches work and why you want to use this overApi::watchruntimefor abstractions that help with more complicated Kubernetes application
Examples
A large list of complete, runnable examples with explainations are available in the examples folder.
Modules
clientAPI helpers for structured interaction with the Kubernetes API
clientA basic API client for interacting with the Kubernetes API
configKubernetes configuration objects from ~/.kube/config, $KUBECONFIG, or the cluster environment.
Re-exports from kube_core
Crate with types and traits necessary for interacting with the Kubernetes API
clientHigh-level utilities for runtime API discovery.
runtimeRe-exports from kube-runtime
Common components for building Kubernetes operators
Structs
clientThe generic Api abstraction
clientClient for connecting with a Kubernetes cluster.
configConfiguration object detailing things like cluster URL, default namespace, root certificates, and timeouts.
clientA caching client for running API discovery against the Kubernetes API.
Enums
Traits
Extension trait that is implemented by kube-derive
An accessor trait for a kubernetes Resource.
Helper methods for resources.
Type Definitions
config or clientConvient alias for Result<T, Error>
Derive Macros
deriveRe-exports from kube-derive
A custom derive for kubernetes custom resource definitions.