Kubernetes Contributors – New Contributor Course

Docs: Section 1: Starting Out

Mon, 01 Jan 0001 00:00:00 +0000

Welcome to Kubernetes!

Welcome to the New Contributor course for Kubernetes!

Section 1: Starting Out

Each unit of this course consists of a slideshow and links to resources. Take your time reading the materials, and feel free to reach out to the community with questions.

We look forward to your contributions!

What you are about to learn

This first unit is all about starting out in the Kubernetes community. By the end of this unit, you will:

Understand the organization of the K8s community, special interest groups, committees, and working groups.
Communicate effectively with the community.
Understand and be able to work with the K8s code of conduct and community values.

Who exactly is a contributor?

Kubernetes contributors bring a wide range of talents, skills, services, and ideas to the community. They:

Write documentation
Write and review code
Participate in the community
Participate in special interest groups
AND MORE!

Everybody’s contributions are welcome in the Kubernetes community!

What are the core values of the Kubernetes community?

The Kubernetes community adheres to the following principles:

Distribution is better than centralization
Community over product or company
Automation over process
Inclusive is better than exclusive
Evolution is better than stagnation

What behavior is expected of contributors?

The Kubernetes community strives to be safe, respectful and inclusive. We expect all contributors to:

Abide by the CNCF Code of Conduct
Help foster an open and welcoming community
Respect their fellow contributors.

Learn more about the Kubernetes community values.

What is the CNCF Code of Conduct?

“The Kubernetes Code of Conduct is in effect, so please be excellent to each other.” — Jorge Castro, 2020 SIG ContribEx co-chair

The Code of Conduct serves as a set of rules used by the Kubernetes community to uphold our core values and establish a safe, respectful and inclusive environment.

Our code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.

Who oversees and enforces the Code of Conduct?

The Code of Conduct Committee oversees and handles all incidents and responses regarding code of conduct issues and violations.

Read about the committee’s reporting and response process.

How is the Kubernetes community organized?

Most community activity is organized into three areas:

Special Interest Groups (SIGs),
Working Groups
Committees

What are Special Interest Groups?

We are organized primarily into Special Interest Groups, or SIGs. Each SIG is composed of members from multiple companies and organizations. In addition, each SIG:

Works to advance the project with respect to a specific topic, such as Networking or Documentation.
Has a charter that specifies its scope, responsibilities, and governance.

What is a working group?

A working group facilitates topics of discussion that cross SIG lines. They are a vehicle for consensus building. A working group:

Provides a formal avenue for collaboration around a common problem,
Crafts a balanced position,
And then disbands!

What is a committee?

Some topics, such as Security or Code of Conduct, require discretion. Committees do not have open membership and do not always operate in the open.

The steering committee forms committees as needed.
All committee members must be community members.
Like a SIG, a committee has a charter and a chair.

Where can I learn more?

The Kubernetes Community Resources page has links to documents that describe our community structure and governance.

The Community Groups page lists all current SIGs, working groups, and committees.
The governance document drills down into more of the specifics.

Onboarding Index | Next Section

Docs: Section 2: Getting Into GitHub

Mon, 01 Jan 0001 00:00:00 +0000

Section 2: Getting Into GitHub

What you’re about to learn

The first step to being a Kubernetes contributor is getting into GitHub! After this unit, you will:

Understand GitHub capabilities and how Kubernetes uses it
Understand fork and clone and be able to perform these on a repository
Be able to complete the contributor license agreement (CLA) and make a first pull request

What is GitHub?

GitHub is a web service for managing software development with Git.
It provides bug tracking, task management, hosted development environments, continuous integration, and other important features.
GitHub hosts the source code for many open source projects, including Kubernetes.

Working with GitHub is straightforward, but if you are new to it, it can seem complex. We want to make the process as easy as possible for you!

How does Kubernetes use GitHub?

As one of the largest open source projects with thousands of contributors, Kubernetes relies on GitHub for organization and sharing information.

