kube_client

Struct Client

source 
pub struct Client { /* private fields */ }
Available on crate feature client only.
Expand description

Client for connecting with a Kubernetes cluster.

The easiest way to instantiate the client is either by inferring the configuration from the environment using Client::try_default or with an existing Config using Client::try_from.

Implementations§

source§

impl Client

Generic client extensions for the unstable-client feature

These methods allow users to query across a wide-array of resources without needing to explicitly create an Api for each one of them.

§Usage
  1. Create a Client
  2. Specify the scope you are querying at via Cluster or Namespace as args
  3. Specify the resource type you are using for serialization (e.g. a top level k8s-openapi type)
§Example
let lp = ListParams::default();
// List at Cluster level for Pod resource:
for pod in client.list::<Pod>(&lp, &Cluster).await? {
    println!("Found pod {} in {}", pod.name_any(), pod.namespace().unwrap());
}
// Namespaced Get for Service resource:
let svc = client.get::<Service>("kubernetes", &Namespace::from("default")).await?;
assert_eq!(svc.name_unchecked(), "kubernetes");
source

pub async fn get<K>(&self, name: &str, scope: &impl ObjectUrl<K>) -> Result<K>
where K: Resource + Serialize + DeserializeOwned + Clone + Debug, <K as Resource>::DynamicType: Default,

Available on crate feature unstable-client only.

Get a single instance of a Resource implementing type K at the specified scope.

let cr = client.get::<ClusterRole>("cluster-admin", &Cluster).await?;
assert_eq!(cr.name_unchecked(), "cluster-admin");
let svc = client.get::<Service>("kubernetes", &Namespace::from("default")).await?;
assert_eq!(svc.name_unchecked(), "kubernetes");
source

pub async fn fetch<K>(&self, reference: &impl ObjectRef<K>) -> Result<K>
where K: Resource + Serialize + DeserializeOwned + Clone + Debug,

Available on crate feature unstable-client only.

Fetch a single instance of a Resource from a provided object reference.

// cluster scoped
let cr: ClusterRole = todo!();
let cr: ClusterRole = client.fetch(&cr.object_ref(&())).await?;
assert_eq!(cr.name_unchecked(), "cluster-admin");
// namespace scoped
let svc: Service = todo!();
let svc: Service = client.fetch(&svc.object_ref(&())).await?;
assert_eq!(svc.name_unchecked(), "kubernetes");
// Fetch an owner of the resource
let pod: Pod = todo!();
let owner = pod
    .owner_references()
    .to_vec()
    .into_iter()
    .find(|r| r.kind == Node::kind(&()))
    .ok_or("Not Found")?;
let node: Node = client.fetch(&owner).await?;
// Namespace scoped objects require namespace
let pod: Pod = client.fetch(&owner.within("ns".to_string())).await?;
// Fetch dynamic object to resolve type later
let dynamic: DynamicObject = client.fetch(&owner.within("ns".to_string())).await?;
// Fetch using local object reference
let secret_ref = pod
    .spec
    .unwrap_or_default()
    .image_pull_secrets
    .unwrap_or_default()
    .get(0)
    .unwrap_or(&LocalObjectReference{name: "pull_secret".into()});
let secret: Secret = client.fetch(&secret_ref.within(pod.namespace())).await?;
source

pub async fn list<K>( &self, lp: &ListParams, scope: &impl CollectionUrl<K>, ) -> Result<ObjectList<K>>
where K: Resource + Serialize + DeserializeOwned + Clone + Debug, <K as Resource>::DynamicType: Default,

Available on crate feature unstable-client only.

List instances of a Resource implementing type K at the specified scope.

let lp = ListParams::default();
for pod in client.list::<Pod>(&lp, &Cluster).await? {
    println!("Found pod {} in {}", pod.name_any(), pod.namespace().unwrap());
}
for svc in client.list::<Service>(&lp, &Namespace::from("default")).await? {
    println!("Found service {}", svc.name_any());
}
source§

impl Client

Constructors and low-level api interfaces.

Most users only need Client::try_default or Client::new from this block.

The many various lower level interfaces here are for more advanced use-cases with specific requirements.

source

pub fn new<S, B, T>(service: S, default_namespace: T) -> Self
where S: Service<Request<Body>, Response = Response<B>> + Send + 'static, S::Future: Send + 'static, S::Error: Into<BoxError>, B: Body<Data = Bytes> + Send + 'static, B::Error: Into<BoxError>, T: Into<String>,

Create a Client using a custom Service stack.

ConfigExt provides extensions for building a custom stack.

To create with the default stack with a Config, use Client::try_from.

