Struct kube::Api

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

Available on crate feature client only.

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

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

PUSH/PUT/POST/GET abstractions

pub async fn get(&self, name: &str) -> impl Future<Output = Result<K, Error>>

Get a named resource

use k8s_openapi::api::core::v1::Pod;

let pods: Api<Pod> = Api::namespaced(client, "apps");
let p: Pod = pods.get("blog").await?;

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.

pub async fn get_metadata( &self, name: &str ) -> impl Future<Output = Result<PartialObjectMeta<K>, Error>>

Get only the metadata for a named resource as PartialObjectMeta

use kube::{Api, core::PartialObjectMeta};
use k8s_openapi::api::core::v1::Pod;

let pods: Api<Pod> = Api::namespaced(client, "apps");
let p: PartialObjectMeta<Pod> = pods.get_metadata("blog").await?;

Note that the type may be converted to ObjectMeta through the usual conversion traits.

Errors

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

pub async fn get_opt( &self, name: &str ) -> impl Future<Output = Result<Option<K>, Error>>

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

use k8s_openapi::api::core::v1::Pod;

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
}

pub async fn get_metadata_opt( &self, name: &str ) -> impl Future<Output = Result<Option<PartialObjectMeta<K>>, Error>>

Get Metadata for a named resource if it exists, returns None if it doesn’t exit

use k8s_openapi::api::core::v1::Pod;
let pods: Api<Pod> = Api::namespaced(client, "apps");
if let Some(pod) = pods.get_metadata_opt("blog").await? {
    // Pod was found
} else {
    // Pod was not found
}

Note that PartialObjectMeta embeds the raw ObjectMeta.

pub async fn list( &self, lp: &ListParams ) -> impl Future<Output = Result<ObjectList<K>, Error>>

Get a list of resources

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

use kube::api::{Api, ListParams, ResourceExt};
use k8s_openapi::api::core::v1::Pod;

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

pub async fn list_metadata( &self, lp: &ListParams ) -> impl Future<Output = Result<ObjectList<PartialObjectMeta<K>>, Error>>

Get a list of resources that contains only their metadata as

Similar to list, you use this to get everything, or a subset matching fields/labels. For example

use kube::api::{Api, ListParams, ResourceExt};
use kube::core::{ObjectMeta, ObjectList, PartialObjectMeta};
use k8s_openapi::api::core::v1::Pod;

let pods: Api<Pod> = Api::namespaced(client, "apps");
let lp = ListParams::default().labels("app=blog"); // for this app only
let list: ObjectList<PartialObjectMeta<Pod>> = pods.list_metadata(&lp).await?;
for p in list {
    println!("Found Pod: {}", p.name_any());
}

pub async fn create( &self, pp: &PostParams, data: &K ) -> impl Future<Output = Result<K, Error>>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)

Note that this method cannot write to the status object (when it exists) of a resource. To set status objects please see Api::replace_status or Api::patch_status.

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

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};
use k8s_openapi::apiextensions_apiserver::pkg::apis::apiextensions::v1 as apiexts;
use apiexts::CustomResourceDefinition;
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));

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

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};
use k8s_openapi::api::core::v1::Pod;

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_any).collect();
        println!("Deleting collection of pods: {:?}", names);
    },
    either::Right(status) => {
        println!("Deleted collection of pods: status={:?}", status);
    }
}

pub async fn patch<P>( &self, name: &str, pp: &PatchParams, patch: &Patch<P> ) -> impl Future<Output = Result<K, Error>>where P: Serialize + Debug,

Patch a subset of a resource’s properties

Takes a Patch along with PatchParams for the call.

use kube::api::{Api, PatchParams, Patch, Resource};
use k8s_openapi::api::core::v1::Pod;

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?;

Note that this method cannot write to the status object (when it exists) of a resource. To set status objects please see Api::replace_status or Api::patch_status.

pub async fn patch_metadata<P>( &self, name: &str, pp: &PatchParams, patch: &Patch<P> ) -> impl Future<Output = Result<PartialObjectMeta<K>, Error>>where P: Serialize + Debug,

Patch a metadata subset of a resource’s properties from PartialObjectMeta

Takes a Patch along with PatchParams for the call. Patches can be constructed raw using serde_json::json! or from ObjectMeta via PartialObjectMetaExt.

use kube::api::{Api, PatchParams, Patch, Resource};
use kube::core::{PartialObjectMetaExt, ObjectMeta};
use k8s_openapi::api::core::v1::Pod;

let pods: Api<Pod> = Api::namespaced(client, "apps");
let metadata = ObjectMeta {
    labels: Some([("key".to_string(), "value".to_string())].into()),
    ..Default::default()
}.into_request_partial::<Pod>();