Kubernetes hosts multiple projects on GitHub, including Kubernetes itself and the Kubernetes Community repository.
Contributions are managed using GitHub features such as issue tracking and pull requests.
Organization membership is managed using GitHub accounts.
There are four GitHub organizations used by the Kubernetes project: kubernetes, kubernetes-sigs, kubernetes-csi, and kubernetes-client. They contain over 300 projects.

How do I set up my GitHub account?

You probably already have a GitHub account, but just in case:

If you don’t have one yet, create a GitHub account on their sign up page. The Free plan works fine!
Official members of the Kubernetes community need their GitHub accounts to meet certain other requirements.

Which GitHub features will I use as a contributor?

Now it’s time to learn all of these extra GitHub features.

Kubernetes uses a fork and pull collaborative development model.
To get started, you will need to understand:
- Pull requests
- Issue management
Both will be covered in this course!

What is a Contributor License Agreement (CLA)?

Once you are ready to contribute, you will have to jump through one small legal hoop, but we make it as easy as possible.

The Kubernetes CLA gives Kubernetes the permission to use content and source code that you contribute.
Kubernetes can only accept original source code from CLA signatories.
If you change employers and still contribute to Kubernetes, you need to update your CLA.

How do I sign a CLA?

After you make your first pull request, a GitHub bot will walk you through the process.
The process is outlined in the Community repository.

Okay, you are ready to make your first pull request!

Visit the Kubernetes Contributor Playground repository.
Use the “Fork” button in the upper right corner to fork the repository to your own account.
In your new fork, create a new branch.
Follow the directions to clone the repository to your workstation.
Make edits in your new branch and push those changes to your fork.
Back on GitHub, create a pull request from your fork.

Onboarding Index | Next Section

Docs: Section 3: Pull Requests

Mon, 01 Jan 0001 00:00:00 +0000

Section 3: Pull Requests

Objectives

This unit will teach you all about how to submit and manage pull requests for the different Kuberenetes repositories. By the end of this unit, you will be able to:

Reference and operate in the Kubernetes GitHub workflow
Recognize common bots and their messages
Respond to code comments and test failures

What is a pull request?

Before we start teaching you how to use pull requests, we should tell you what they are!

A pull request is how you communicate that you have a Git branch filled with completed changes that you wish to merge with a repository on GitHub.
Pull requests allow contributors to collaborate, review code, run tests, and confirm critical details before new changes are integrated into a project.
You will frequently see a pull request called a “PR”.
Kubernetes relies heavily on GitHub’s pull request system. The GitHub docs have a thorough dive into pull requests. Go deeper!

Where do I make a pull request?

Before creating a pull request, you should:

Figure out which repository and SIG is responsible for your changes.
Check to see if an issue already exists for your change, and if not open one.
Consider attending a SIG meeting and adding your issue to the agenda.
Discuss your issue on Slack or on the mailing list.

How do I open a pull request?

You’ll want to review the basic pull request process you learned at the end of Unit 2.

Every pull request starts with a branch on your fork of a Kubernetes project.
You can create pull requests using the GitHub website, any of the GitHub tools, or some third-party GitHub interfaces.
Take time to review the GitHub Workflow documentation.

How does Kubernetes use pull requests?

Kubernetes generally follows the standard GitHub pull request process, but there is a layer of additional Kubernetes specific (and sometimes SIG specific) differences.

Right away, a bot starts adding automated labels to your PR.
The bot helps you facilitate PR review. You can use these commands to interact with the bot.
You can learn more about the Kubernetes pull request process here.

How does the pull request review process work?

Anyone can review a documentation pull request. Code pull requests require approved reviewers.
In addition to code-related concerns, pull request reviews also look at:
- Language and grammar
- Content
- Potential website changes

You can respond to comments from reviewers through comments or additional changes that you push to your development branch. We will cover code review in a later unit.

When are my pull requests run through tests?

A bot runs your PR through a few pre-commit tests automatically.
The results of these tests will be posted to your pull request’s discussion automatically.
Once a reviewer adds the ok-to-test label, the bot will run your changes through end-to-end (e2e) tests.

