Need top-level Controllers concept guide

[erictune]

This is a...

• Feature Request
• Bug Report

Problem:

No overarching Concept guide for controllers.

Proposed Solution:

Write one.

Page to Update:
New page to be added.

We have Concept docs for various controllers:

• docs/concepts/workloads/controllers/deployment.md
• docs/concepts/workloads/controllers/daemonset.md
• docs/concepts/workloads/controllers/replicaset.md
• docs/concepts/workloads/controllers/replicationcontroller.md
• docs/concepts/workloads/controllers/statefulset.md

We have Tasks for types of applications:

• docs/tasks/run-application/run-single-instance-stateful-application.md
• docs/tasks/run-application/run-stateless-application-deployment.md
• docs/tasks/run-application/run-replicated-stateful-application.md

We do not have an overarching doc that covers the following use cases:

• To define what we mean by the word controller.
• To help the users select the right one
• To explain concepts common to all controllers.
• To explain that there are built-in controllers, but that users can write their own (Operators).

@kubernetes/sig-apps-feature-requests

[erictune]

There is an incomplete list of controllers in docs/concepts/workloads/pods/pod-lifecycle.md

[erictune]

Common responsibilities for Kubernetes controllers:

• Kubernetes controllers automatically create replacement pods in the face of node failures.
• Kubernetes controllers aggregate status of their pods, so that the CLI and UI can summarize.
• and so on.

[enisoc]

+1 I would have liked to link to such a doc from #4071.

[erictune]

Also, this doc could talk about roll-forward and back in a general way, across SS, DS, Deployment, RS. And ControllerRevision.

[erictune]

Started a draft for this here:
https://docs.google.com/document/d/1jDPTKIRUf_UaVUu_BNu9IxXZR61rZ4MLPDRDWOevczg/view

Collecting content.

[metmajer]

@erictune: this is going to be a very valuable feature. Is there any way I could help out with this PR?

[markmandel]

How can I also get involved? I think it would be great if this resource existed - especially separate from CRDS (as they may not necessarily go together). I have a huge list of external examples and resources I used to learn about Controllers, happy to add them to the google doc if it helps / review / whatever.

Here is my Friction Log if it helps.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[erictune]

/remove-lifecycle stale

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[nikhita]

/remove-lifecycle stale

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[nikhita]

/remove-lifecycle rotten

still relevant.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[erictune]

/remove-lifecycle stale

…

On Sun, Dec 23, 2018 at 10:56 PM fejta-bot ***@***.***> wrote: Issues go stale after 90d of inactivity. Mark the issue as fresh with /remove-lifecycle stale. Stale issues rot after an additional 30d of inactivity and eventually close. If this issue is safe to close now please do so with /close. Send feedback to sig-testing, kubernetes/test-infra and/or fejta <https://github.com/fejta>. /lifecycle stale — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#4135 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AHuudlau5scQUhpHqRY4JsFhSJV4aY2Yks5u8HqbgaJpZM4N-sN6> .

[bradtopol]

@markmandel @metmajer @erictune We would love to see this content get completed. Would one of you be willing to take the lead on generating the content? I can help with any questions you may have on submitting a PR

[erictune]

Linking to this would be a good start: https://book.kubebuilder.io/basics/what_is_a_controller.html

…

On Mon, Feb 18, 2019 at 2:50 PM Brad Topol ***@***.***> wrote: @markmandel <https://github.com/markmandel> @metmajer <https://github.com/metmajer> @erictune <https://github.com/erictune> We would love to see this content get completed. Would one of you be willing to take the lead on generating the content? I can help with any questions you may have on submitting a PR — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#4135 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AHuudjgRRUJS9igsi1l4oEi88bUpqn0oks5vOy4ngaJpZM4N-sN6> .

[sftim]

I'm sketching out how to do this. I won't /assign it to myself; if anyone wants to join in, I'll be happy to collaborate.

[sftim]

/language en

[sftim]

#12323 might be (very slightly) relevant here

[zacharysarah]

@sethmccombs 👋 Thanks for following up with @sftim.

[sftim]

I've got a big bunch of changes that apply cleanly to master.

I'm going to wait for Kubernetes v1.15 to be out and for the dust to settle. Then I'll make branches with subsets of the overall changes and send in pull requests (there could be several size/XXL PRs to come from this).

[zacharysarah]

@sftim 👋 Any updates?

[sftim]

I've been away-from-keyboard for a week. Will update this.

[bradtopol]

Thanks @sftim please feel free to ping me when its ready for review

[sftim]

/priority important-longterm

[sftim]

/status active

[sftim]

/close
Resolved by #15733
If there's part of the task still left to do, I recommend opening a new issue and referencing this closed one.

[k8s-ci-robot]

@sftim: Closing this issue.

In response to this:

/close
Resolved by #15733
If there's part of the task still left to do, I recommend opening a new issue and referencing this closed one.

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.