Move Support topics. (#3108)
* Move Support topics. * Update stage-documentation-changes.md * Update stage-documentation-changes.md
This commit is contained in:
Steve Perry
@@ -0,0 +1,98 @@
|
||||
---
|
||||
title: Creating a Documentation Pull Request
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
|
||||
To contribute to the Kubernetes documentation, create a pull request against the
|
||||
[kubernetes/kubernetes.github.io](https://github.com/kubernetes/kubernetes.github.io){: target="_blank"}
|
||||
repository. This page shows how to create a pull request.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture prerequisites %}
|
||||
|
||||
1. Create a [GitHub account](https://github.com){: target="_blank"}.
|
||||
|
||||
1. Sign the
|
||||
[Linux Foundation Contributor License Agreement](https://identity.linuxfoundation.org/projects/cncf){: target="_blank"}.
|
||||
|
||||
Documentation will be published under the [CC BY SA 4.0](https://github.com/kubernetes/kubernetes.github.io/blob/master/LICENSE) license.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture steps %}
|
||||
|
||||
## Creating a fork of the Kubernetes documentation repository
|
||||
|
||||
1. Go to the
|
||||
[kubernetes/kubernetes.github.io](https://github.com/kubernetes/kubernetes.github.io){: target="_blank"}
|
||||
repository.
|
||||
|
||||
1. In the upper-right corner, click **Fork**. This creates a copy of the
|
||||
Kubernetes documentation repository in your GitHub account. The copy
|
||||
is called a *fork*.
|
||||
|
||||
## Making your changes
|
||||
|
||||
1. In your GitHub account, in your fork of the Kubernetes docs, create
|
||||
a new branch to use for your contribution.
|
||||
|
||||
1. In your new branch, make your changes and commit them. If you want to
|
||||
[write a new topic](/docs/contribute/write-new-topic/),
|
||||
choose the
|
||||
[page type](/docs/contribute/page-templates/)
|
||||
that is the best fit for your content.
|
||||
|
||||
## Submitting a pull request to the master branch (Current Release)
|
||||
|
||||
If you want your change to be published in the released version Kubernetes docs,
|
||||
create a pull request against the master branch of the Kubernetes
|
||||
documentation repository.
|
||||
|
||||
1. In your GitHub account, in your new branch, create a pull request
|
||||
against the master branch of the kubernetes/kubernetes.github.io
|
||||
repository. This opens a page that shows the status of your pull request.
|
||||
|
||||
1. Click **Show all checks**. Wait for the **deploy/netlify** check to complete.
|
||||
To the right of **deploy/netlify**, click **Details**. This opens a staging
|
||||
site where you can verify that your changes have rendered correctly.
|
||||
|
||||
1. During the next few days, check your pull request for reviewer comments.
|
||||
If needed, revise your pull request by committing changes to your
|
||||
new branch in your fork.
|
||||
|
||||
## Submitting a pull request to the <vnext> branch (Upcoming Release)
|
||||
|
||||
If your documentation change should not be released until the next release of
|
||||
the Kubernetes product, create a pull request against the <vnext> branch
|
||||
of the Kubernetes documentation repository. The <vnext> branch has the
|
||||
form `release-<version-number>`, for example release-1.5.
|
||||
|
||||
1. In your GitHub account, in your new branch, create a pull request
|
||||
against the <vnext> branch of the kubernetes/kubernetes.github.io
|
||||
repository. This opens a page that shows the status of your pull request.
|
||||
|
||||
1. Click **Show all checks**. Wait for the **deploy/netlify** check to complete.
|
||||
To the right of **deploy/netlify**, click **Details**. This opens a staging
|
||||
site where you can verify that your changes have rendered correctly.
|
||||
|
||||
1. During the next few days, check your pull request for reviewer comments.
|
||||
If needed, revise your pull request by committing changes to your
|
||||
new branch in your fork.
|
||||
|
||||
The staging site for the upcoming Kubernetes release is here:
|
||||
[http://kubernetes-io-vnext-staging.netlify.com/](http://kubernetes-io-vnext-staging.netlify.com/).
|
||||
The staging site reflects the current state of what's been merged in the
|
||||
release branch, or in other words, what the docs will look like for the
|
||||
next upcoming release. It's automatically updated as new PRs get merged.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn about [writing a new topic](/docs/contribute/write-new-topic).
|
||||
* Learn about [using page templates](/docs/contribute/page-templates/).
|
||||
* Learn about [staging your changes](/docs/contribute/stage-documentation-changes).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/task.md %}
|
||||
@@ -0,0 +1,222 @@
|
||||
---
|
||||
redirect_from:
|
||||
- "/docs/templatedemos/"
|
||||
- "/docs/templatedemos.html"
|
||||
title: Using Page Templates
|
||||
---
|
||||
|
||||
<!--<html>
|
||||
<body>-->
|
||||
|
||||
<p>These page templates are available for writers who would like to contribute new topics to the Kubernetes docs:</p>
|
||||
|
||||
<ul>
|
||||
<li><a href="#task_template">Task</a></li>
|
||||
<li><a href="#tutorial_template">Tutorial</a></li>
|
||||
<li><a href="#concept_template">Concept</a></li>
|
||||
</ul>
|
||||
|
||||
<p>The page templates are in the <a href="https://github.com/kubernetes/kubernetes.github.io/tree/master/_includes/templates" target="_blank">_includes/templates</a> directory of the <a href="https://github.com/kubernetes/kubernetes.github.io">kubernetes.github.io</a> repository.
|
||||
|
||||
<h2 id="task_template">Task template</h2>
|
||||
|
||||
<p>A task page shows how to do a single thing, typically by giving a short
|
||||
sequence of steps. Task pages have minimal explanation, but often provide links
|
||||
to conceptual topics that provide related background and knowledge.</p>
|
||||
|
||||
<p>To write a new task page, create a Markdown file in a subdirectory of the
|
||||
/docs/tasks directory. In your Markdown file, provide values for these
|
||||
variables, and then include templates/task.md:</p>
|
||||
|
||||
<ul>
|
||||
<li>overview - required</li>
|
||||
<li>prerequisites - required</li>
|
||||
<li>steps - required</li>
|
||||
<li>discussion - optional</li>
|
||||
<li>whatsnext - optional</li>
|
||||
</ul>
|
||||
|
||||
<p>In the <code>steps</code> section, use <code>##</code> to start with a level-two heading. For subheadings,
|
||||
use <code>###</code> and <code>####</code> as needed. Similarly, if you choose to have a <code>discussion</code> section,
|
||||
start the section with a level-two heading.</p>
|
||||
|
||||
<p>Here's an example of a Markdown file that uses the task template:</p>
|
||||
|
||||
{% raw %}
|
||||
<pre>---
|
||||
title: Configuring This Thing
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page shows how to ...
|
||||
{% endcapture %}
|
||||
|
||||
{% capture prerequisites %}
|
||||
* Do this.
|
||||
* Do this too.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture steps %}
|
||||
## Doing ...
|
||||
|
||||
1. Do this.
|
||||
1. Do this next. Possibly read this [related explanation](...).
|
||||
{% endcapture %}
|
||||
|
||||
{% capture discussion %}
|
||||
## Understanding ...
|
||||
|
||||
Here's an interesting thing to know about the steps you just did.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn more about [this](...).
|
||||
* See this [related task](...).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/task.md %}
|
||||
</pre>
|
||||
{% endraw %}
|
||||
|
||||
<p>Here's an example of a published topic that uses the task template:</p>
|
||||
|
||||
<p><a href="/docs/tasks/access-kubernetes-api/http-proxy-access-api">Using an HTTP Proxy to Access the Kubernetes API</a></p>
|
||||
|
||||
<h2 id="tutorial_template">Tutorial template</h2>
|
||||
|
||||
<p>A tutorial page shows how to accomplish a goal that is larger than a single
|
||||
task. Typically a tutorial page has several sections, each of which has a
|
||||
sequence of steps. For example, a tutorial might provide a walkthrough of a
|
||||
code sample that illustrates a certain feature of Kubernetes. Tutorials can
|
||||
include surface-level explanations, but should link to related concept topics
|
||||
for deep explanations.
|
||||
|
||||
<p>To write a new tutorial page, create a Markdown file in a subdirectory of the
|
||||
/docs/tutorials directory. In your Markdown file, provide values for these
|
||||
variables, and then include templates/tutorial.md:</p>
|
||||
|
||||
<ul>
|
||||
<li>overview - required</li>
|
||||
<li>prerequisites - required</li>
|
||||
<li>objectives - required</li>
|
||||
<li>lessoncontent - required</li>
|
||||
<li>cleanup - optional</li>
|
||||
<li>whatsnext - optional</li>
|
||||
</ul>
|
||||
|
||||
<p>In the <code>lessoncontent</code> section, use <code>##</code> to start with a level-two heading. For subheadings,
|
||||
use <code>###</code> and <code>####</code> as needed.
|
||||
|
||||
<p>Here's an example of a Markdown file that uses the tutorial template:</p>
|
||||
|
||||
{% raw %}
|
||||
<pre>---
|
||||
title: Running a Thing
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page shows how to ...
|
||||
{% endcapture %}
|
||||
|
||||
{% capture prerequisites %}
|
||||
* Do this.
|
||||
* Do this too.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture objectives %}
|
||||
* Learn this.
|
||||
* Build this.
|
||||
* Run this.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture lessoncontent %}
|
||||
## Building ...
|
||||
|
||||
1. Do this.
|
||||
1. Do this next. Possibly read this [related explanation](...).
|
||||
|
||||
## Running ...
|
||||
|
||||
1. Do this.
|
||||
1. Do this next.
|
||||
|
||||
## Understanding the code
|
||||
Here's something interesting about the code you ran in the preceding steps.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture cleanup %}
|
||||
* Delete this.
|
||||
* Stop this.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn more about [this](...).
|
||||
* See this [related tutorial](...).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/tutorial.md %}
|
||||
</pre>
|
||||
{% endraw %}
|
||||
|
||||
<p>Here's an example of a published topic that uses the tutorial template:</p>
|
||||
|
||||
<p><a href="/docs/tutorials/stateless-application/run-stateless-application-deployment/">Running a Stateless Application Using a Deployment</a></p>
|
||||
|
||||
<h2 id="concept_template">Concept template</h2>
|
||||
|
||||
<p>A concept page explains some aspect of Kubernetes. For example, a concept
|
||||
page might describe the Kubernetes Deployment object and explain the role it
|
||||
plays as an application is deployed, scaled, and updated. Typically, concept
|
||||
pages don't include sequences of steps, but instead provide links to tasks or
|
||||
tutorials.
|
||||
|
||||
<p>To write a new concept page, create a Markdown file in a subdirectory of the
|
||||
/docs/concepts directory. In your Markdown file, provide values for these
|
||||
variables, and then include templates/concept.md:</p>
|
||||
|
||||
<ul>
|
||||
<li>overview - required</li>
|
||||
<li>body - required</li>
|
||||
<li>whatsnext - optional</li>
|
||||
</ul>
|
||||
|
||||
<p>In the <code>body</code> section, use <code>##</code> to start with a level-two heading. For subheadings,
|
||||
use <code>###</code> and <code>####</code> as needed.
|
||||
|
||||
<p>Here's an example of a page that uses the concept template:</p>
|
||||
|
||||
{% raw %}
|
||||
<pre>---
|
||||
title: Understanding this Thing
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page explains ...
|
||||
{% endcapture %}
|
||||
|
||||
{% capture body %}
|
||||
## Understanding ...
|
||||
|
||||
Kubernetes provides ...
|
||||
|
||||
## Using ...
|
||||
|
||||
To use ...
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn more about [this](...).
|
||||
* See this [related task](...).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/concept.md %}
|
||||
</pre>
|
||||
{% endraw %}
|
||||
|
||||
<p>Here's an example of a published topic that uses the concept template:</p>
|
||||
|
||||
<p><a href="/docs/concepts/object-metadata/annotations">Annotations</a></p>
|
||||
|
||||
<!--</body>
|
||||
</html>-->
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
title: Reviewing Documentation Issues
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
|
||||
This page explains how documentation issues are reviewed and prioritized for the [kubernetes/kubernetes.github.io](https://github.com/kubernetes/kubernetes.github.io){: target="_blank"} repository. The purpose is to provide a way to organize issues and make it easier to contribute to Kubernetes documentation. The following should be used as the standard way of prioritizing, labeling, and interacting with issues.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture body %}
|
||||
|
||||
## Categorizing issues
|
||||
Issues should be sorted into different buckets of work using the following labels and definitions. If an issue doesn't have enough information to identify a problem that can be researched, reviewed, or worked on (i.e. the issue doesn't fit into any of the categories below) you should close the issue with a comment explaining why it is being closed.
|
||||
|
||||
### Needs Clarification
|
||||
* Issues that need more information from the original submitter to make them actionable. Issues with this label that aren't followed up within a week may be closed.
|
||||
|
||||
### Actionable
|
||||
* Issues that can be worked on with current information (or may need a comment to explain what needs to be done to make it more clear)
|
||||
* Allows contributors to have easy to find issues to work on
|
||||
|
||||
|
||||
### Needs Tech Review
|
||||
* Issues that need more information in order to be worked on (the proposed solution needs to be proven, a subject matter expert needs to be involved, work needs to be done to understand the problem/resolution and if the issue is still relevant)
|
||||
* Promotes transparency about level of work needed for the issue and that issue is in progress
|
||||
|
||||
### Needs Docs Review
|
||||
* Issues that are suggestions for better processes or site improvements that require community agreement to be implemented
|
||||
* Topics can be brought to SIG meetings as agenda items
|
||||
|
||||
### Needs UX Review
|
||||
* Issues that are suggestions for improving the user interface of the site.
|
||||
* Fixing broken site elements.
|
||||
|
||||
|
||||
## Prioritizing Issues
|
||||
The following labels and definitions should be used to prioritize issues. If you change the priority of an issues, please comment on the issue with your reasoning for the change.
|
||||
|
||||
### P1
|
||||
* Major content errors affecting more than 1 page
|
||||
* Broken code sample on a heavily trafficked page
|
||||
* Errors on a “getting started” page
|
||||
* Well known or highly publicized customer pain points
|
||||
* Automation issues
|
||||
|
||||
### P2
|
||||
* Default for all new issues
|
||||
* Broken code for sample that is not heavily used
|
||||
* Minor content issues in a heavily trafficked page
|
||||
* Major content issues on a lower-trafficked page
|
||||
|
||||
### P3
|
||||
* Typos and broken anchor links
|
||||
|
||||
## Handling special issue types
|
||||
|
||||
### Duplicate issues
|
||||
If a single problem has one or more issues open for it, the problem should be consolodated into a single issue. You should decide which issue to keep open (or open a new issue), port over all relevant information, link related issues, and close all the other issues that describe the same problem. Only having a single issue to work on will help reduce confusion and avoid duplicating work on the same problem.
|
||||
|
||||
### Dead link issues
|
||||
Depending on where the dead link is reported, different actions are required to resolve the issue. Dead links in the API and Kubectl docs are automation issues and should be assigned a P1 until the problem can be fully understood. All other dead links are issues that need to be manually fixed and can be assigned a P3.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn about [writing a new topic](/docs/contribute/write-new-topic).
|
||||
* Learn about [using page templates](/docs/contribute/page-templates/).
|
||||
* Learn about [staging your changes](/docs/contribute/stage-documentation-changes).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/concept.md %}
|
||||
@@ -0,0 +1,109 @@
|
||||
---
|
||||
title: Staging Your Documentation Changes
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page shows how to stage content that you want to contribute
|
||||
to the Kubernetes documentation.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture prerequisites %}
|
||||
Create a fork of the Kubernetes documentation repository as described in
|
||||
[Creating a Documentation Pull Request](/docs/contribute/create-pull-request/).
|
||||
{% endcapture %}
|
||||
|
||||
{% capture steps %}
|
||||
|
||||
## Staging from your GitHub account
|
||||
|
||||
GitHub provides staging of content in your master branch. Note that you
|
||||
might not want to merge your changes into your master branch. If that is
|
||||
the case, choose another option for staging your content.
|
||||
|
||||
1. In your GitHub account, in your fork, merge your changes into
|
||||
the master branch.
|
||||
|
||||
1. Change the name of your repository to `<your-username>.github.io`, where
|
||||
`<your-username>` is the username of your GitHub account.
|
||||
|
||||
1. Delete the `CNAME` file.
|
||||
|
||||
1. View your staged content at this URL:
|
||||
|
||||
https://<your-username>.github.io
|
||||
|
||||
## Staging a pull request
|
||||
|
||||
When you create a pull request, either against the master or <vnext>
|
||||
branch, your changes are staged in a custom subdomain on Netlify so that
|
||||
you can see your changes in rendered form before the pull request is merged.
|
||||
|
||||
1. In your GitHub account, in your new branch, submit a pull request to the
|
||||
kubernetes/kubernetes.github.io repository. This opens a page that shows the
|
||||
status of your pull request.
|
||||
|
||||
1. Scroll down to the list of automated checks. Click **Show all checks**.
|
||||
Wait for the **deploy/netlify** check to complete. To the right of
|
||||
**deploy/netlify**, click **Details**. This opens a staging site where you
|
||||
can see your changes.
|
||||
|
||||
## Staging locally using Docker
|
||||
|
||||
You can use the k8sdocs Docker image to run a local staging server. If you're
|
||||
interested, you can view the
|
||||
[Dockerfile](https://github.com/kubernetes/kubernetes.github.io/blob/master/staging-container/Dockerfile){: target="_blank"}
|
||||
for this image.
|
||||
|
||||
1. Install Docker if you don't already have it.
|
||||
|
||||
1. Clone your fork to your local development machine.
|
||||
|
||||
1. In the root of your cloned repository, enter this command to start a local
|
||||
web server:
|
||||
|
||||
docker run -ti --rm -v "$PWD":/k8sdocs -p 4000:4000 gcr.io/google-samples/k8sdocs:1.0
|
||||
|
||||
1. View your staged content at
|
||||
[http://localhost:4000](http://localhost:4000){: target="_blank"}.
|
||||
|
||||
## Staging locally without Docker
|
||||
|
||||
1. [Install Ruby 2.2 or later](https://www.ruby-lang.org){: target="_blank"}.
|
||||
|
||||
1. [Install RubyGems](https://rubygems.org){: target="_blank"}.
|
||||
|
||||
1. Verify that Ruby and RubyGems are installed:
|
||||
|
||||
gem --version
|
||||
|
||||
1. Install the GitHub Pages package, which includes Jekyll:
|
||||
|
||||
gem install github-pages
|
||||
|
||||
1. Clone your fork to your local development machine.
|
||||
|
||||
1. In the root of your cloned repository, enter this command to start a local
|
||||
web server:
|
||||
|
||||
jekyll serve
|
||||
|
||||
1. View your staged content at
|
||||
[http://localhost:4000](http://localhost:4000){: target="_blank"}.
|
||||
|
||||
<i>NOTE: If you do not want Jekyll to interfere with your other globally installed gems, you can use `bundler`:</i>
|
||||
|
||||
gem install bundler
|
||||
bundle install
|
||||
bundler exec jekyll serve
|
||||
|
||||
<i> Regardless of whether you use `bundler` or not, your copy of the site will then be viewable at: [http://localhost:4000](http://localhost:4000)</i>
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn about [writing a new topic](/docs/contribute/write-new-topic/).
|
||||
* Learn about [using page templates](/docs/contribute/page-templates/).
|
||||
* Learn about [creating a pull request](/docs/contribute/create-pull-request/).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/task.md %}
|
||||
@@ -0,0 +1,236 @@
|
||||
---
|
||||
title: Documentation Style Guide
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page gives writing style guidelines for the Kubernetes documentation.
|
||||
These are guidelines, not rules. Use your best judgment, and feel free to
|
||||
propose changes to this document in a pull request.
|
||||
|
||||
For additional information on creating new content for the Kubernetes
|
||||
docs, follow the instructions on
|
||||
[using page templates](/docs/contribute/page-templates/) and
|
||||
[creating a documentation pull request](/docs/contribute/create-pull-request/).
|
||||
{% endcapture %}
|
||||
|
||||
{% capture body %}
|
||||
|
||||
## Documentation formatting standards
|
||||
|
||||
### Use camel case for API objects
|
||||
|
||||
When you refer to an API object, use the same uppercase and lowercase letters
|
||||
that are used in the actual object name. Typically, the names of API
|
||||
objects use
|
||||
[camel case](https://en.wikipedia.org/wiki/Camel_case).
|
||||
|
||||
Don't split the API object name into separate words. For example, use
|
||||
PodTemplateList, not Pod Template List.
|
||||
|
||||
Refer to API objects without saying "object," unless omitting "object"
|
||||
leads to an awkward construction.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>The Pod has two Containers.</td><td>The pod has two containers.</td></tr>
|
||||
<tr><td>The Deployment is responsible for ...</td><td>The Deployment object is responsible for ...</td></tr>
|
||||
<tr><td>A PodList is a list of Pods.</td><td>A Pod List is a list of pods.</td></tr>
|
||||
<tr><td>The two ContainerPorts ...</td><td>The two ContainerPort objects ...</td></tr>
|
||||
<tr><td>The two ContainerStateTerminated objects ...</td><td>The two ContainerStateTerminateds ...</td></tr>
|
||||
</table>
|
||||
|
||||
### Use angle brackets for placeholders
|
||||
|
||||
Use angle brackets for placeholders. Tell the reader what a placeholder
|
||||
represents.
|
||||
|
||||
1. Display information about a pod:
|
||||
|
||||
kubectl describe pod <pod-name>
|
||||
|
||||
where `<pod-name>` is the name of one of your pods.
|
||||
|
||||
### Use bold for user interface elements
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Click <b>Fork</b>.</td><td>Click "Fork".</td></tr>
|
||||
<tr><td>Select <b>Other</b>.</td><td>Select 'Other'.</td></tr>
|
||||
</table>
|
||||
|
||||
### Use italics to define or introduce new terms
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>A <i>cluster</i> is a set of nodes ...</td><td>A "cluster" is a set of nodes ...</td></tr>
|
||||
<tr><td>These components form the <i>control plane.</i></td><td>These components form the <b>control plane.</b></td></tr>
|
||||
</table>
|
||||
|
||||
### Use code style for filenames, directories, and paths
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Open the <code>envars.yaml</code> file.</td><td>Open the envars.yaml file.</td></tr>
|
||||
<tr><td>Go to the <code>/docs/tutorials</code> directory.</td><td>Go to the /docs/tutorials directory.</td></tr>
|
||||
<tr><td>Open the <code>/_data/concepts.yaml</code> file.</td><td>Open the /_data/concepts.yaml file.</td></tr>
|
||||
</table>
|
||||
|
||||
## Inline code formatting
|
||||
|
||||
### Use code style for inline code and commands
|
||||
|
||||
For inline code in an HTML document, use the `<code>` tag. In a Markdown
|
||||
document, use the backtick (`).
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>The <code>kubectl run</code> command creates a Deployment.</td><td>The "kubectl run" command creates a Deployment.</td></tr>
|
||||
<tr><td>For declarative management, use <code>kubectl apply</code>.</td><td>For declarative management, use "kubectl apply".</td></tr>
|
||||
</table>
|
||||
|
||||
### Use code style for object field names
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Set the value of the <code>replicas</code> field in the configuration file.</td><td>Set the value of the "replicas" field in the configuration file.</td></tr>
|
||||
<tr><td>The value of the <code>exec</code> field is an ExecAction object.</td><td>The value of the "exec" field is an ExecAction object.</td></tr>
|
||||
</table>
|
||||
|
||||
### Use normal style for string and integer field values
|
||||
|
||||
For field values of type string or integer, use normal style without quotation marks.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Set the value of <code>imagePullPolicy</code> to Always.</td><td>Set the value of <code>imagePullPolicy</code> to "Always".</td></tr>
|
||||
<tr><td>Set the value of <code>image</code> to nginx:1.8.</td><td>Set the value of <code>image</code> to <code>nginx:1.8</code>.</td></tr>
|
||||
<tr><td>Set the value of the <code>replicas</code> field to 2.</td><td>Set the value of the <code>replicas</code> field to <code>2</code>.</td></tr>
|
||||
</table>
|
||||
|
||||
## Code snippet formatting
|
||||
|
||||
### Don't include the command prompt
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>kubectl get pods</td><td>$ kubectl get pods</td></tr>
|
||||
</table>
|
||||
|
||||
### Separate commands from output
|
||||
|
||||
Verify that the pod is running on your chosen node:
|
||||
|
||||
kubectl get pods --output=wide
|
||||
|
||||
The output is similar to this:
|
||||
|
||||
NAME READY STATUS RESTARTS AGE IP NODE
|
||||
nginx 1/1 Running 0 13s 10.200.0.4 worker0
|
||||
|
||||
|
||||
{% comment %}## Kubernetes.io word list
|
||||
|
||||
A list of Kubernetes-specific terms and words to be used consistently across the site.
|
||||
|
||||
<table>
|
||||
<tr><th>Term</th><th>Useage</th></tr>
|
||||
<tr><td>TBD</td><td>TBD</td></tr>
|
||||
</table>{% endcomment %}
|
||||
|
||||
|
||||
## Content best practices
|
||||
|
||||
This section contains suggested best practices for clear, concise, and consistent content.
|
||||
|
||||
### Use present tense
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>This command starts a proxy.</td><td>This command will start a proxy.</td></tr>
|
||||
</table>
|
||||
|
||||
Exception: Use future or past tense if it is required to convey the correct
|
||||
meaning.
|
||||
|
||||
### Use active voice
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>You can explore the API using a browser.</td><td>The API can be explored using a browser.</td></tr>
|
||||
<tr><td>The YAML file specifies the replica count.</td><td>The replica count is specified in the YAML file.</td></tr>
|
||||
</table>
|
||||
|
||||
Exception: Use passive voice if active voice leads to an awkward construction.
|
||||
|
||||
### Use simple and direct language
|
||||
|
||||
Use simple and direct language. Avoid using unnecessary phrases, such as saying "please."
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>To create a ReplicaSet, ...</td><td>In order to create a ReplicaSet, ...</td></tr>
|
||||
<tr><td>See the configuration file.</td><td>Please see the configuration file.</td></tr>
|
||||
<tr><td>View the Pods.</td><td>With this next command, we'll view the Pods.</td></tr>
|
||||
|
||||
</table>
|
||||
|
||||
### Address the reader as "you"
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>You can create a Deployment by ...</td><td>We'll create a Deployment by ...</td></tr>
|
||||
<tr><td>In the preceding output, you can see...</td><td>In the preceding output, we can see ...</td></tr>
|
||||
</table>
|
||||
|
||||
## Patterns to avoid
|
||||
|
||||
### Avoid using "we"
|
||||
|
||||
Using "we" in a sentence can be confusing, because the reader might not know
|
||||
whether they're part of the "we" you're describing.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Version 1.4 includes ...</td><td>In version 1.4, we have added ...</td></tr>
|
||||
<tr><td>Kubernetes provides a new feature for ...</td><td>We provide a new feature ...</td></tr>
|
||||
<tr><td>This page teaches you how to use pods.</td><td>In this page, we are going to learn about pods.</td></tr>
|
||||
</table>
|
||||
|
||||
### Avoid jargon and idioms
|
||||
|
||||
Some readers speak English as a second language. Avoid jargon and idioms to help make their understanding easier.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Internally, ...</td><td>Under the hood, ...</td></tr>
|
||||
<tr><td>Create a new cluster.</td><td>Turn up a new cluster.</td></tr>
|
||||
</table>
|
||||
|
||||
### Avoid statements about the future
|
||||
|
||||
Avoid making promises or giving hints about the future. If you need to talk about
|
||||
an alpha feature, put the text under a heading that identifies it as alpha
|
||||
information.
|
||||
|
||||
### Avoid statements that will soon be out of date
|
||||
|
||||
Avoid words like "currently" and "new." A feature that is new today might not be
|
||||
considered new in a few months.
|
||||
|
||||
<table>
|
||||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>In version 1.4, ...</td><td>In the current version, ...</td></tr>
|
||||
<tr><td>The Federation feature provides ...</td><td>The new Federation feature provides ...</td></tr>
|
||||
</table>
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn about [writing a new topic](/docs/contribute/write-new-topic/).
|
||||
* Learn about [using page templates](/docs/contribute/page-templates/).
|
||||
* Learn about [staging your changes](/docs/contribute/stage-documentation-changes/)
|
||||
* Learn about [creating a pull request](/docs/contribute/create-pull-request/).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/concept.md %}
|
||||
@@ -0,0 +1,143 @@
|
||||
---
|
||||
title: Writing a New Topic
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page shows how to create a new topic for the Kubernetes docs.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture prerequisites %}
|
||||
Create a fork of the Kubernetes documentation repository as described in
|
||||
[Creating a Documentation Pull Request](/docs/contribute/create-pull-request/).
|
||||
{% endcapture %}
|
||||
|
||||
{% capture steps %}
|
||||
|
||||
## Choosing a page type
|
||||
|
||||
As you prepare to write a new topic, think about which of these page types
|
||||
is the best fit for your content:
|
||||
|
||||
<table>
|
||||
|
||||
<tr>
|
||||
<td>Task</td>
|
||||
<td>A task page shows how to do a single thing, typically by giving a short sequence of steps. Task pages have minimal explanation, but often provide links to conceptual topics that provide related background and knowledge.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Tutorial</td>
|
||||
<td>A tutorial page shows how to accomplish a goal that is larger than a single task. Typically a tutorial page has several sections, each of which has a sequence of steps. For example, a tutorial might provide a walkthrough of a code sample that illustrates a certain feature of Kubernetes. Tutorials can include surface-level explanations, but should link to related concept topics for deep explanations.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Concept</td>
|
||||
<td>A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials.</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
Each page type has a
|
||||
[template](/docs/contribute/page-templates/)
|
||||
that you can use as you write your topic.
|
||||
Using templates helps ensure consistency among topics of a given type.
|
||||
|
||||
## Choosing a title and filename
|
||||
|
||||
Choose a title that has the keywords you want search engines to find.
|
||||
Create a filename that uses the words in your title separated by hyphens.
|
||||
For example, the topic with title
|
||||
[Using an HTTP Proxy to Access the Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api/)
|
||||
has filename `http-proxy-access-api.md`. You don't need to put
|
||||
"kubernetes" in the filename, because "kubernetes" is already in the
|
||||
URL for the topic, for example:
|
||||
|
||||
http://kubernetes.io/docs/tasks/access-kubernetes-api/http-proxy-access-api/
|
||||
|
||||
## Adding the topic title to the front matter
|
||||
|
||||
In your topic, put a `title` field in the
|
||||
[front matter](https://jekyllrb.com/docs/frontmatter/).
|
||||
The front matter is the YAML block that is between the
|
||||
triple-dashed lines at the top of the page. Here's an example:
|
||||
|
||||
---
|
||||
title: Using an HTTP Proxy to Access the Kubernetes API
|
||||
---
|
||||
|
||||
## Choosing a directory
|
||||
|
||||
Depending on your page type, put your new file in a subdirectory of one of these:
|
||||
|
||||
* /docs/tasks/
|
||||
* /docs/tutorials/
|
||||
* /docs/concepts/
|
||||
|
||||
You can put your file in an existing subdirectory, or you can create a new
|
||||
subdirectory.
|
||||
|
||||
## Creating an entry in the table of contents
|
||||
|
||||
Depending page type, create an entry in one of these files:
|
||||
|
||||
* /_data/tasks.yaml
|
||||
* /_data/tutorials.yaml
|
||||
* /_data/concepts.yaml
|
||||
|
||||
Here's an example of an entry in /_data/tasks.yaml:
|
||||
|
||||
- docs/tasks/configure-pod-container/configure-volume-storage.md
|
||||
|
||||
## Including code from another file
|
||||
|
||||
To include a code file in your topic, place the code file in the Kubernetes
|
||||
documentation repository, preferably in the same directory as your topic
|
||||
file. In your topic file, use the `include` tag:
|
||||
|
||||
<pre>{% include code.html language="<LEXERVALUE>" file="<RELATIVEPATH>" ghlink="/<PATHFROMROOT>" %}</pre>
|
||||
|
||||
where:
|
||||
|
||||
* `<LEXERVALUE>` is the language in which the file was written. This must be
|
||||
[a value supported by Rouge](https://github.com/jneen/rouge/wiki/list-of-supported-languages-and-lexers).
|
||||
* `<RELATIVEPATH>` is the path to the file you're including, relative to the current file, for example, `gce-volume.yaml`.
|
||||
* `<PATHFROMROOT>` is the path to the file relative to root, for example, `docs/tutorials/stateful-application/gce-volume.yaml`.
|
||||
|
||||
Here's an example of using the `include` tag:
|
||||
|
||||
<pre>{% include code.html language="yaml" file="gce-volume.yaml" ghlink="/docs/tutorials/stateful-application/gce-volume.yaml" %}</pre>
|
||||
|
||||
## Showing how to create an API object from a configuration file
|
||||
|
||||
If you need to show the reader how to create an API object based on a
|
||||
configuration file, place the configuration file in the Kubernetes documentation
|
||||
repository, preferably in the same directory as your topic file.
|
||||
|
||||
In your topic, show this command:
|
||||
|
||||
kubectl create -f http://k8s.io/<PATHFROMROOT>
|
||||
|
||||
where `<PATHFROMROOT>` is the path to the configuration file relative to root,
|
||||
for example, `docs/tutorials/stateful-application/gce-volume.yaml`.
|
||||
|
||||
Here's an example of a command that creates an API object from a configuration file:
|
||||
|
||||
kubectl create -f http://k8s.io/docs/tutorials/stateful-application/gce-volume.yaml
|
||||
|
||||
For an example of a topic that uses this technique, see
|
||||
[Running a Single-Instance Stateful Application](/docs/tutorials/stateful-application/run-stateful-application/).
|
||||
|
||||
## Adding images to a topic
|
||||
|
||||
Put image files in the `/images` directory. The preferred
|
||||
image format is SVG.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn about [using page templates](/docs/contribute/page-templates/).
|
||||
* Learn about [staging your changes](/docs/contribute/stage-documentation-changes).
|
||||
* Learn about [creating a pull request](/docs/contribute/create-pull-request/).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/task.md %}
|
||||
@@ -0,0 +1,262 @@
|
||||
---
|
||||
assignees:
|
||||
- bgrant0607
|
||||
- lavalamp
|
||||
- thockin
|
||||
title: Kubernetes Deprecation Policy
|
||||
---
|
||||
|
||||
Kubernetes is a large system with many components and many contributors. As
|
||||
with any such software, the feature set naturally evolves over time, and
|
||||
sometimes a feature may need to be removed. This could include an API, a flag,
|
||||
or even an entire feature. To avoid breaking existing users, Kubernetes follows
|
||||
a deprecation policy for aspects of the system that are slated to be removed.
|
||||
|
||||
This document details the deprecation policy for various facets of the system.
|
||||
|
||||
## Deprecating parts of the API
|
||||
|
||||
Since Kubernetes is an API-driven system, the API has evolved over time to
|
||||
reflect the evolving understanding of the problem space. The Kubernetes API is
|
||||
actually a set of APIs, called "API groups", and each API group is
|
||||
independently versioned. [API versions](http://kubernetes.io/docs/api/) fall
|
||||
into 3 main tracks, each of which has different policies for deprecation:
|
||||
|
||||
| Example | Track |
|
||||
|----------|----------------------------------|
|
||||
| v1 | GA (generally available, stable) |
|
||||
| v1beta1 | Beta (pre-release) |
|
||||
| v1alpha1 | Alpha (experimental) |
|
||||
|
||||
A given release of Kubernetes can support any number of API groups and any
|
||||
number of versions of each.
|
||||
|
||||
The following rules govern the deprecation of elements of the API. This
|
||||
includes:
|
||||
|
||||
* REST resources (aka API objects)
|
||||
* Fields of REST resources
|
||||
* Enumerated or constant values
|
||||
* Component config structures
|
||||
|
||||
These rules are enforced between official releases, not between
|
||||
arbitrary commits to master or release branches.
|
||||
|
||||
**Rule #1: API elements may only be removed by incrementing the version of the
|
||||
API group.**
|
||||
|
||||
Once an API element has been added to an API group at a particular version, it
|
||||
can not be removed from that version or have its behavior significantly
|
||||
changed, regardless of track.
|
||||
|
||||
Note: For historical reasons, there are 2 "monolithic" API groups - "core" (no
|
||||
group name) and "extensions". Resources will incrementally be moved from these
|
||||
legacy API groups into more domain-specific API groups.
|
||||
|
||||
**Rule #2: API objects must be able to round-trip between API versions in a given
|
||||
release without information loss, with the exception of whole REST resources
|
||||
that do not exist in some versions.**
|
||||
|
||||
For example, an object can be written as v1 and then read back as v2 and
|
||||
converted to v1, and the resulting v1 resource will be identical to the
|
||||
original. The representation in v2 might be different from v1, but the system
|
||||
knows how to convert between them in both directions. Additionally, any new
|
||||
field added in v2 must be able to round-trip to v1 and back, which means v1
|
||||
might have to add an equivalent field or represent it as an annotation.
|
||||
|
||||
**Rule #3: An API version in a given track may not be deprecated until a new
|
||||
API version at least as stable is released.**
|
||||
|
||||
GA API versions can replace GA API versions as well as beta and alpha API
|
||||
version. Beta API versions *may not* replace GA API versions.
|
||||
|
||||
**Rule #4: Other than the most recent API version in each track, older API
|
||||
versions must be supported after their announced deprecation for a duration of
|
||||
no less than:**
|
||||
|
||||
* **GA: 1 year or 2 releases (whichever is longer)**
|
||||
* **Beta: 3 months or 1 release (whichever is longer)**
|
||||
* **Alpha: 0 releases**
|
||||
|
||||
This is best illustrated by example. Imagine a Kubernetes release, version X,
|
||||
which supports a particular API group. A new Kubernetes release is made every
|
||||
approximately 3 months (4 per year). The following table describes which API
|
||||
versions are supported in a series of subsequent releases.
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Release</th>
|
||||
<th>API Versions</th>
|
||||
<th>Notes</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>X</td>
|
||||
<td>v1</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+1</td>
|
||||
<td>v1, v2alpha1</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+2</td>
|
||||
<td>v1, v2alpha2</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>v2alpha1 is removed, "action required" relnote</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+3</td>
|
||||
<td>v1, v2beta1</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>v2alpha2 is removed, "action required" relnote</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+4</td>
|
||||
<td>v1, v2beta1, v2beta2</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>v2beta1 is deprecated, "action required" relnote</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+5</td>
|
||||
<td>v1, v2, v2beta2</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>v2beta1 is removed, "action required" relnote</li>
|
||||
<li>v2beta2 is deprecated, "action required" relnote</li>
|
||||
<li>v1 is deprecated, "action required" relnote</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+6</td>
|
||||
<td>v1, v2</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>v2beta2 is removed, "action required" relnote</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+7</td>
|
||||
<td>v1, v2</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+8</td>
|
||||
<td>v1, v2</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>X+9</td>
|
||||
<td>v2</td>
|
||||
<td>
|
||||
<ul>
|
||||
<li>v1 is removed, "action required" relnote</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
### REST resources (aka API objects)
|
||||
|
||||
Consider a hypothetical REST resource named Widget, which was present in API v1
|
||||
in the above timeline, and which needs to be deprecated. We
|
||||
[document](http://kubernetes.io/docs/deprecated/) and
|
||||
[announce](https://groups.google.com/forum/#!forum/kubernetes-announce) the
|
||||
deprecation in sync with release X+1. The Widget resource still exists in API
|
||||
version v1 (deprecated) but not in v2alpha1. The Widget resource continues to
|
||||
exist and function in releases up to and including X+8. Only in release X+9,
|
||||
when API v1 has aged out, does the Widget resource cease to exist, and the
|
||||
behavior get removed.
|
||||
|
||||
### Fields of REST resources
|
||||
|
||||
As with whole REST resources, an individual field which was present in API v1
|
||||
must exist and function until API v1 is removed. Unlike whole resources, the
|
||||
v2 APIs may choose a different representation for the field, as long as it can
|
||||
be round-tripped. For example a v1 field named "magnitude" which was
|
||||
deprecated might be named "deprecatedMagnitude" in API v2. When v1 is
|
||||
eventually removed, the deprecated field can be removed from v2.
|
||||
|
||||
### Enumerated or constant values
|
||||
|
||||
As with whole REST resources and fields thereof, a constant value which was
|
||||
supported in API v1 must exist and function until API v1 is removed.
|
||||
|
||||
### Component config structures
|
||||
|
||||
Component configs are versioned and managed just like REST resources.
|
||||
|
||||
### Future work
|
||||
|
||||
Over time, Kubernetes will introduce more fine-grained API versions, at which
|
||||
point these rules will be adjusted as needed.
|
||||
|
||||
## Deprecating a flag or CLI
|
||||
|
||||
The Kubernetes system is comprised of several different programs cooperating.
|
||||
Sometimes, a Kubernetes release might remove flags or CLI commands
|
||||
(collectively "CLI elements") in these programs. The individual programs
|
||||
naturally sort into two main groups - user-facing and admin-facing programs,
|
||||
which vary slightly in their deprecation policies. Unless a flag is explicitly
|
||||
prefixed or documented as "alpha" or "beta", it is considered GA.
|
||||
|
||||
CLI elements are effectively part of the API to the system, but since they are
|
||||
not versioned in the same way as the REST API, the rules for deprecation are as
|
||||
follows:
|
||||
|
||||
**Rule #5a: CLI elements of user-facing components (e.g. kubectl) must function
|
||||
after their announced deprecation for no less than:**
|
||||
|
||||
* **GA: 1 year or 2 releases (whichever is longer)**
|
||||
* **Beta: 3 months or 1 release (whichever is longer)**
|
||||
* **Alpha: 0 releases**
|
||||
|
||||
**Rule #5b: CLI elements of admin-facing components (e.g. kubelet) must function
|
||||
after their announced deprecation for no less than:**
|
||||
|
||||
* **GA: 6 months or 1 release (whichever is longer)**
|
||||
* **Beta: 3 months or 1 release (whichever is longer)**
|
||||
* **Alpha: 0 releases**
|
||||
|
||||
**Rule #6: Deprecated CLI elements must emit warnings (optionally disable)
|
||||
when used.**
|
||||
|
||||
## Deprecating a feature or behavior
|
||||
|
||||
Occasionally a Kubernetes release needs to deprecate some feature or behavior
|
||||
of the system that is not controlled by the API or CLI. In this case, the
|
||||
rules for deprecation are as follows:
|
||||
|
||||
**Rule #7: Deprecated behaviors must function for no less than 1 year after their
|
||||
announced deprecation.**
|
||||
|
||||
This does not imply that all changes to the system are governed by this policy.
|
||||
This applies only to significant, user-visible behaviors which impact the
|
||||
correctness of applications running on Kubernetes or that impact the
|
||||
administration of Kubernetes clusters, and which are being removed entirely.
|
||||
|
||||
## Exceptions
|
||||
|
||||
No policy can cover every possible situation. This policy is a living
|
||||
document, and will evolve over time. In practice, there will be situations
|
||||
that do not fit neatly into this policy, or for which this policy becomes a
|
||||
serious impediment. Such situations should be discussed with SIGs and project
|
||||
leaders to find the best solutions for those specific cases, always bearing in
|
||||
mind that Kubernetes is committed to being a stable system that, as much as
|
||||
possible, never breaks users. Exceptions will always be announced in all
|
||||
relevant release notes.
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
assignees:
|
||||
- bgrant0607
|
||||
- thockin
|
||||
title: Kubernetes Documentation
|
||||
redirect_from:
|
||||
- "/docs/"
|
||||
- "/docs/index.html"
|
||||
---
|
||||
|
||||
<p>Kubernetes documentation can help you set up Kubernetes, learn about the system, or get your applications and workloads running on Kubernetes. To learn the basics of what Kubernetes is and how it works, read "<a href="/docs/whatisk8s/">What is Kubernetes</a>". </p>
|
||||
|
||||
<h2>Interactive Tutorial</h2>
|
||||
|
||||
<p>The <a href="/docs/tutorials/kubernetes-basics/">Kubernetes Basics interactive tutorial</a> lets you try out Kubernetes right out of your web browser, using a virtual terminal. Learn about the Kubernetes system and deploy, expose, scale, and upgrade a containerized application in just a few minutes.</p>
|
||||
|
||||
<h2>Installing/Setting Up Kubernetes</h2>
|
||||
|
||||
<p><a href="/docs/getting-started-guides/">Picking the Right Solution</a> can help you get a Kubernetes cluster up and running, either for local development, or on your cloud provider of choice.</p>
|
||||
|
||||
<p>Other/newer ways to set up a Kubernetes cluster include:</p>
|
||||
<ul>
|
||||
<li><a href="/docs/getting-started-guides/minikube/">Minikube</a>: Install a single-node Kubernetes cluster on your local machine for development and testing.</li>
|
||||
<li><a href="/docs/getting-started-guides/kops/">Installing Kubernetes on AWS with kops</a>: Bring up a complete Kubernetes cluster on Amazon Web Services, using a tool called <code>kops</code>.</li>
|
||||
<li><a href="/docs/getting-started-guides/kubeadm/">Installing Kubernetes on Linux with kubeadm</a> (Beta): Install a secure Kubernetes cluster on any pre-existing machines running Linux, using the built-in <code>kubeadm</code> tool.</li>
|
||||
<li><a href="/docs/getting-started-guides/kargo/">Installing Kubernetes On-premise/Cloud Providers with Kargo</a>: Deploy a Kubernetes cluster on-premise baremetal or hosted on cloud providers, with Ansible and <code>kargo</code> tools.</li>
|
||||
</ul>
|
||||
|
||||
<h2>Guides, Tutorials, Tasks, and Concepts</h2>
|
||||
|
||||
<p>The Kubernetes documentation contains a number of resources to help you understand and work with Kubernetes.</p>
|
||||
<ul>
|
||||
<li><b><a href="/docs/user-guide/">Guides</a></b> provides documentation for Kubernetes features as well as administering and spinning up clusters, including usage examples.</li>
|
||||
<li><b><a href="/docs/tutorials/">Tutorials</a></b> contain detailed walkthroughs of the Kubernetes workflow.</li>
|
||||
<li><b><a href="/docs/tasks/">Tasks</a></b> contain step-by-step instructions for common Kubernetes tasks.</li>
|
||||
<li><b><a href="/docs/concepts/">Concepts</a></b> provide a deep understanding of how Kubernetes works.</li>
|
||||
</ul>
|
||||
|
||||
<h2>API and Command References</h2>
|
||||
|
||||
<p>The <a href="/docs/reference/">reference</a> documentation provides complete information on the Kubernetes APIs and the <code>kubectl</code> command-line interface.</p>
|
||||
|
||||
<h2>Tools</h2>
|
||||
|
||||
<p>The <a href="/docs/tools/">tools</a> page contains a list of native and third-party tools for Kubernetes.</p>
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
layout: docwithnav
|
||||
title: Kubernetes Security and Disclosure Information
|
||||
permalink: /security/
|
||||
assignees:
|
||||
- eparis
|
||||
- erictune
|
||||
- philips
|
||||
- jessfraz
|
||||
---
|
||||
|
||||
## Security Announcements
|
||||
|
||||
Join the [kubernetes-announce](https://groups.google.com/forum/#!forum/kubernetes-announce) group for emails about security and major API announcements.
|
||||
|
||||
## Report a Vulnerability
|
||||
|
||||
We’re extremely grateful for security researchers and users that report vulnerabilities to the Kubernetes Open Source Community. All reports are thoroughly investigated by a set of community volunteers.
|
||||
|
||||
To make a report, please email the private [kubernetes-security@googlegroups.com](mailto:kubernetes-security@googlegroups.com) list with the security details and the details expected for [all Kubernetes bug reports](https://github.com/kubernetes/kubernetes/blob/master/.github/ISSUE_TEMPLATE.md).
|
||||
|
||||
You may encrypt your email to this list using the GPG keys of the [Product Security Team members](https://github.com/kubernetes/community/blob/master/contributors/devel/security-release-process.md#product-security-team-pst). Encryption using GPG is NOT required to make a disclosure.
|
||||
|
||||
### When Should I Report a Vulnerability?
|
||||
|
||||
- You think you discovered a potential security vulnerability in Kubernetes
|
||||
- You are unsure how a vulnerability affects Kubernetes
|
||||
- You think you discovered a vulnerability in another project that Kubernetes depends on (e.g. docker, rkt, etcd)
|
||||
|
||||
### When Should I NOT Report a Vulnerability?
|
||||
|
||||
- You need help tuning Kubernetes components for security
|
||||
- You need help applying security related updates
|
||||
- Your issue is not security related
|
||||
|
||||
## Security Vulnerability Response
|
||||
|
||||
Each report is acknowledged and analyzed by Product Security Team members within 3 working days. This will set off the [Security Release Process](https://github.com/kubernetes/community/blob/master/contributors/devel/security-release-process.md#product-security-team-pst).
|
||||
|
||||
Any vulnerability information shared with Product Security Team stays within Kubernetes project and will not be disseminated to other projects unless it is necessary to get the issue fixed.
|
||||
|
||||
As the security issue moves from triage, to identified fix, to release planning we will keep the reporter updated.
|
||||
|
||||
## Public Disclosure Timing
|
||||
|
||||
A public disclosure date is negotiated by the Kubernetes product security team and the bug submitter. We prefer to fully disclose the bug as soon as possible once a user mitigation is available. It is reasonable to delay disclosure when the bug or the fix is not yet fully understood, the solution is not well-tested, or for vendor coordination. The timeframe for disclosure is from immediate (especially if it's already publicly known) to a few weeks. As a basic default, we expect report date to disclosure date to be on the order of 7 days. The Kubernetes product security team holds the final say when setting a disclosure date.
|
||||
Reference in New Issue
Block a user