What do I do if my test fails?

The test results should give some indication of what went wrong.
Make changes, push them to your branch, and continue iterating through the pull request process.

We will cover tests in more detail in a later unit.

Onboarding Index | Next Section

Docs: Section 4: Issues Management and Triage

Mon, 01 Jan 0001 00:00:00 +0000

Section 4: Issues Management/Triage

What you’re about to learn

This unit will help you get started with issue management across the Kubernetes GitHub repositories. By the end, you’ll:

Understand and locate the issues management and triage tags
Know where bugs are reported and how they are triaged
Be able to understand how to prioritize work based on issues
Be able to locate the security response committee for security issues

How does Kubernetes use GitHub issues?

Contributors and end users use issues for a variety of reasons:

Reporting bugs
Tracking tasks
Community organization
Discussion

You can identify different types of issues with their labels (AKA tags).

What are labels?

Labels are a GitHub feature used to organize issues and pull requests.
They allow you to quickly identify at a glance what type of issue or pull request you are looking at.
They are helpful when using the search feature to look for issues.
Labels are also called tags!

Where can I find all of the Kubernetes issues?

Issues are managed in many of the different Kubernetes GitHub repositories, and can be accessed via the Issues tab. Here are the most common:

What are some common labels?

There are A LOT of different labels, and both issues and pull requests (PRs) can have their own labels. Here are a few you will run into frequently.

`help wanted` and `good first issue`	Use these to figure out what to work on first or next.
`needs-sig` and `needs-triage`	Bugs that haven't been assigned or triaged
`lgtm`	"Looks good to me", a PR is ready to merge.
`approved`	Indicates a PR has been approved by an approver from all required OWNERS files.
`sig/*`	Each Special Interest Group (SIG) has their own label.
`area/*`	For issues and PRs that apply to a specific area of Kubernetes
`kind/*`	Label different kinds of issues or PRs, such as bugs, API changes, or support requests.

Which labels will you have to worry about?

That list of labels is really long, but you won’t need to worry about most of them at the beginning.

When starting out, you just need to look for issues labeled help wanted or good first issue.
Many labels are managed automatically by bots.
The community will suggest other labels for issues, or add them for you.

What is triaging?

Triaging is the process where new issues and requests are reviewed and organized.
Factors considered include priority/urgency, SIG ownership of the issue, and the kind of issue (bug, feature, etc.).
Triage can happen asynchronously and continuously, or in regularly scheduled meetings.
Each SIG may have its own approach to triaging.

Triaging is critical for keeping track of new issues, bugs, and problems. Read the Issue Triage Guidelines for more information.

How are issues prioritized?

Each SIG is responsible for triaging and deciding on the priority of issues that affect their area.

The lowest priority is priority/awaiting-more-evidence
The highest priority issues are labeled priority/critical-urgent and require somebody to work on them immediately.

What is the Security Response Committee?

The Security Response Committee (SRC) is responsible for triaging and handling the security issues for Kubernetes.
The SRC is also responsible for disclosing vulnerabilities to the public.
Report to them when you think you have discovered a potential security vulnerability in Kubernetes.

You can learn more about Kubernetes security disclosure and reporting here.

Onboarding Index | Next Section

Docs: Section 5: Getting Started with Kubernetes Development

Mon, 01 Jan 0001 00:00:00 +0000

Section 5: Getting Started with Kubernetes Development

What you’re about to learn

It’s time to set up a development environment so you can build Kubernetes. By end of this unit, you will:

Know the various environments for building and developing Kubernetes
Know where to find the Kubernetes Development Guide

What are your options for a development environment?

There are three primary options, all with their own benefits and drawbacks.

Building Kubernetes with Docker
Building Kubernetes on your local OS and shell environment
Building Kubernetes with GitHub Codespaces

Why build with Docker?

This method uses a containerized build environment. There are some good reasons to use it:

Official releases are built using Docker containers.
Initial setup is simple.
This provides a very consistent build and test environment.

Read more about this method in Building Kubernetes.

Why build using a local OS?

