Crate kube

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:

• client with the Kubernetes Client and its layers
• config for cluster Config
• api with the generic Kubernetes Api
• derive with the CustomResource / Resource derive for building controllers types
• runtime with a Controller / watcher / reflector / Store
• core with generics from apimachinery

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_any());
    }
    Ok(())
}

For details, see:

• Client for the extensible Kubernetes client
• Api for 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 futures::{StreamExt, TryStreamExt};
use k8s_openapi::apiextensions_apiserver::pkg::apis::apiextensions::v1::CustomResourceDefinition;
use kube::{
    api::{Api, DeleteParams, PatchParams, Patch, ResourceExt},
    core::CustomResourceExt,
    Client, CustomResource,
    runtime::{watcher, WatchStreamExt, wait::{conditions, await_condition}},
};

// Our custom resource
#[derive(CustomResource, Deserialize, Serialize, Clone, Debug, JsonSchema)]
#[kube(group = "clux.dev", version = "v1", kind = "Foo", namespaced)]
pub struct FooSpec {
    info: String,
    #[schemars(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 wc = watcher::Config::default();
    let mut apply_stream = watcher(foos, wc).applied_objects().boxed();
    while let Some(f) = apply_stream.try_next().await? {
        println!("saw apply to {}", f.name_any());
    }
    Ok(())
}

For details, see:

• CustomResource for documentation how to configure custom resources
• runtime::watcher for how to long-running watches work and why you want to use this over Api::watch
• runtime for 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

apiclient

API helpers for structured interaction with the Kubernetes API

clientclient

API client for interacting with the Kubernetes API

configconfig

Kubernetes configuration objects.

core

Types and traits necessary for interacting with the Kubernetes API

discoveryclient

High-level utilities for runtime API discovery.

errorconfig or client

Error handling and error types

prelude

A prelude for kube. Reduces the number of duplicated imports.

runtimeruntime

Common components for building Kubernetes operators

Structs

Apiclient

The generic Api abstraction

Clientclient

Client for connecting with a Kubernetes cluster.

Configconfig

Configuration object for accessing a Kuernetes cluster

Discoveryclient

A caching client for running API discovery against the Kubernetes API.

Enums

Errorconfig or client

Possible errors from the Client

Traits

CustomResourceExt

Extension trait that is implemented by kube-derive

Resource

An accessor trait for a kubernetes Resource.

ResourceExt

Helper methods for resources.

Type Aliases

Resultconfig or client

Convient alias for Result<T, Error>

Derive Macros

CELSchemaderive

Generates a JsonSchema implementation a set of CEL validation rules applied on the CRD.

CustomResourcederive

A custom derive for kubernetes custom resource definitions.

Resourcederive

A custom derive for inheriting Resource impl for the type.