Add reference documentation for built-in controllers #15374

sftim · 2019-07-11T07:44:34Z

Relevant to issue #4135.

Add a reference section that lists the built-in controllers and explains what each of them does.

This change fits in with an idea I have to restructure https://kubernetes.io/docs/concepts/workloads/

People developing things to deploy on Kubernetes need to understand that there is (eg) a Deployment resource; it doesn't matter as much how the Deployment resource gets translated into API actions like creating or removing ReplicaSet objects. Some resources happen to involve more than one controller (eg Job with the Job controller and the TTL-after-finished controller).

If you are interested in looking behind the scenes, I think it helps to have all kube-controller-manager controllers listed in one place, no matter what kind of resource they interact with (Endpoint? ReplicaSet? Namespace?)

/sig apps

You can see this change in broader context by viewing the deployment preview for PR #15373 (or looking at the list of files changed there, etc).

Credit to @lavalamp for the excellent Kubecon talk that helped me a lot with drafting these documents.

k8s-ci-robot · 2019-07-11T07:44:56Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign zparnold
You can assign the PR to them by writing /assign @zparnold in a comment when ready.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

content/en/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

sftim · 2019-07-11T07:45:10Z

/assign @zparnold

sftim · 2019-07-11T07:45:55Z

@bradtopol I'd welcome your feedback on this.

netlify · 2019-07-11T07:52:13Z

Deploy preview for kubernetes-io-master-staging ready!

Built with commit c96ed15

https://deploy-preview-15374--kubernetes-io-master-staging.netlify.com

jaypipes

Phew, this was a big one :)

Mostly awesome work on this @sftim. I have a number of inline suggestions, but the biggest ones are around separating out information that is implementation details about the controllers from information that is more end-user oriented that explains how to use the different objects like Job, Deployment, StatefulSet. I think that kind information -- the more end-user oriented -- best belongs in the concepts/workloads/ documentation.

Anyway, love to hear your thoughts on my comments.

Best,
-jay

content/en/docs/reference/controllers/admission-pod-preset.md

jaypipes · 2019-07-12T21:29:43Z

content/en/docs/reference/controllers/attach-detach.md

@@ -0,0 +1,39 @@
+---


recommend naming the file volume-attach-detach.md instead of just attach-detach.md. You never know, we could get additional attaching-detaching controllers in the future. :)

In that case, I should probably rename all the controller documents based on the subdirectory they're in in the kubernetes/kubernetes source code.

Which I will do.

I have a better idea. I will rename them based on the names visible to cluster operators, as per --controllers in https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/

(these must also be in the source code, so I'll see if I can spot how that's done)

content/en/docs/reference/controllers/attach-detach.md

jaypipes · 2019-07-12T21:50:14Z

content/en/docs/reference/controllers/attach-detach.md

+to detach it.
+
+Different nodes might have different ways of attaching volumes, and different
+Volumes can have different values for VolumeNodeAffinity, so the decision


Consider linking VolumeNodeAffinity to https://kubernetes.io/docs/concepts/storage/persistent-volumes/#node-affinity.

This sentence is hard for me to understand, though, in particular the part "so the decision around volume attachment happens after scheduling." What specifically are you conveying here? Are you trying to say that normally node affinity constraints are handled by the scheduler, but in some cases node affinity constraints are handled on the node instead?

content/en/docs/reference/controllers/built-in.md

content/en/docs/reference/controllers/replicationcontroller.md

jaypipes · 2019-07-16T14:26:49Z

content/en/docs/reference/controllers/resource-quota.md

+
+This controller limits the quantity of objects that can be created in a namespace
+by object type, as well as the total amount of compute resources that may be
+consumed by resources in that project.


"that project" is used, but there is no mention of "project" earlier in the paragraph. This is likely due to legacy Google-specific terminology? Probably best to rephrase it here.

jaypipes · 2019-07-16T14:29:48Z

content/en/docs/reference/controllers/statefulset.md

+The controller constructs the pod name label valuebased on a pattern:
+`$(statefulset name)-$(ordinal)`.
+
+### Storage