This method takes the most effort to set up. But it has its own advantages:

You’ll have fine-grained control over all aspects of the build process.
There is no overheard from a container system like Docker.

To set this method up, follow the steps from the Development Guide.

Why build using GitHub Codespaces?

The newest method takes advantage of GitHub Codespaces to provide a container-based development environment.

All of your development resources (CPU, memory, and disk) are in the cloud.
The only tool you need to install locally is a web browser!

To build Kubernetes with Codespaces, follow the steps in this document.

What are the next steps?

Once you have a working development environment, you will be ready to develop and run tests against Kubernetes.

But first, we recommend that you become familiar with the Development Guide.

Onboarding Index | Next Section

Docs: Section 6: Testing

Mon, 01 Jan 0001 00:00:00 +0000

Section 6: Testing

This unit is all about the various types of tests, both automated and manual, in the Kubernetes project.

What you’re about to learn

By the time you’re done with this unit, you’ll:

Be able to locate the requirements for manual testing during development
Be able to respond to the automatic tests of bots for a pull request

Testing Kubernetes is pretty complicated. We will try to make it easy for you, but you might want to start by reading the Development Guide.

What are the different types of tests?

In the course of developing Kubernetes, you will interact with three different test types:

Unit tests
Integration tests
End-to-End tests

Let’s learn about each type of test!

Unit tests

Unit tests run against the smallest possible components of code, like an individual function or API calls.

Contributions with new significant functionality must come with unit tests!
Unit tests can use mock clients and servers to emulate aspects of the Kubernetes API for testing.

Integration tests

Integration tests make sure that components work together flawlessly as a group.

All significant features require integration tests—including kubectl commands.
Integration tests are able to test the behavior of the Kubernetes API without bringing up a whole cluster.
This makes integration tests more realistic than unit tests.

End-to-End tests

End-to-end (E2E) tests emulate an entire execution path across the entire application, from start to end.

E2E tests are the last signal to ensure end user operations match developer specifications.
Significant features should come with e2e tests.
- If you contribute a new feature without e2e tests, be prepared to explain your reasoning to your PR’s reviewers.

Who is responsible for Kubernetes tests?

“Developers! Developers! Developers!” — Steve Ballmer

Any contributor adding new functionality will be responsible for creating tests that validate their contribution.
Any contributor submitting a pull request will be responsible for making sure that tests run against their contribution—and pass!
SIG Testing is responsible for maintaining the test framework.

What is presubmission verification?

Presubmission is the phase before a pull request is created—the steps that you, the contributor, can take to maximize your PR’s chance of success.

Presubmission verification is a collection of checks that give your pull request the best chance of being accepted.
Developers need to run as many verification tests as possible locally.
Learn how to run them in the Development Guide.

How do I interact with unit tests?

Pull requests need to pass all unit tests.

Run them all from your development directory with make test
You can also run unit tests individually during the development process.
Read everything there is to know about unit tests in the Testing Guide.

How do I interact with integration tests?

Pull requests also need to pass all integration tests.

If you are testing locally, you might need to install extra software.
These tests are run from your development environment with make test-integration
Read Integration Testing in Kubernetes to learn more about this type of test.

How do I interact with end-to-end (E2E) tests?

E2E tests build test binaries, spin up a test cluster, run the tests, and then tear the cluster down.

Note: Running all E2E tests takes a very long time!

You will not need to run E2E tests for every pull request. The End-to-End Testing Guide is a great place to learn more.

How does testing affect my pull request?

You should run tests locally or in your development environment before submitting a pull request, because it will speed up the process.

The bots that process pull requests will run tests against your code!
When the tests fail, your pull request will stall.
You will need to use the /ok-to-test command to tell the bot to run tests again.

Read about the ok-to-test label in the Pull Request Process documentation.

Testing Resources

We’ve covered a lot of ground in this unit, and if you want to go deeper, here is a collection of all the resources we used.

Onboarding Index | Next Section

Docs: Section 7: Code Review

Mon, 01 Jan 0001 00:00:00 +0000

Section 7: Code Review

