Umbrella issue - Revamping the Kubernetes Developer’s guide

[eduartua]

The contributor guide has been revamped. This is a mostly general guide for all who are getting ramped up on Kubernetes upstream contributions. We need to produce a section of that with the name “The developer guide”

As per #1919 and #892, and the content within the /devel folder, we have to decide a structure for the developer guide. It has to be in a way that new developers find it intuitive and well organized.

Primary goals:

• Have an inventory of everything inside the /devel folder.
• Update and clean up of /devel, some files have to be updated, moved or just deleted.
• Create a skeleton.
• Develope in a logical manner every skeleton point.

This issue is an umbrella tracking issue.

Skeleton draft

We are going to build this thinking of two personas:

1. Developers that want to contribute to the code base (kubernetes/kubernetes).
2. Developers that want to build apps over top of k8s.

This initial work will be focused on the understanding of the internals required by persona 1. It is important to have a sense of how they come together to form a functional cluster and how that is used.

As a new developer, the following are the things I would like to read first in order to become familiar with the project:

1. Prerequisites

• Setting the dev environment - There is information about this but my feeling the first time I read it was that something was missing, something like a small example or tutorial testing dev tools after installation.

  1. Golang dev environment
  2. Keeping your golang install up to date
  3. Specify the software required with versions (e.g etdc version)

• Getting the code (git workflow)

  1. fork k8s repo on github
  2. where to put your k8s repo locally
  3. Environment variables to set

• Concepts to which you must have familiarity and sources.

2. Communication channels
   Where to ask for help or orientation - We have this in the contributing guide. SIGs, repos, mailing lists, IM/chat, meetings

3. Quick reference
   Here are the basic steps needed to get set up and contribute.

4. Status of Kubernetes branches
   A table with information like branch’s name, status about the kinds of contributions it accepts. Example: release branches that are N-3 only allow bug fixes, feature branches are used for feature work to be merged into master later, etc.

5. Code of Conduct

Both Persona 1 and 2 have in common the previous points.

Specific points for each persona:

Persona 1 (Code Contributor)

1. How to make a change to Kubernetes

• Understanding the architecture - Control Plane

  • General introduction of the Kubernetes API server
    1. Terminology and architecture diagram.
    2. API request flow and API Machinery.
    3. Interaction with internal and external objects; worker nodes, kubelet, etc.
    4. API Conventions
    5. Admission controller
    6. Webhooks
  • Kube and Cloud Controller Manager
    1. Overview of how the controller manager bundle programs with different jobs.
  • Communication
    1. Protocols (gRPC, protobuf)
  • Scheduler
    1. Resource requirements
    2. Quality of services requirements
    3. Policy constraints
    4. Affinity and anti-affinity specifications
    5. Data locality
    6. Inter-workload interference
    7. Deadlines
  • How the state of kubernetes objects is managed
    1. Etcd intro
    2. Cluster state
    3. Communication between components via etcd
  • Kubelet
  • Kube-proxy
  • Container Runtime
    Introduction to the assumptions kubernetes makes about the infrastructure resources where it is hosted, and overview of compute, network, storage abstractions:
    1. Compute
    • CRI
    • Resource management
    2. Network
    • CNI
    • DNS related components
    • Resource management
    3. Storage
    • CSI
    • Volumes management
    • StatefulSets
    • Resource management
  • System components (user side)
    1. Kubectl
    2. Client-go
    3. Parts or elements involved in user and admin configuration.

• Building

  1. Description of kubernetes build process
  • Guidelines on when/if there should be used make TARGET
  2. How to build using Bazel

• Deploying and running Kubernetes code

  1. Bootstrapping the cluster
  • Cluster component configuration and secrets
  • Starting cluster services
  2. Bootstrapping the cluster with kubeadm
  3. A short tutorial of building

• Testing

  1. Description of testing and status of coverage test
  • Unit test
  • e2e
  2. integration
  3. Adding a test
  4. Benchmarks

• Debugging
  A brief description of the best practices and methods used. This information can be taken from subprojects with well defined debugging processes.

• Submitting a Pull Request
  Lifecycle of a PR

  • Opening a PR
  • Code review
  • Tutorials/model PRs for making changes

2. How to work within the community to get agreement on some change to the code base.

3. Others

• Go vendoring
• Release process
• Kubernetes enhancement proposals

Persona 2 (Platform Developer)

Extending kubernetes.

• Extension points
  1. Kubectl Plugins
  2. API Access Extensions
  3. Custom controllers for native resources
• Api Extensions
  1. Custom Resource Definitions (CRDs)
  2. Aggregated API Servers
• Infrastructure Extension
  1. Network Plugins
  2. Storage Plugins
  3. Compute Extensions
  4. Scheduler Extensions

To help out