To create with the default stack with an inferred Config, use Client::try_default.

§Example
use kube::{client::ConfigExt, Client, Config};
use tower::{BoxError, ServiceBuilder};
use hyper_util::rt::TokioExecutor;

let config = Config::infer().await?;
let service = ServiceBuilder::new()
    .layer(config.base_uri_layer())
    .option_layer(config.auth_layer()?)
    .map_err(BoxError::from)
    .service(hyper_util::client::legacy::Client::builder(TokioExecutor::new()).build_http());
let client = Client::new(service, config.default_namespace);
source

pub async fn try_default() -> Result<Self>

Create and initialize a Client using the inferred configuration.

Will use Config::infer which attempts to load the local kubeconfig first, and then if that fails, trying the in-cluster environment variables.

Will fail if neither configuration could be loaded.

let client = Client::try_default().await?;

If you already have a Config then use Client::try_from instead.

source

pub fn default_namespace(&self) -> &str

Get the default namespace for the client

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

source

pub async fn send(&self, request: Request<Body>) -> Result<Response<Body>>

Perform a raw HTTP request against the API and return the raw response back. This method can be used to get raw access to the API which may be used to, for example, create a proxy server or application-level gateway between localhost and the API server.

source

pub async fn connect( &self, request: Request<Vec<u8>>, ) -> Result<WebSocketStream<TokioIo<Upgraded>>>

Available on crate feature ws only.

Make WebSocket connection.

source

pub async fn request<T>(&self, request: Request<Vec<u8>>) -> Result<T>
where T: DeserializeOwned,

Perform a raw HTTP request against the API and deserialize the response as JSON to some known type.

source

pub async fn request_text(&self, request: Request<Vec<u8>>) -> Result<String>

Perform a raw HTTP request against the API and get back the response as a string

source

pub async fn request_stream( &self, request: Request<Vec<u8>>, ) -> Result<impl AsyncBufRead>

Perform a raw HTTP request against the API and stream the response body.

The response can be processed using AsyncReadExt and AsyncBufReadExt.

source

pub async fn request_status<T>( &self, request: Request<Vec<u8>>, ) -> Result<Either<T, Status>>
where T: DeserializeOwned,

Perform a raw HTTP request against the API and get back either an object deserialized as JSON or a Status Object.

source

pub async fn request_events<T>( &self, request: Request<Vec<u8>>, ) -> Result<impl TryStream<Item = Result<WatchEvent<T>>>>
where T: Clone + DeserializeOwned,

Perform a raw request and get back a stream of WatchEvent objects

source§

impl Client

Low level discovery methods using k8s_openapi types.

Consider using the discovery module for easier-to-use variants of this functionality. The following methods might be deprecated to avoid confusion between similarly named types within discovery.

source

pub async fn apiserver_version(&self) -> Result<Info>

Returns apiserver version.

source

pub async fn list_api_groups(&self) -> Result<APIGroupList>

Lists api groups that apiserver serves.

source

pub async fn list_api_group_resources( &self, apiversion: &str, ) -> Result<APIResourceList>

Lists resources served in given API group.

§Example usage:
let apigroups = client.list_api_groups().await?;
for g in apigroups.groups {
    let ver = g
        .preferred_version
        .as_ref()
        .or_else(|| g.versions.first())
        .expect("preferred or versions exists");
    let apis = client.list_api_group_resources(&ver.group_version).await?;
    dbg!(apis);
}
source

pub async fn list_core_api_versions(&self) -> Result<APIVersions>

Lists versions of core a.k.a. "" legacy API group.

source

pub async fn list_core_api_resources( &self, version: &str, ) -> Result<APIResourceList>

Lists resources served in particular core group version.

Trait Implementations§

source§

impl Clone for Client

source§

fn clone(&self) -> Client

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Converts to this type from the input type.
source§

impl TryFrom<Config> for Client

source§

fn try_from(config: Config) -> Result<Self>

Builds a default Client from a Config.

See ClientBuilder or Client::new if more customization is required

source§

type Error = Error

The type returned in the event of a conversion error.

Auto Trait Implementations§

§

impl Freeze for Client

§

impl !RefUnwindSafe for Client

§

impl Send for Client

§

impl Sync for Client

§

impl Unpin for Client

§

impl !UnwindSafe for Client

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> DynClone for T
where T: Clone,

source§

fn __clone_box(&self, _: Private) -> *mut ()

source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

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

fn in_current_span(self) -> Instrumented<Self>

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

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

impl<T> Same for T

source§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

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

fn clone_into(&self, target: &mut T)

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

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

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

fn with_current_subscriber(self) -> WithDispatch<Self>

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