What you’re about to learn

In this unit, you will learn everything about getting your code contributions to Kubernetes reviewed. By the end of this unit, you will be able to:

Understand the role of code reviews in the lifecycle of a pull request.
Use your SIG process to get a senior contributor to review code for approval.

What is a code review?

A code review is when other developers examine proposed changes and additions to source code.

A code review validates new designs and implementations.
Code review can also help newer developers learn the intricacies and architecture of existing code.

Why are code reviews important?

Like testing, code reviews help make sure Kubernetes remains stable, reliable, and bug-free.

With our huge contributor base, we need great guardrails to keep our code in good shape.
Code reviews are a cornerstone of successful large software projects.
Code reviews make sure that at least two pairs of eyes examine everything before integration into the main branch.

Where does a code review fit into the process?

To understand code reviews, you need to understand pull requests first. Make sure you’ve finished that unit!

After you have submitted a pull request, the bot will assign two reviewers to your changes.
Their code reviews must be passed before your pull request will be accepted into the main branch.

Who can review my code?

Anybody can review your code, but only approved reviewers can add the lgtm label to your PR, which marks it as ready for merging.

Every SIG and section of the code base has its own approved reviewers.
The requirements for becoming an approved reviewer differ across SIGs.
- For an excellent example, read about SIG-Node approvers and reviewers.

How can I make sure my changes pass review?

There are a number of points to keep in mind while preparing your pull request for review.

Follow the project coding conventions.
Write good commit messages.
Break large changes into smaller patches that are easier to understand.
Label your PR appropriately.
Pay attention to the instructions the bot gives you.

The Contributor Guide has more guidelines and tips for passing reviews.

Help! My pull request isn’t getting any reviews!

If you need help finding reviewers for your pull request, try one of the following:

Post a message on the appropriate SIG’s Slack channel.
Ask for assistance on the #pr-reviews Slack channel.

Onboarding Index | Next Section

Docs: Section 8: Community

Mon, 01 Jan 0001 00:00:00 +0000

Section 8: Community

What you’re about to learn

It’s time to learn about communication and community among Kubernetes contributors. By the end of this unit, you will:

Understand the size, diversity, and capability of the Kubernetes community
Be able to interact with members productively
When to use email, when to use Slack, when to use GitHub issues, etc.
Know the venues for involvement, including Kubecon and SIG meetings.

How big is the Kubernetes contributor community?

The Kubernetes community has thousands of active contributors.

Take a look at the statistics!

Is every contributor a developer?

No! Kubernetes contributors take on all kinds of responsibilities and roles, including:

Writing documentation and blog posts
Coordinating volunteers
Event management
Project management
Issue triage
Managing communication tools

Communication moderation
Hosting meetups
Social media management
Public relations
Community education
New contributor training
And the list goes on!

What is the best way to communicate with my fellow contributors?

Every SIG, working group, and committee will have its preferred method of communication, but globally, the community uses:

Slack for synchronous communication and asking questions
GitHub issues for tracking changes to code and content
Mailing List(s) for long-form communication

What do I need to know about the mailing lists?

Community-wide notifications and discussions are always sent to the Kubernetes dev mailing list.

Joining the Kubernetes dev mailing list will ensure you can access documents and receive notifications impacting the whole community.

How do I join the Kubernetes Slack community?

The Kubernetes Slack server has over 500 channels!

First, get familiar with our Slack communication guidelines.
Then join our Slack server here!

What is the best way to communicate with each SIG?

Each SIG and Working Group has its favored method of communication. You can start in their Slack channel and ask around.

By working with a SIG, you will learn how its members communicate.
The Community Groups list is a great place to learn about communication preferences.
- This is also where you will learn about each group’s regularly scheduled meetings and how to attend.

How does the community use GitHub Issues and email to communicate?

Slack is excellent for most discussion and questions.

Issues that affect more than one group need to be discussed on the kubernetes-dev email list.
Decisions affecting a single group can be handled in GitHub.

How do I find out more about KubeCon and other in-person events?

