From 6a4dddd251f13f1c87a271544a048baaafe9a496 Mon Sep 17 00:00:00 2001 From: Jay Pipes Date: Thu, 12 Aug 2021 16:21:27 -0400 Subject: [PATCH] clarify declarative API in custom controller docs The content describing a declarative API in the custom controller section of the custom resources doc was confusing: > A declarative API allows you to declare or specify the desired state of your resource **and tries to keep the current state of Kubernetes objects in sync with the desired state**. The controller interprets the structured data as a record of the user's desired state, and continually maintains this state. (emphasis added) It is not the declarative API that tries to keep the current state of the objects in sync with the desired state. It's the controller that does that. I've reworded this paragraph to hopefully clarify this. Closes Issue #29348 Signed-off-by: Jay Pipes --- .../api-extension/custom-resources.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md b/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md index f37a71f278..0746e9f4f1 100644 --- a/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md +++ b/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md @@ -35,11 +35,11 @@ On their own, custom resources let you store and retrieve structured data. When you combine a custom resource with a *custom controller*, custom resources provide a true _declarative API_. -A [declarative API](/docs/concepts/overview/kubernetes-api/) -allows you to _declare_ or specify the desired state of your resource and tries to -keep the current state of Kubernetes objects in sync with the desired state. -The controller interprets the structured data as a record of the user's -desired state, and continually maintains this state. +The Kubernetes [declarative API](/docs/concepts/overview/kubernetes-api/) +enforces a separation of responsibilities. You declare the desired state of +your resource. The Kubernetes controller keeps the current state of Kubernetes +objects in sync with your declared desired state. This is in contrast to an +imperative API, where you *instruct* a server what to do. You can deploy and update a custom controller on a running cluster, independently of the cluster's lifecycle. Custom controllers can work with any kind of resource,