1. The first thing we need to create is a definitive skeleton or toc. If you are part of a SIG that has valuable information regards the developer's guide, It is very helpful to make proposals to the points mentioned above.
2. If you know a file is outdated or lacks information, please comment here.
3. Ping me or this issue so I can update it with changes.
4. In case you are helping to re-write, move, and/or remove a linked reference, make a PR pointing out if it is finished or it is in partial completion, and finally referring to this issue.
5. Lastly, all files used to build this guide will live in community/contributors/devel/guide.

Files to review

Files in the contributors/devel need to be scrubbed for the developer guide. Non-developer relevant topics should be moved over to other parts of the contributor repo or just be deleted. There might be some calls to make.

Check for:

Duplicate content that can be removed.
Might not be appropriate for the developer guide.
Might need to be deleted or combined with another document.
Might be blocked on waiting on another part of the contributor guide to be finished.
(Thanks to Guin here)

Pages to update

https://github.com/kubernetes/community/tree/master/contributors/devel/README.md

Folders to update

https://github.com/kubernetes/community/tree/master/contributors/devel

Inventory

• adding-an-APIGroup.md - referes to api_changes.md, so references to this files has to be changed to api_changes.md and finally removed.
• api_changes.md - Should be part of developer guide (Point 1.a)
• api-conventions.md - This is going to be part of the developer guide, I think we must segment the information oriented towards either the core devs or platform devs.
• architectural-roadmap.md - This will be part of the developer guide, revision in progress.
• arch-roadmap-1.png
• Automation.md - This document has to be part of k/test-infra - it won’t be part of the developer guide.
• bazel.md - The default build process is using kubernetes development helper scripts - is going Bazel to become default?
• cherry-picks.md - Should be part of the guide, but where? - move to https://git.k8s.io/sig-release/release-process-documentation
• client-libraries.md - filed moved to docs (to be deleted from /devel).
• collab.md - Talks about collaborative development. (To remove)
• component-config-conventions.md - This doc serves as a design guideline for component configurations. We can reference this document in the main content of the developer guide.
• conformance-tests.md - This document has testing information that can be integrated into the guide.
• container-runtime-interface.md - It has to be part of the guide.
• controllers.md - It has valuable information for developers, we can take that info and then move it into the docs.
• cri-container-stats.md - Take info to the README, then consider deletion or to merge with CRI main document.
• cri-testing-policy.md - Should be part the developer guide.
• cri-validation.md - Should be part the developer guide.
• development.md - This file contains info that can be put in the README and then it can be deleted.
• e2e-node-tests.md - To review with sig testing, it has to be in the dev guide.
• e2e-tests.md - To review with sig testing, it has to be in the dev guide.
• event-style-guide.md - This is a design document, it can be part of the dev guide.
• flaky-tests.md - To decide with sig testing what can be taken to be part of the dev guide.
• flexvolume.md - Has to be part of the dev guide.
• generating-clientset.md - Falls within Persona 2? To be moved.
• getting-builds.md - This can be merged into the README.
• godep.md - It has to be in the dev guide.
• gubernator.md - Great for the debugging part, keep it.
• help-wanted.md - This document has to be called somewhre in the How to contribute part.
• how-to-doc.md - this document has to be in the contributor guide. Ask guin.
• instrumentation.md - to include in the guide, has good info about metrics and instrumentation.
• issues.md - To be deleted.
• kubectl-conventions.md - it definitely has to be part of the developer guide.
• kubelet-cri-networking.md - this document is two years old, it has to be reviewed and updated.
• kubemark-guide.md - Needs revision too (state of running kubemark clusters on cloud providers). It should be part of the dev guide.
• logging.md - Not sure about this. I'll ask to Christopher Hein.
• mesos-style.md - This document compares two architechtures and explains how to build one them with Kubernetes. It has to be part of the guide.
• node-performance-testing.md - Ask sig-testing if we can move this. It looks like an doc for operators. Merge into the README is an option too.
• on-call-federation-build-cop.md - Testing document, review with sig-testing.
• OWNERS - Skip.
• profiling.md - Should be part of the developer guide.
• README.md - This guide.
• release-cycle.png - Skip.
• release-lifecycle.png - Skip.
• release.md - Is going to be part of the dev guide.
• running-locally.md - This will be deleted, some of information will be taken to the main README.
• scheduler_algorithm.md - Is going to be part of the dev guide.
• scheduler.md - Is going to be part of the dev guide.
• staging.md - This can be added to the vendoring documentation.
• strategic-merge-patch.md - Good content for the dev guide, but it needs to be updated.
• testing.md - Should be part of the dev guide - section testing.
• update-release-docs.md - To be deleted.
• updating-docs-for-feature-changes.md - To be deleted.
• vagrant.md - Support for vagrant has been removed in 1.10. To be archived.
• welcome-to-kubernetes-new-developer-guide.md - To be deleted.
• writing-a-getting-started-guide.md - deleted.
• writing-good-e2e-tests.md - Should be part of the dev guide - section testing.

I will be updating this issue on a daily basis.

[eduartua]

/sig contributor-experience
cc @parispittman @nikhita