While KubeCon is organized by the Cloud Native Computing Foundation (CNCF), we like to host a Contributor Summit alongside KubeCon.

You can learn more about the next Contributor Summit on our #contributor-summit Slack channel.
Find out more on our Events page.

Where can I learn more about communication in the community?

We have extensive guidelines and policies around our various communication channels.

Read the Kubernetes Communication Platform Guidelines and Policies.

Onboarding Index | Next Section

Docs: Section 9: Documentation

Mon, 01 Jan 0001 00:00:00 +0000

Section 9: Documentation

What you’re about to learn

This unit is about documentation, and by the end, you will:

Know where documentation is stored for Kubernetes
Understand the importance of localization
Understand the process and responsibilities for updating documentation
Know who is responsible for documentation
Locate the style guide and other guidance for writing documentation

How is the Kubernetes documentation organized?

The documentation for the Kubernetes project can be divided into a number of categories.

User-facing documentation
Community documentation
Special Interest Group (SIG) documentation

What is the user-facing Kubernetes documentation?

The user-facing documentation deals with how to install, configure, and operate Kubernetes and its subsystems.

It also includes API documentation.
It is available on the Kubernetes website.

What is the community documentation?

The community documentation is an informal collection of docs maintained by contributors. It consists of:

What is the SIG documentation?

Each SIG is in control of some aspect of Kubernetes development, infrastructure, or community.

They each document their domains and processes in different ways.
Consequently, the documentation is stored in many different places and varies widely in how complete it is.
Here are some of the best:
- SIG Release handles the process of releasing new Kubernetes versions.
- You already saw lots of SIG Testing documentation in a previous unit.

Is the documentation available in other languages?

Kubernetes is used by developers and DevOps people all over the world. It is important that the documentation is available in other languages.

Can you write documentation in a language that isn’t English? We would love your help!
Access user-facing documentation in other languages from the documentation pages.

Who is responsible for the documentation?

YOU ARE!

No, seriously!

All of the contributors are responsible for documentation.

Any user-facing changes should be documented.
Any developer-facing changes should be documented.
Any changes in SIG processes should be documented.

When you make a change, document it.

What is the process for updating the documentation?

Documentation updates follow the same process as any other contribution.

All of our documentation is written in Markdown.
- Including these slides!
Use the pull request process to submit changes to documentation.

How do we keep the documentation useful and consistent?

Of course the last slide is the million dollar question.

It is only through the efforts of contributors like you that the documentation stays useful and consistent.
Pay attention to any visible changes your contributions are making! Always ask yourself, “How will this affect the documentation?”

Onboarding Index | Next Section

Docs: Section 10: Architecture and Enhancements

Mon, 01 Jan 0001 00:00:00 +0000

Section 10: Architecture and Enhancements

What you’re about to learn

We’re getting into the guts of Kubernetes now! After this module, you will:

Be able to locate the architecture documents for Kubernetes
Understand how the different components interact
Know how features and major changes are added to Kubernetes

Where are the architecture documents?

The good news is that the Kubernetes architecture is very well documented.

A great place to start is this overview of Kubernetes components.
You can find the cluster architecture in the Concepts section of the documentation.

What are the components of a Kubernetes cluster?

A Kubernetes deployment is called a cluster. So what is it made of?

The control plane makes global decisions about the cluster, as well as detecting and responding to cluster events
Compute resources, known as nodes, run pods and provide the Kubernetes runtime environment.
Pods are the smallest deployable units of computing that you can create and manage in Kubernetes.

You can also learn how they communicate with each other.

How are new features added to Kubernetes?

New features are added through a process that begins with a Kubernetes Enhancement Proposal.

KEPs are required for most non-trivial changes. Specifically:

Anything that may be controversial
Most new features
Major changes to existing features
Changes that are wide ranging or impact most of the project

Who manages the Kubernetes Enhancement Proposal process?

First, we call it KEP for short. And second, the KEP process is managed by the Architecture Special Interest Group (SIG Architecture).

To learn more, read the SIG Architecture documentation.

Onboarding Index