let params = PatchParams::apply("myapp");
let o_patched = pods.patch_metadata("blog", &params, &Patch::Apply(&metadata)).await?;
println!("Patched {}", o_patched.metadata.name.unwrap());

Warnings

The TypeMeta (apiVersion + kind) of a patch request (required for apply patches) must match the underlying type that is being patched (e.g. “v1” + “Pod”). The returned TypeMeta will always be {“meta.k8s.io/v1”, “PartialObjectMetadata”}. These constraints are encoded into PartialObjectMetaExt.

This method can write to non-metadata fields such as spec if included in the patch.

pub async fn replace( &self, name: &str, pp: &PostParams, data: &K ) -> impl Future<Output = Result<K, Error>>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, ResourceExt};
use k8s_openapi::api::batch::v1::Job;

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?;

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

Note that this method cannot write to the status object (when it exists) of a resource. To set status objects please see Api::replace_status or Api::patch_status.

pub async fn watch( &self, wp: &WatchParams, version: &str ) -> impl Future<Output = Result<impl Stream<Item = Result<WatchEvent<K>, Error>>, Error>>

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 WatchParams::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, WatchParams, ResourceExt, WatchEvent};
use k8s_openapi::api::batch::v1::Job;
use futures::{StreamExt, TryStreamExt};

let jobs: Api<Job> = Api::namespaced(client, "apps");
let lp = WatchParams::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_any()),
        WatchEvent::Modified(s) => println!("Modified: {}", s.name_any()),
        WatchEvent::Deleted(s) => println!("Deleted {}", s.name_any()),
        WatchEvent::Bookmark(s) => {},
        WatchEvent::Error(s) => println!("{}", s),
    }
}

pub async fn watch_metadata( &self, wp: &WatchParams, version: &str ) -> impl Future<Output = Result<impl Stream<Item = Result<WatchEvent<PartialObjectMeta<K>>, Error>>, Error>>

Watch a list of metadata for a given resources

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

Note that a watch_metadata call can terminate for many reasons (even before the specified WatchParams::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 metadata_watcher to deal with automatic re-watches and error cases.

use kube::api::{Api, WatchParams, ResourceExt, WatchEvent};
use k8s_openapi::api::batch::v1::Job;
use futures::{StreamExt, TryStreamExt};

let jobs: Api<Job> = Api::namespaced(client, "apps");

let lp = WatchParams::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.metadata.name.unwrap()),
        WatchEvent::Modified(s) => println!("Modified: {}", s.metadata.name.unwrap()),
        WatchEvent::Deleted(s) => println!("Deleted {}", s.metadata.name.unwrap()),
        WatchEvent::Bookmark(s) => {},
        WatchEvent::Error(s) => println!("{}", s),
    }
}

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

Methods for scale subresource.

pub async fn get_scale( &self, name: &str ) -> impl Future<Output = Result<Scale, Error>>

Fetch the scale subresource

pub async fn patch_scale<P>( &self, name: &str, pp: &PatchParams, patch: &Patch<P> ) -> impl Future<Output = Result<Scale, Error>>where P: Serialize + Debug,

Update the scale subresource

pub async fn replace_scale( &self, name: &str, pp: &PostParams, data: Vec<u8, Global> ) -> impl Future<Output = Result<Scale, Error>>

Replace the scale subresource

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

Arbitrary subresources

pub async fn get_subresource( &self, subresource_name: &str, name: &str ) -> impl Future<Output = Result<K, Error>>

Display one or many sub-resources.

pub async fn create_subresource<T>( &self, subresource_name: &str, name: &str, pp: &PostParams, data: Vec<u8, Global> ) -> impl Future<Output = Result<T, Error>>where T: DeserializeOwned,

Create an instance of the subresource

pub async fn patch_subresource<P>( &self, subresource_name: &str, name: &str, pp: &PatchParams, patch: &Patch<P> ) -> impl Future<Output = Result<K, Error>>where P: Serialize + Debug,

Patch an instance of the subresource

pub async fn replace_subresource( &self, subresource_name: &str, name: &str, pp: &PostParams, data: Vec<u8, Global> ) -> impl Future<Output = Result<K, Error>>

Replace an instance of the subresource

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

Methods for status subresource.

pub async fn get_status( &self, name: &str ) -> impl Future<Output = Result<K, Error>>

Get the named resource with a status subresource

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

pub async fn patch_status<P>( &self, name: &str, pp: &PatchParams, patch: &Patch<P> ) -> impl Future<Output = Result<K, Error>>where P: Serialize + Debug,

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(())
}

pub async fn replace_status( &self, name: &str, pp: &PostParams, data: Vec<u8, Global> ) -> impl Future<Output = Result<K, Error>>

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(())
}

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

pub async fn logs( &self, name: &str, lp: &LogParams ) -> impl Future<Output = Result<String, Error>>

