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 <[email protected]>

kube-client/src/api/mod.rs

@@ -70,6 +70,11 @@ impl<K: Resource> Api<K> {
     /// 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<Node> = 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())
     }

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