Struct kube::Api

pub struct Api<K> { /* fields omitted */ }

A generic Api abstraction

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

Implementations

impl<K> Api<K> where
    K: Resource, 

Expose same interface as Api for controlling scope/group/versions/ns

pub fn all(client: Client) -> Self

Cluster level resources, or resources viewed across all namespaces

pub fn namespaced(client: Client, ns: &str) -> Self

Namespaced resource within a given namespace

pub fn into_client(self) -> Client

Consume self and return the Client

impl<K> Api<K> where
    K: Clone + DeserializeOwned + Meta, 

PUSH/PUT/POST/GET abstractions

pub async fn get(&self, name: &str) -> Result<K>

Get a named resource

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

pub async fn list(&self, lp: &ListParams) -> Result<ObjectList<K>>

Get a list of resources

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

use kube::{api::{Api, ListParams, Meta}, Client};
use k8s_openapi::api::core::v1::Pod;
#[tokio::main]
async fn main() -> Result<(), kube::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: {}", Meta::name(&p));
    }
    Ok(())
}

pub async fn create(&self, pp: &PostParams, data: &K) -> Result<K> where
    K: Serialize, 

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)

pub async fn delete(
    &self,
    name: &str,
    dp: &DeleteParams
) -> Result<Either<K, Status>>

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::Error::Api).

use kube::{api::{Api, DeleteParams}, Client};
use k8s_openapi::apiextensions_apiserver::pkg::apis::apiextensions::v1beta1 as apiexts;
use apiexts::CustomResourceDefinition;
#[tokio::main]
async fn main() -> Result<(), kube::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(())
}

pub async fn delete_collection(
    &self,
    dp: &DeleteParams,
    lp: &ListParams
) -> Result<Either<ObjectList<K>, Status>>

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::Error::Api).

use kube::{api::{Api, DeleteParams, ListParams, Meta}, Client};
use k8s_openapi::api::core::v1::Pod;
#[tokio::main]
async fn main() -> Result<(), kube::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(Meta::name).collect();
            println!("Deleting collection of pods: {:?}", names);
        },
        either::Right(status) => {
            println!("Deleted collection of pods: status={:?}", status);
        }
    }
    Ok(())
}

pub async fn patch<P: Serialize>(
    &self,
    name: &str,
    pp: &PatchParams,
    patch: &Patch<P>
) -> Result<K>

Patch a resource a subset of its properties

Note that actual patch value depends on what PatchStrategy is used. It is configured in PatchParams and defauls to strategic merge patch.

See kubernetes json patch types for more information about their distinction.

use kube::{api::{Api, PatchParams, Patch, Meta}, Client};
use k8s_openapi::api::core::v1::Pod;
#[tokio::main]
async fn main() -> Result<(), kube::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(())
}

pub async fn replace(&self, name: &str, pp: &PostParams, data: &K) -> Result<K> where
    K: Serialize, 

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, Meta}, Client};
use k8s_openapi::api::batch::v1::Job;
#[tokio::main]
async fn main() -> Result<(), kube::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": Meta::resource_ver(&j),
        },
        "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.

pub async fn watch(
    &self,
    lp: &ListParams,
    version: &str
) -> Result<impl Stream<Item = Result<WatchEvent<K>>>>

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, Meta, WatchEvent}, Client};
use k8s_openapi::api::batch::v1::Job;
use futures::{StreamExt, TryStreamExt};
#[tokio::main]
async fn main() -> Result<(), kube::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 {}", Meta::name(&s)),
            WatchEvent::Modified(s) => println!("Modified: {}", Meta::name(&s)),
            WatchEvent::Deleted(s) => println!("Deleted {}", Meta::name(&s)),
            WatchEvent::Bookmark(s) => {},
            WatchEvent::Error(s) => println!("{}", s),
        }
    }
    Ok(())
}

impl<K> Api<K> where
    K: Clone + DeserializeOwned, 

Methods for scale subresource.

pub async fn get_scale(&self, name: &str) -> Result<Scale>

Fetch the scale subresource

pub async fn patch_scale<P: Serialize>(
    &self,
    name: &str,
    pp: &PatchParams,
    patch: &Patch<P>
) -> Result<Scale>

Update the scale subresource

pub async fn replace_scale(
    &self,
    name: &str,
    pp: &PostParams,
    data: Vec<u8>
) -> Result<Scale>

Replace the scale subresource

impl<K> Api<K> where
    K: Clone + DeserializeOwned, 

Methods for status subresource.

pub async fn get_status(&self, name: &str) -> Result<K>

Get the named resource with a status subresource

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

pub async fn patch_status<P: Serialize>(
    &self,
    name: &str,
    pp: &PatchParams,
    patch: &Patch<P>
) -> Result<K>

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<(), kube::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(())
}

pub async fn replace_status(
    &self,
    name: &str,
    pp: &PostParams,
    data: Vec<u8>
) -> Result<K>

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<(), kube::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(())
}

impl<K> Api<K> where
    K: Clone + DeserializeOwned + LoggingObject, 

pub async fn logs(&self, name: &str, lp: &LogParams) -> Result<String>

Fetch logs as a string

pub async fn log_stream(
    &self,
    name: &str,
    lp: &LogParams
) -> Result<impl Stream<Item = Result<Bytes>>>

Fetch logs as a stream of bytes

impl<K> Api<K> where
    K: Clone + DeserializeOwned + AttachableObject, 

pub async fn attach(
    &self,
    name: &str,
    ap: &AttachParams
) -> Result<AttachedProcess>

This is supported on crate feature ws only.

Attach to pod

impl<K> Api<K> where
    K: Clone + DeserializeOwned + ExecutingObject, 

pub async fn exec<I, T>(
    &self,
    name: &str,
    command: I,
    ap: &AttachParams
) -> Result<AttachedProcess> where
    I: IntoIterator<Item = T>,
    T: Into<String>, 

This is supported on crate feature ws only.

Execute a command in a pod

Trait Implementations

impl<K: Clone> Clone for Api<K>

pub fn clone(&self) -> Api<K>

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<K> From<Api<K>> for Client

pub fn from(api: Api<K>) -> Self

Performs the conversion.