pub struct Api<K> { /* private fields */ }
Expand description

The generic Api abstraction

This abstracts over a Request and a type K so that we get automatic serialization/deserialization on the api calls implemented by the dynamic Resource.

Implementations

PUSH/PUT/POST/GET abstractions

Get a named resource

use kube::{Api, Client};
use k8s_openapi::api::core::v1::Pod;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::try_default().await?;
    let pods: Api<Pod> = Api::namespaced(client, "apps");
    let p: Pod = pods.get("blog").await?;
    Ok(())
}
Errors

This function assumes that the object is expected to always exist, and returns Error if it does not. Consider using Api::get_opt if you need to handle missing objects.

Get a named resource if it exists, returns None if it doesn’t exist

use kube::{Api, Client};
use k8s_openapi::api::core::v1::Pod;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::try_default().await?;
    let pods: Api<Pod> = Api::namespaced(client, "apps");
    if let Some(pod) = pods.get_opt("blog").await? {
        // Pod was found
    } else {
        // Pod was not found
    }
    Ok(())
}

Get a list of resources

You get use this to get everything, or a subset matching fields/labels, say:

use kube::{api::{Api, ListParams, ResourceExt}, Client};
use k8s_openapi::api::core::v1::Pod;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::try_default().await?;
    let pods: Api<Pod> = Api::namespaced(client, "apps");
    let lp = ListParams::default().labels("app=blog"); // for this app only
    for p in pods.list(&lp).await? {
        println!("Found Pod: {}", p.name());
    }
    Ok(())
}

Create a resource

This function requires a type that Serializes to K, which can be:

  1. Raw string YAML
    • easy to port from existing files
    • error prone (run-time errors on typos due to failed serialize attempts)
    • very error prone (can write invalid YAML)
  2. An instance of the struct itself
    • easy to instantiate for CRDs (you define the struct)
    • dense to instantiate for k8s_openapi types (due to many optionals)
    • compile-time safety
    • but still possible to write invalid native types (validation at apiserver)
  3. serde_json::json! macro instantiated serde_json::Value
    • Tradeoff between the two
    • Easy partially filling of native k8s_openapi types (most fields optional)
    • Partial safety against runtime errors (at least you must write valid JSON)

Delete a named resource

When you get a K via Left, your delete has started. When you get a Status via Right, this should be a a 2XX style confirmation that the object being gone.

4XX and 5XX status types are returned as an Err(kube_client::Error::Api).

use kube::{api::{Api, DeleteParams}, Client};
use k8s_openapi::apiextensions_apiserver::pkg::apis::apiextensions::v1 as apiexts;
use apiexts::CustomResourceDefinition;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::try_default().await?;
    let crds: Api<CustomResourceDefinition> = Api::all(client);
    crds.delete("foos.clux.dev", &DeleteParams::default()).await?
        .map_left(|o| println!("Deleting CRD: {:?}", o.status))
        .map_right(|s| println!("Deleted CRD: {:?}", s));
    Ok(())
}

Delete a collection of resources

When you get an ObjectList<K> via Left, your delete has started. When you get a Status via Right, this should be a a 2XX style confirmation that the object being gone.

4XX and 5XX status types are returned as an Err(kube_client::Error::Api).

use kube::{api::{Api, DeleteParams, ListParams, ResourceExt}, Client};
use k8s_openapi::api::core::v1::Pod;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::try_default().await?;
    let pods: Api<Pod> = Api::namespaced(client, "apps");
    match pods.delete_collection(&DeleteParams::default(), &ListParams::default()).await? {
        either::Left(list) => {
            let names: Vec<_> = list.iter().map(ResourceExt::name).collect();
            println!("Deleting collection of pods: {:?}", names);
        },
        either::Right(status) => {
            println!("Deleted collection of pods: status={:?}", status);
        }
    }
    Ok(())
}

Patch a subset of a resource’s properties

Takes a Patch along with PatchParams for the call.

use kube::{api::{Api, PatchParams, Patch, Resource}, Client};
use k8s_openapi::api::core::v1::Pod;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::try_default().await?;
    let pods: Api<Pod> = Api::namespaced(client, "apps");
    let patch = serde_json::json!({
        "apiVersion": "v1",
        "kind": "Pod",
        "metadata": {
            "name": "blog"
        },
        "spec": {
            "activeDeadlineSeconds": 5
        }
    });
    let params = PatchParams::apply("myapp");
    let patch = Patch::Apply(&patch);
    let o_patched = pods.patch("blog", &params, &patch).await?;
    Ok(())
}

Replace a resource entirely with a new one

This is used just like Api::create, but with one additional instruction: You must set metadata.resourceVersion in the provided data because k8s will not accept an update unless you actually knew what the last version was.

Thus, to use this function, you need to do a get then a replace with its result.

use kube::{api::{Api, PostParams, ResourceExt}, Client};
use k8s_openapi::api::batch::v1::Job;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::try_default().await?;
    let jobs: Api<Job> = Api::namespaced(client, "apps");
    let j = jobs.get("baz").await?;
    let j_new: Job = serde_json::from_value(serde_json::json!({
        "apiVersion": "batch/v1",
        "kind": "Job",
        "metadata": {
            "name": "baz",
            "resourceVersion": j.resource_version(),
        },
        "spec": {
            "template": {
                "metadata": {
                    "name": "empty-job-pod"
                },
                "spec": {
                    "containers": [{
                        "name": "empty",
                        "image": "alpine:latest"
                    }],
                    "restartPolicy": "Never",
                }
            }
        }
    }))?;
    jobs.replace("baz", &PostParams::default(), &j_new).await?;
    Ok(())
}