Fetch logs as a string

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

Fetch logs as a stream of bytes

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

pub async fn evict( &self, name: &str, ep: &EvictParams ) -> impl Future<Output = Result<Status, Error>>

Create an eviction

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

pub async fn attach( &self, name: &str, ap: &AttachParams ) -> impl Future<Output = Result<AttachedProcess, Error>>

Attach to pod

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

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

Execute a command in a pod

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

pub async fn portforward( &self, name: &str, ports: &[u16] ) -> impl Future<Output = Result<Portforwarder, Error>>

Forward ports of a pod

impl Api<CertificateSigningRequest>

pub async fn patch_approval<P>( &self, name: &str, pp: &PatchParams, patch: &Patch<P> ) -> impl Future<Output = Result<CertificateSigningRequest, Error>>where P: Serialize,

Partially update approval of the specified CertificateSigningRequest.

pub async fn get_approval( &self, name: &str ) -> impl Future<Output = Result<CertificateSigningRequest, Error>>

Get the CertificateSigningRequest. May differ from get(name)

impl<K> Api<K>where K: Restart + Resource + DeserializeOwned,

pub async fn restart( &self, name: &str ) -> impl Future<Output = Result<K, Error>>

Trigger a restart of a Resource.

impl Api<Node>

pub async fn cordon( &self, name: &str ) -> impl Future<Output = Result<Node, Error>>

Cordon a Node.

pub async fn uncordon( &self, name: &str ) -> impl Future<Output = Result<Node, Error>>

Uncordon a Node.

impl Api<ServiceAccount>

pub async fn create_token_request( &self, name: &str, pp: &PostParams, token_request: &TokenRequest ) -> impl Future<Output = Result<TokenRequest, Error>>

Create a TokenRequest of a ServiceAccount

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

pub async fn entry<'a>( &'a self, name: &'a str ) -> impl Future<Output = Result<Entry<'a, K>, Error>>

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?;

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

Api constructors for Resource implementors with custom DynamicTypes

This generally means resources created via DynamicObject.

pub fn all_with( client: Client, dyntype: &<K as Resource>::DynamicType ) -> Api<K>

Cluster level resources, or resources viewed across all namespaces

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

pub fn namespaced_with( client: Client, ns: &str, dyntype: &<K as Resource>::DynamicType ) -> Api<K>where K: Resource<Scope = DynamicResourceScope>,

Namespaced resource within a given namespace

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

pub fn default_namespaced_with( client: Client, dyntype: &<K as Resource>::DynamicType ) -> Api<K>where K: Resource<Scope = DynamicResourceScope>,

Namespaced resource within the default namespace

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

The namespace is either configured on context in the kubeconfig or falls back to default when running locally, and it’s using the service account’s namespace when deployed in-cluster.

pub fn into_client(self) -> Client

Consume self and return the Client

pub fn resource_url(&self) -> &str

Return a reference to the current resource url path

impl<K> Api<K>where K: Resource, <K as Resource>::DynamicType: Default,

Api constructors for Resource implementors with Default DynamicTypes

This generally means structs implementing k8s_openapi::Resource.

pub fn all(client: Client) -> Api<K>

Cluster level resources, or resources viewed across all namespaces

Namespace scoped resource allowing querying across all namespaces:

use k8s_openapi::api::core::v1::Pod;
let api: Api<Pod> = Api::all(client);

Cluster scoped resources also use this entrypoint:

use k8s_openapi::api::core::v1::Node;
let api: Api<Node> = Api::all(client);

pub fn namespaced(client: Client, ns: &str) -> Api<K>where K: Resource<Scope = NamespaceResourceScope>,

Namespaced resource within a given namespace

use k8s_openapi::api::core::v1::Pod;
let api: Api<Pod> = Api::namespaced(client, "default");

This will ONLY work on namespaced resources as set by Scope:

use k8s_openapi::api::core::v1::Node;
let api: Api<Node> = Api::namespaced(client, "default"); // resource not namespaced!

For dynamic type information, use Api::namespaced_with variants.

pub fn default_namespaced(client: Client) -> Api<K>where K: Resource<Scope = NamespaceResourceScope>,

Namespaced resource within the default namespace

The namespace is either configured on context in the kubeconfig or falls back to default when running locally, and it’s using the service account’s namespace when deployed in-cluster.

use k8s_openapi::api::core::v1::Pod;
let api: Api<Pod> = Api::default_namespaced(client);

This will ONLY work on namespaced resources as set by Scope:

use k8s_openapi::api::core::v1::Node;
let api: Api<Node> = Api::default_namespaced(client); // resource not namespaced!

Trait Implementations

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<K> Debug for Api<K>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

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

fn from(api: Api<K>) -> Client

Converts to this type from the input type.