From de9f22299353c360345f497736f160eff8055bf9 Mon Sep 17 00:00:00 2001 From: Nikhita Raghunath Date: Wed, 16 May 2018 11:06:30 +0530 Subject: [PATCH] custom resources: explain declarative API (#8543) Currently, the link just points to a description of what Kubernetes objects are and does not explicitly state what a declarative API is. It is not immediately clear to the reader what the term means. This commit tries to explain it explicitly so that the link adds to the meaning and it is clearer to the reader. --- content/en/docs/concepts/api-extension/custom-resources.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/content/en/docs/concepts/api-extension/custom-resources.md b/content/en/docs/concepts/api-extension/custom-resources.md index f65985e474..624fbc83b3 100644 --- a/content/en/docs/concepts/api-extension/custom-resources.md +++ b/content/en/docs/concepts/api-extension/custom-resources.md @@ -28,7 +28,12 @@ Once a custom resource is installed, users can create and access its objects wit ### Custom controllers On their own, custom resources simply let you store and retrieve structured data. -It is only when combined with a *controller* that they become a true [declarative API](/docs/concepts/overview/working-with-objects/kubernetes-objects/#understanding-kubernetes-objects). The controller interprets the structured data as a record of the user's desired state, and continually takes action to achieve and maintain that state. +It is only when combined with a *controller* that they become a true declarative API. +A [declarative API](/docs/concepts/overview/working-with-objects/kubernetes-objects/#understanding-kubernetes-objects) +allows you to _declare_ or specify the desired state of your resource and tries +to match the actual state to this desired state. +Here, the controller interprets the structured data as a record of the user's +desired state, and continually takes action to achieve and maintain this state. A *custom controller* is a controller that users can deploy and update on a running cluster, independently of the cluster's own lifecycle. Custom controllers can work with any kind of resource, but they are especially effective when combined with custom resources. The [Operator](https://coreos.com/blog/introducing-operators.html) pattern is one example of such a combination. It allows developers to encode domain knowledge for specific applications into an extension of the Kubernetes API.