Consider mutating the result of api.get rather than recreating it.

Watch a list of resources

This returns a future that awaits the initial response, then you can stream the remaining buffered WatchEvent objects.

Note that a watch call can terminate for many reasons (even before the specified ListParams::timeout is triggered), and will have to be re-issued with the last seen resource version when or if it closes.

Consider using a managed watcher to deal with automatic re-watches and error cases.

use kube::{api::{Api, ListParams, ResourceExt, WatchEvent}, Client};
use k8s_openapi::api::batch::v1::Job;
use futures::{StreamExt, TryStreamExt};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::try_default().await?;
    let jobs: Api<Job> = Api::namespaced(client, "apps");
    let lp = ListParams::default()
        .fields("metadata.name=my_job")
        .timeout(20); // upper bound of how long we watch for
    let mut stream = jobs.watch(&lp, "0").await?.boxed();
    while let Some(status) = stream.try_next().await? {
        match status {
            WatchEvent::Added(s) => println!("Added {}", s.name()),
            WatchEvent::Modified(s) => println!("Modified: {}", s.name()),
            WatchEvent::Deleted(s) => println!("Deleted {}", s.name()),
            WatchEvent::Bookmark(s) => {},
            WatchEvent::Error(s) => println!("{}", s),
        }
    }
    Ok(())
}

Methods for scale subresource.

Fetch the scale subresource

Update the scale subresource

Replace the scale subresource

Arbitrary subresources

Display one or many sub-resources.

Patch an instance of the subresource

Replace an instance of the subresource

Methods for status subresource.

Get the named resource with a status subresource

This actually returns the whole K, with metadata, and spec.

Patch fields on the status object

NB: Requires that the resource has a status subresource.

use kube::{api::{Api, PatchParams, Patch}, Client};
use k8s_openapi::api::batch::v1::Job;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::try_default().await?;
    let jobs: Api<Job> = Api::namespaced(client, "apps");
    let mut j = jobs.get("baz").await?;
    let pp = PatchParams::default(); // json merge patch
    let data = serde_json::json!({
        "status": {
            "succeeded": 2
        }
    });
    let o = jobs.patch_status("baz", &pp, &Patch::Merge(data)).await?;
    assert_eq!(o.status.unwrap().succeeded, Some(2));
    Ok(())
}

Replace every field on the status object

This works similarly to the Api::replace method, but .spec is ignored. You can leave out the .spec entirely from the serialized output.

use kube::{api::{Api, PostParams}, Client};
use k8s_openapi::api::batch::v1::{Job, JobStatus};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::try_default().await?;
    let jobs: Api<Job> = Api::namespaced(client, "apps");
    let mut o = jobs.get_status("baz").await?; // retrieve partial object
    o.status = Some(JobStatus::default()); // update the job part
    let pp = PostParams::default();
    let o = jobs.replace_status("baz", &pp, serde_json::to_vec(&o)?).await?;
    Ok(())
}

Fetch logs as a string

Fetch logs as a stream of bytes

Create an eviction

Attach to pod

Execute a command in a pod

Forward ports of a pod

Partially update approval of the specified CertificateSigningRequest.

Get the CertificateSigningRequest. May differ from get(name)

Trigger a restart of a Resource.

Cordon a Node.

Uncordon a Node.

Gets a given object’s “slot” on the Kubernetes API, designed for “get-or-create” and “get-and-modify” patterns

This is similar to HashMap::entry, but the Entry must be OccupiedEntry::commited for changes to be persisted.

Usage
let kube = kube::Client::try_default().await?;
let cms = kube::Api::<ConfigMap>::namespaced(kube, "default");
cms
    // Try to get `entry-example` if it exists
    .entry("entry-example").await?
    // Modify object if it already exists
    .and_modify(|cm| {
        cm.data
            .get_or_insert_with(BTreeMap::default)
            .insert("already-exists".to_string(), "true".to_string());
    })
    // Provide a default object if it does not exist
    .or_insert(|| ConfigMap::default())
    // Modify the object unconditionally now that we have provided a default value
    .and_modify(|cm| {
        cm.data
            .get_or_insert_with(BTreeMap::default)
            .insert("modified".to_string(), "true".to_string());
    })
    // Save changes
    .commit(&kube::api::PostParams::default()).await?;

Api constructors for Resource implementors with custom DynamicTypes

This generally means resources created via DynamicObject.

Cluster level resources, or resources viewed across all namespaces

This function accepts K::DynamicType so it can be used with dynamic resources.

Namespaced resource within a given namespace

This function accepts K::DynamicType so it can be used with dynamic resources.

Namespaced resource within the default namespace

This function accepts K::DynamicType so it can be used with dynamic resources.

Unless configured explicitly, the default namespace is either “default” out of cluster, or the service account’s namespace in cluster.

Consume self and return the Client

Return a reference to the current resource url path

Api constructors for Resource implementors with Default DynamicTypes

This generally means structs implementing k8s_openapi::Resource.

Cluster level resources, or resources viewed across all namespaces

Namespaced resource within a given namespace

Namespaced resource within the default namespace

Unless configured explicitly, the default namespace is either “default” out of cluster, or the service account’s namespace in cluster.

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Converts to this type from the input type.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Should always be Self

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more