Similar to Deployment and Job, I think much of the remainder of this page should be in a concepts/workloads/statefulset.md document that is written from an end-user or object reference perspective. And leave this doc for implementation specifics about the controller itself.

jaypipes · 2019-07-16T14:30:42Z

content/en/docs/reference/controllers/ttl-after-finished.md

+of expired Jobs can still happen, even if you requested a longer TTL
+and you saw a successful API response to your update request.
+
+## Time skew


this probably belongs in this document since it's implementation details about the controller itself.

jaypipes · 2019-07-16T14:31:50Z

content/en/docs/reference/controllers/ttl-after-finished.md

+its dependent objects together with it. Note that when the resource is deleted,
+its lifecycle guarantees, such as finalizers, will be honored.
+
+The TTL seconds can be set at any time. Here are some examples for setting the


From here down in this section kind of feels like it belongs in a concepts/workloads/job.md document that is more oriented to the end user than the person interested in how the controller works under the hood.

lavalamp · 2019-07-16T20:00:21Z

My last kubecon talk was almost exactly about this: https://youtu.be/zCXiXKMqnuE

sftim · 2019-07-16T20:56:28Z

What do you reckon @jaypipes? How's this now?

sftim · 2019-07-16T21:04:04Z

My last kubecon talk was almost exactly about this: https://youtu.be/zCXiXKMqnuE

@lavalamp a good talk, too! Please do let me know if I've got any details wrong.

jaypipes

++ great work on this, Tim.

jaypipes · 2019-07-18T16:00:54Z

content/en/docs/reference/controllers/built-in.md

+
+### Namespace lifecycle controller {#controller-namespace}
+
+When you (or any Kubernetes API client) remove a {{< glossary_tooltip term_id="namespace" >}},


ack, great explanation @lavalamp, appreciated! @sftim might be good to paste Daniel's explanation on the difference between the two controllers into this doc in a followup PR.

jaypipes · 2019-07-18T16:08:06Z

content/en/docs/reference/controllers/daemonset.md

+
+### Taints and Tolerations
+
+the controller automatically adds the following 


nit: Capitalize "The controller"

kbhawkey · 2019-07-19T20:00:11Z

hello, @sftim. I am in the process of reading through the files 😄 . My initial impression is that this will serve as a nice resource. Since the list of controllers is long and you have categorized some of the controllers on the Built-in controllers page, I would suggest to create several groupings to list on the left nav and then put the individual controllers in a category. If there are a few that do not have a single category, then list them independently. Perhaps you do not need the Built-in Controllers page.
The Controllers main list item in the left nav could also be listed after the API-related folder items.
Not sure about listing vendor links in the reference, for example, third party ingress controllers.

New Controllers root page preview
https://deploy-preview-15374--kubernetes-io-master-staging.netlify.com/docs/reference/controllers

DanyC97 · 2019-07-20T09:08:40Z

content/en/docs/reference/controllers/built-in.md

