Struct kube::api::Api [−][src]
pub struct Api<K> { /* fields omitted */ }
client
only.Expand description
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(())
}
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:
- 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)
- 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)
- [
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(())
}
pub async fn delete_collection(
&'_ self,
dp: &'_ DeleteParams,
lp: &'_ ListParams
) -> Result<Either<ObjectList<K>, Status>, Error>
pub async fn delete_collection(
&'_ self,
dp: &'_ DeleteParams,
lp: &'_ ListParams
) -> 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}, 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", ¶ms, &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.
pub async fn watch(
&'_ self,
lp: &'_ ListParams,
version: &'_ str
) -> Result<impl Stream<Item = Result<WatchEvent<K>, Error>>, Error>
pub async fn watch(
&'_ self,
lp: &'_ ListParams,
version: &'_ str
) -> 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
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
pub async fn patch_scale<P>(
&'_ self,
name: &'_ str,
pp: &'_ PatchParams,
patch: &'_ Patch<P>
) -> Result<Scale, Error> where
P: Serialize + Debug,
pub async fn patch_scale<P>(
&'_ self,
name: &'_ str,
pp: &'_ PatchParams,
patch: &'_ Patch<P>
) -> 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>
) -> Result<Scale, Error>
pub async fn replace_scale(
&'_ self,
name: &'_ str,
pp: &'_ PostParams,
data: Vec<u8, Global>
) -> Result<Scale, Error>
Replace the scale subresource
Methods for status subresource.
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>
) -> Result<K, Error> where
P: Serialize + Debug,
pub async fn patch_status<P>(
&'_ self,
name: &'_ str,
pp: &'_ PatchParams,
patch: &'_ Patch<P>
) -> 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>
) -> Result<K, Error>
pub async fn replace_status(
&'_ self,
name: &'_ str,
pp: &'_ PostParams,
data: Vec<u8, Global>
) -> 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(())
}
pub async fn attach(
&'_ self,
name: &'_ str,
ap: &'_ AttachParams
) -> Result<AttachedProcess, Error>
pub async fn attach(
&'_ self,
name: &'_ str,
ap: &'_ AttachParams
) -> Result<AttachedProcess, Error>
Attach to pod
pub async fn exec<I, T>(
&'_ self,
name: &'_ str,
command: I,
ap: &'_ AttachParams
) -> Result<AttachedProcess, Error> where
I: Debug + IntoIterator<Item = T>,
T: Into<String>,
pub async fn exec<I, T>(
&'_ self,
name: &'_ str,
command: I,
ap: &'_ AttachParams
) -> Result<AttachedProcess, Error> where
I: Debug + IntoIterator<Item = T>,
T: Into<String>,
Execute a command in a pod
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.
pub fn namespaced_with(
client: Client,
ns: &str,
dyntype: &<K as Resource>::DynamicType
) -> Api<K>
pub fn namespaced_with(
client: Client,
ns: &str,
dyntype: &<K as Resource>::DynamicType
) -> Api<K>
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>
pub fn default_namespaced_with(
client: Client,
dyntype: &<K as Resource>::DynamicType
) -> Api<K>
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
Auto Trait Implementations
impl<K> !RefUnwindSafe for Api<K>
impl<K> !UnwindSafe for Api<K>
Blanket Implementations
Mutably borrows from an owned value. Read more
pub fn vzip(self) -> V
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