[nikhita]

Looks great, @eduartua! ❤️

/sig contributor-experience
/kind feature

I know its more "developer guide" than contributor guide but would be useful to find/triage issues, so:
/area contributor-guide

[eduartua]

I rewrote what I had in the doc, so this feels more like a real guide. We need to come to a consensus about the skeleton.

[guineveresaenger]

Thank you so much for this, @eduartua! A couple thoughts, in no particular order:

At the danger of repeating others, I want to point out the Python Developer Guide as a fantastic example of a very useable, helpful dev guide.

Please ping me (here or on Slack) about files that are more a contributor guide topic than a technical dev guide topic that need to be deleted or still incorporated - I'm thinking help-wanted, issues and collab, for instance, are either already elsewhere, or need to be moved/deleted.

In addition to cherry-picks, all release related processes should live in k/sig-release and be linked (and actually from the contrib guide, since it's really more of a process and less of a technical thing).

I'm super excited for a top-level README to tell me where to build WHAT. 😉

[guineveresaenger]

Found a couple related issues; perhaps add to the list of files above:
#1537 (regards testing.md)
#2759 (regards e2e tests)

[tpepper]

Looking good to me for a start! A few small comments:

The sections:

• Building and running Kubernetes
• Deploy process

might better be:

• Building Kubernetes
• Deploying and running your Kubernetes code

In the deploy and run section I think some treatment needs given to the multitude of host platforms on which one might run. This also then relates to cloud provider code. I'm curious if @andrewsykim has thoughts on where best cloud provider developer content might fit into the guide.

The Testing section probably should include a "conformance" section in addition to unit, integration and e2e. I see them as a sort of continuum: unit, integration, e2e, conformance.

Debugging: This is a very broad section. It might make sense to seed some sub-categories, eg: control plane component specific, network communications, and client side.

Security: Especially thinking about recent CVEs, I think it's critically important to give developers a sense of the general thread model against a running Kubernetes cluster and the implications
this has on coding. Maybe this is a cross-component discussion under "Understanding the architecture - Control Plane", but it might also be a set of content larger than that.

[eduartua]

Thank you @tpepper I will include those sections.

[markjacksonfishing]

I am going over the issues opened for similar items. They are
#155
#1644
#1899
#2441
#2759
#3749

All of this in some way connected in terms of the needs. @eduartua really summed that up in this issue so I would like to incorporate the the above mentioned issues in to this one. That does not mean close those issues bit rather address each one of those issues with @eduartua work here.

The tasks for this body of work as I see it is as followed:

• [] Digest and understand the work @eduartua has done here (ETA: EOD 9/15)
• [] Create outline with the work here and draw dotted lines to the issues where appropriate (ETA: EOD 9/15)
• [] For items that have no dotted line, I will address them in my outline as well as reference the given issue pointing them here (ETA: EOD 9/22)
• [] Start work on missing items (ETA: EOD 10/6)
• [] Start the review process (ETA: EOD 10/13)

Note The ETA are not solid and may slip here and there

[markjacksonfishing]

I am starting my online documentation here: https://docs.google.com/document/d/1D7CZZLqKrByrPrXytmf1q5YWzTURL_r7_3KH9iCPgOE/edit?usp=sharing

[markjacksonfishing]

I continue to work on this. My hope is to have an initial pr in by end of this week

[markjacksonfishing]

@vishakhanihore kindly see the above

[markjacksonfishing]

/assign @vishakhanihore

[k8s-ci-robot]

@markyjackson-taulia: GitHub didn't allow me to assign the following users: vishakhanihore.

Note that only kubernetes members, repo collaborators and people who have commented on this issue/PR can be assigned. Additionally, issues/PRs can only have 10 assignees at the same time.
For more information please see the contributor guide

In response to this:

/assign @vishakhanihore

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.

[ameukam]

/assign @vishakhanihore

[k8s-ci-robot]

@ameukam: GitHub didn't allow me to assign the following users: vishakhanihore.

Note that only kubernetes members, repo collaborators and people who have commented on this issue/PR can be assigned. Additionally, issues/PRs can only have 10 assignees at the same time.
For more information please see the contributor guide

In response to this:

/assign @vishakhanihore

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.

[vishakhanihore]

/assign

[vishakhanihore]

/lifecycle frozen

[markjacksonfishing]

@vishakhanihore I am going to remove myself from assigned since you are now working on this. If you need any help please do let me know. Thanks kindly 😺

[markjacksonfishing]

/unassign @markyjackson-taulia

[markjacksonfishing]

We need to break this down into workable chunks. This should be a focus meeting to do this

[mrbobbytables]

I think this is safe to close for now. A good chunk has been merged or closed. We probably need to revisit it from the beginning :x

/close

[k8s-ci-robot]

@mrbobbytables: Closing this issue.

In response to this:

I think this is safe to close for now. A good chunk has been merged or closed. We probably need to revisit it from the beginning :x

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