+
+## Resource management controllers {#controllers-resource-management}
+
+* [Resource quota controller](/reference/access-authn-authz/admission-controllers/#resourcequota)


@sftim don't you need a /docs too ?

DanyC97 · 2019-07-20T09:13:23Z

content/en/docs/reference/controllers/certificate-approver.md

+
+When kubelet is setting up on a new node, kubelet will generate a CSR and submit it
+to the Kubernetes API server using its
+[bootstrap](https://kubernetes.io/docs/reference/access-authn-authz/bootstrap-tokens/)


@sftim pls use the relative url so it does work for localization too ;)

DanyC97 · 2019-07-20T09:31:31Z

content/en/docs/reference/controllers/node.md

+all the pods from the node (using graceful termination) if the node continues
+to be unreachable. (The default timeouts are 40s to start reporting
+ConditionUnknown and 5m after that to start evicting pods.) The node controller
+checks the state of each node every `--node-monitor-period` seconds.


@sftim imo i'd turn into a number list the first, second and third roles, easy to read

DanyC97 · 2019-07-20T09:35:04Z

content/en/docs/reference/controllers/node.md

+
+In most cases, node controller limits the eviction rate to
+`--node-eviction-rate` (default 0.1) per second, meaning it won't evict pods
+from more than 1 node per 10 seconds.


@sftim imo i find that we could maybe reword it a bit like

won't evict pods from more than 1 node during 10 seconds window

kbhawkey · 2019-07-21T16:09:00Z

content/en/docs/reference/controllers/daemonset.md

+of the the DaemonSet the Pod belongs to.
+
+If it's managing a Pod on a Node that no longer matches the DaemonSet,
+or where the Node no longer exists, the controller will remove that Pod.


What is it?

kbhawkey · 2019-07-21T16:12:38Z

content/en/docs/reference/controllers/volume-persistentvolumeclaim.md

+{{% /capture %}}
+
+{{% capture body %}}
+


General comment for all pages:
Can you add a ## Controller behavior section so that the content is consistent with the other pages?

content/en/docs/reference/controllers/ttl.md

content/en/docs/reference/controllers/serviceaccount-token.md

kbhawkey · 2019-07-21T16:29:20Z

content/en/docs/reference/controllers/serviceaccount-token.md

+{{% capture overview %}}
+
+One of a pair of controllers for the {{< glossary_tooltip text="ServiceAccount" term_id="service-account" >}}
+resource.


remove resource?
A ServiceAccount Token Controller generates and assigns API access tokens for a ServiceAccount.

sftim · 2019-07-24T06:27:17Z

This should help a little with (closed) issue #10160, about documenting NodeLease.

content/en/docs/reference/controllers/built-in.md

bradtopol · 2019-07-28T14:34:06Z

content/en/docs/reference/controllers/built-in.md

+runs separately from the kube-controller-manager. This separation helps
+with control plane performance.
+
+The controllers that run inside kube-controller-manager are:


The transition on the page from "The controllers that run inside kube-controller-manager are:" to then going to a bold heading of "Controllers for running workloads on Kubernetes" looks really weird. Check out https://kubernetes.io/docs/setup/ which shows a nice transition from a list of topics (Learning Environment, Production environment) to their sections below the introductory paragraph. The https://kubernetes.io/docs/concepts/ also as some nice examples of how to do this as well

Thanks for your feedback on this.

sftim · 2019-07-31T10:18:38Z

Something that occurred to me a little while ago: possibly, this documentation could live as reference documentation in kubernetes/kubernetes

I'll continue with this approach for now, if people reading this like the above idea though I can look into taking a different tack.

sftim · 2019-08-26T15:15:32Z

Didn't get round to this yet. I still plan to!

zacharysarah · 2019-10-10T00:24:15Z

@sftim Please feel free to reopen this when you're ready!

/close

k8s-ci-robot · 2019-10-10T00:24:17Z

@zacharysarah: Closed this PR.

In response to this:

@sftim Please feel free to reopen this when you're ready!

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

sftim · 2019-10-13T21:59:50Z

/retitle Add reference documentation for built-in controllers

sftim · 2019-10-14T07:51:18Z

Rebased & tweaked
/reopen

k8s-ci-robot · 2019-10-14T07:51:19Z

@sftim: Failed to re-open PR: state cannot be changed. The 20190711_add_controller_reference_pages branch was force-pushed or recreated.

In response to this:

Rebased & tweaked
/reopen

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

k8s-ci-robot requested review from stewart-yu and xiangpengzhao July 11, 2019 07:44

k8s-ci-robot assigned zparnold Jul 11, 2019

jaypipes suggested changes Jul 16, 2019

View reviewed changes

sftim changed the title ~~Add reference documentation for built-in controllers~~ [WIP] Add reference documentation for built-in controllers Jul 16, 2019

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jul 16, 2019

sftim mentioned this pull request Jul 16, 2019

Update Garbage Collection Docs #4510

Closed

2 tasks

sftim force-pushed the 20190711_add_controller_reference_pages branch from 44a63a9 to 038645a Compare July 16, 2019 20:55

sftim changed the title ~~[WIP] Add reference documentation for built-in controllers~~ Add reference documentation for built-in controllers Jul 16, 2019

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jul 16, 2019

jaypipes approved these changes Jul 18, 2019

View reviewed changes

sftim force-pushed the 20190711_add_controller_reference_pages branch 2 times, most recently from d432671 to 7cf5a57 Compare July 19, 2019 08:29

DanyC97 reviewed Jul 20, 2019

View reviewed changes

kbhawkey reviewed Jul 21, 2019

View reviewed changes

content/en/docs/reference/controllers/ttl.md Outdated Show resolved Hide resolved

kbhawkey reviewed Jul 21, 2019

View reviewed changes

content/en/docs/reference/controllers/serviceaccount-token.md Show resolved Hide resolved

kbhawkey reviewed Jul 21, 2019

View reviewed changes

sftim changed the title ~~Add reference documentation for built-in controllers~~ [WIP] Add reference documentation for built-in controllers Jul 22, 2019

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jul 22, 2019

sftim force-pushed the 20190711_add_controller_reference_pages branch 2 times, most recently from 2ef10d7 to f884084 Compare July 24, 2019 09:25

bradtopol reviewed Jul 28, 2019

View reviewed changes

content/en/docs/reference/controllers/built-in.md Show resolved Hide resolved

bradtopol reviewed Jul 28, 2019

View reviewed changes

sftim force-pushed the 20190711_add_controller_reference_pages branch from f884084 to bab6332 Compare July 28, 2019 15:20

sftim mentioned this pull request Aug 3, 2019

Reword Service Accounts docs #14681

Closed

sftim mentioned this pull request Aug 26, 2019

Add concept page about Controllers #15733

Merged

Add reference documentation for built-in controllers

c96ed15

sftim force-pushed the 20190711_add_controller_reference_pages branch from bab6332 to c96ed15 Compare October 1, 2019 11:27

sftim mentioned this pull request Oct 7, 2019

Issue with k8s.io/docs/reference/command-line-tools-reference/kube-controller-manager/ #15272

Closed

k8s-ci-robot closed this Oct 10, 2019

k8s-ci-robot changed the title ~~[WIP] Add reference documentation for built-in controllers~~ Add reference documentation for built-in controllers Oct 13, 2019

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 13, 2019

sftim mentioned this pull request Oct 14, 2019

[WIP] Add controller reference pages #16885

Closed

sftim mentioned this pull request Nov 21, 2021

Improvement for k8s.io/docs/concepts/overview/components/ #30582

Closed


		### Namespace lifecycle controller {#controller-namespace}

		When you (or any Kubernetes API client) remove a {{< glossary_tooltip term_id="namespace" >}},


		### Taints and Tolerations

		the controller automatically adds the following


		## Resource management controllers {#controllers-resource-management}

		* [Resource quota controller](/reference/access-authn-authz/admission-controllers/#resourcequota)

Add reference documentation for built-in controllers #15374

Add reference documentation for built-in controllers #15374

Conversation

sftim commented Jul 11, 2019 • edited Loading

k8s-ci-robot commented Jul 11, 2019

sftim commented Jul 11, 2019

sftim commented Jul 11, 2019

netlify bot commented Jul 11, 2019 • edited Loading

jaypipes left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim Jul 16, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lavalamp commented Jul 16, 2019

sftim commented Jul 16, 2019

sftim commented Jul 16, 2019

jaypipes left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kbhawkey commented Jul 19, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DanyC97 Jul 20, 2019 • edited Loading

Choose a reason for hiding this comment

DanyC97 Jul 20, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kbhawkey Jul 21, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim commented Jul 24, 2019

bradtopol Jul 28, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim commented Jul 31, 2019

sftim commented Aug 26, 2019

zacharysarah commented Oct 10, 2019

k8s-ci-robot commented Oct 10, 2019

sftim commented Oct 13, 2019

sftim commented Oct 14, 2019

k8s-ci-robot commented Oct 14, 2019

sftim commented Jul 11, 2019 •

edited

Loading

netlify bot commented Jul 11, 2019 •

edited

Loading

sftim Jul 16, 2019 •

edited

Loading

DanyC97 Jul 20, 2019 •

edited

Loading

DanyC97 Jul 20, 2019 •

edited

Loading

kbhawkey Jul 21, 2019 •

edited

Loading

bradtopol Jul 28, 2019 •

edited

Loading