Struct Client 

pub struct Client { /* private fields */ }

Available on crate feature k8s only.

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

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.

pub fn new<S, B, T>(service: S, default_namespace: T) -> Client

where S: Service<Request<Body>, Response = Response<B>> + Send + 'static, <S as Service<Request<Body>>>::Future: Send + 'static, <S as Service<Request<Body>>>::Error: Into<Box<dyn Error + Send + Sync>>, B: Body<Data = Bytes> + Send + 'static, <B as Body>::Error: Into<Box<dyn Error + Send + Sync>>, T: Into<String>,

Available on crate feature client only.

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

pub fn with_valid_until(self, valid_until: Option<Timestamp>) -> Client

Available on crate feature client only.

Sets an expiration timestamp to the client, which has to be checked by the user using Client::valid_until function.

pub fn valid_until(&self) -> &Option<Timestamp>

Available on crate feature client only.

Get the expiration timestamp of the client, if it has been set.

pub async fn try_default() -> Result<Client, Error>

Available on crate feature client only.

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.

pub fn default_namespace(&self) -> &str

Available on crate feature client only.

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.

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

Available on crate feature client only.

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.

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

where T: DeserializeOwned,

Available on crate feature client only.

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

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

Available on crate feature client only.

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

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

Available on crate feature client only.

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

The response can be processed using AsyncReadExt and AsyncBufReadExt.

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

where T: DeserializeOwned,

Available on crate feature client only.

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

pub async fn request_events<T>( &self, request: Request<Vec<u8>>, ) -> Result<impl TryStream + use<T>, Error>

where T: Clone + DeserializeOwned,

Available on crate feature client only.

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

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.

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

Available on crate feature client only.

Returns apiserver version.

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

Available on crate feature client only.

Lists api groups that apiserver serves.

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

Available on crate feature client only.

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

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

Available on crate feature client only.

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

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

Available on crate feature client only.

Lists resources served in particular core group version.

impl Client

Aggregated Discovery API methods

These methods use the Aggregated Discovery API (available since Kubernetes 1.26, stable in 1.30) to fetch all API resources in a single request, reducing the number of API calls compared to the traditional discovery methods.

pub async fn list_api_groups_aggregated( &self, ) -> Result<APIGroupDiscoveryList, Error>

Available on crate feature client only.

Returns aggregated discovery for all API groups served at /apis.

This uses the Aggregated Discovery API to fetch all non-core API groups and their resources in a single request.

Requires Kubernetes 1.26+ (beta) or 1.30+ (stable).

Example usage:

let discovery = client.list_api_groups_aggregated().await?;
for group in discovery.items {
    let name = group.metadata.as_ref().and_then(|m| m.name.as_ref());
    println!("Group: {:?}", name);
    for version in group.versions {
        println!("  Version: {:?}", version.version);
        for resource in version.resources {
            println!("    Resource: {:?}", resource.resource);
        }
    }
}

pub async fn list_core_api_versions_aggregated( &self, ) -> Result<APIGroupDiscoveryList, Error>

Available on crate feature client only.

Returns aggregated discovery for core API group served at /api.

This uses the Aggregated Discovery API to fetch the core API group and all its resources in a single request.

Requires Kubernetes 1.26+ (beta) or 1.30+ (stable).

Example usage:

let discovery = client.list_core_api_versions_aggregated().await?;
for group in discovery.items {
    for version in group.versions {
        println!("Core version: {:?}", version.version);
        for resource in version.resources {
            println!("  Resource: {:?} (scope: {:?})", resource.resource, resource.scope);
        }
    }
}

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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

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

Converts to this type from the input type.

impl TryFrom<Config> for Client

fn try_from(config: Config) -> Result<Client, Error>

Builds a default Client from a Config.

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

type Error = Error

The type returned in the event of a conversion error.

impl TryFrom<Kubeconfig> for Client

type Error = Error

The type returned in the event of a conversion error.

fn try_from(kubeconfig: Kubeconfig) -> Result<Client, Error>

Performs the conversion.