From d04d6ed586b4771b74966a4c28c777d811e2f0bd Mon Sep 17 00:00:00 2001 From: Eirik A Date: Fri, 15 Dec 2023 15:14:00 +0000 Subject: [PATCH] Add a warning to common footgun in `Api::all` and `Api::all_with` (#1374) People keep re-using the global-view to do individual operations on namespaced resources. Signed-off-by: clux --- kube-client/src/api/mod.rs | 10 ++++++++++ kube/src/lib.rs | 18 +++++++++--------- 2 files changed, 19 insertions(+), 9 deletions(-) diff --git a/kube-client/src/api/mod.rs b/kube-client/src/api/mod.rs index 88342025b..554b96876 100644 --- a/kube-client/src/api/mod.rs +++ b/kube-client/src/api/mod.rs @@ -70,6 +70,11 @@ impl Api { /// Cluster level resources, or resources viewed across all namespaces /// /// This function accepts `K::DynamicType` so it can be used with dynamic resources. + /// + /// # Warning + /// + /// This variant **can only `list` and `watch` namespaced resources** and is commonly used with a `watcher`. + /// If you need to create/patch/replace/get on a namespaced resource, you need a separate `Api::namespaced`. pub fn all_with(client: Client, dyntype: &K::DynamicType) -> Self { let url = K::url_path(dyntype, None); Self { @@ -149,6 +154,11 @@ where /// use k8s_openapi::api::core::v1::Node; /// let api: Api = Api::all(client); /// ``` + /// + /// # Warning + /// + /// This variant **can only `list` and `watch` namespaced resources** and is commonly used with a `watcher`. + /// If you need to create/patch/replace/get on a namespaced resource, you need a separate `Api::namespaced`. pub fn all(client: Client) -> Self { Self::all_with(client, &K::DynamicType::default()) } diff --git a/kube/src/lib.rs b/kube/src/lib.rs index f82046664..9d4b13e27 100644 --- a/kube/src/lib.rs +++ b/kube/src/lib.rs @@ -7,12 +7,12 @@ //! //! The main modules are: //! -//! - [`client`](crate::client) with the Kubernetes [`Client`](crate::Client) and its layers -//! - [`config`](crate::config) for cluster [`Config`](crate::Config) -//! - [`api`](crate::api) with the generic Kubernetes [`Api`](crate::Api) -//! - [`derive`](kube_derive) with the [`CustomResource`](crate::CustomResource) derive for building controllers types -//! - [`runtime`](crate::runtime) with a [`Controller`](crate::runtime::Controller) / [`watcher`](crate::runtime::watcher()) / [`reflector`](crate::runtime::reflector::reflector) / [`Store`](crate::runtime::reflector::Store) -//! - [`core`](crate::core) with generics from `apimachinery` +//! - [`client`] with the Kubernetes [`Client`] and its layers +//! - [`config`] for cluster [`Config`] +//! - [`api`] with the generic Kubernetes [`Api`] +//! - [`derive`](kube_derive) with the [`CustomResource`] derive for building controllers types +//! - [`runtime`] with a [`Controller`](crate::runtime::Controller) / [`watcher`](crate::runtime::watcher()) / [`reflector`](crate::runtime::reflector::reflector) / [`Store`](crate::runtime::reflector::Store) +//! - [`core`] with generics from `apimachinery` //! //! You can use each of these as you need with the help of the [exported features](https://github.com/kube-rs/kube/blob/main/kube/Cargo.toml#L18). //! @@ -39,7 +39,7 @@ //! For details, see: //! //! - [`Client`](crate::client) for the extensible Kubernetes client -//! - [`Api`](crate::Api) for the generic api methods available on Kubernetes resources +//! - [`Api`] for the generic api methods available on Kubernetes resources //! - [k8s-openapi](https://docs.rs/k8s-openapi/*/k8s_openapi/) for documentation about the generated Kubernetes types //! //! # Using the Runtime with the Derive macro @@ -97,9 +97,9 @@ //! //! For details, see: //! -//! - [`CustomResource`](crate::CustomResource) for documentation how to configure custom resources +//! - [`CustomResource`] for documentation how to configure custom resources //! - [`runtime::watcher`](crate::runtime::watcher()) for how to long-running watches work and why you want to use this over [`Api::watch`](crate::Api::watch) -//! - [`runtime`](crate::runtime) for abstractions that help with more complicated Kubernetes application +//! - [`runtime`] for abstractions that help with more complicated Kubernetes application //! //! # Examples //! A large list of complete, runnable examples with explainations are available in the [examples folder](https://github.com/kube-rs/kube/tree/main/examples).