Skip to content
Permalink
Browse files

KEP 1327: Apply feedback for third party and dual sourced content (#1…

…9486)

* Apply feedback for third party and dual sourced content

Add feedback from sftim

clarify which slack

* Limit third-party content to OSS

See kubernetes/enhancements#1327 (comment) for more discussion
  • Loading branch information
zacharysarah committed Mar 17, 2020
1 parent a2844f7 commit 329c823aa68f74fbbcb2ef302c0123127bd96182
Showing with 53 additions and 149 deletions.
  1. +52 −91 content/en/docs/contribute/style/content-guide.md
  2. +1 −58 content/en/docs/setup/_index.md
@@ -10,107 +10,68 @@ card:
---

{{% capture overview %}}
This page contains guidelines for adding content to the Kubernetes documentation.
If you have questions about allowed content, join the [Kubernetes Slack](http://slack.k8s.io/) #sig-docs channel and ask! 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 in the [Style guide](/docs/contribute/style/style-guide).
This page contains guidelines for Kubernetes documentation.

If you have questions about what's allowed, join the #sig-docs channel in
[Kubernetes Slack](http://slack.k8s.io/) and ask!

You can register for Kubernetes Slack at http://slack.k8s.io/.

For information on creating new content for the Kubernetes
docs, follow the [style guide](/docs/contribute/style/style-guide).

{{% /capture %}}

{{% capture body %}}
## Contributing content

The Kubernetes documentation comprises the content of the
[kubernetes/website](https://github.com/kubernetes/website) source repository.
## Overview

Source for the Kubernetes website, including the docs, resides in the
[kubernetes/website](https://github.com/kubernetes/website) repository.

Located in the `kubernetes/website/content/<language_code>/docs` folder, the
majority of the Kubernetes documentation is specific to the [Kubernetes
project](https://github.com/kubernetes/kubernetes). The Kubernetes
documentation may also include content from projects in the
[kubernetes](https://github.com/kubernetes) and
[kubernetes-sigs](https://github.com/kubernetes-sigs) GitHub organizations if
those projects do not have their own documentation. Linking to active kubernetes,
kubernetes-sigs, and ({{< glossary_tooltip text="CNCF" term_id="cncf" >}}) projects from the Kubernetes documentation is always
allowed, but linking to vendor-specific products is not. Check the CNCF project lists
([Graduated/Incubating](https://www.cncf.io/projects/),
[Sandbox](https://www.cncf.io/sandbox-projects/),
[Archived](https://www.cncf.io/archived-projects/)) if you are unsure of a
project's CNCF status.

### Dual-sourced content

Kubernetes documentation does not include duplicate content sourced from multiple
locations (*dual-sourced* content). Dual-sourced content requires duplicated
effort from project maintainers and tends to become outdated more quickly.
Before adding content, ask yourself this:

- Is the content about an active CNCF project OR a project in the kubernetes or kubernetes-sigs GitHub organizations?
- If yes, then:
- Does the project have its own documentation?
- if yes, link to the project's documentation from the Kubernetes documentation
- if no, add the content to the project's repository if possible and then link to it from the Kubernetes documentation
- If no, then:
- Stop!
- Adding content about vendor-specific products is not allowed
- Linking to vendor-specific documentation and websites is not allowed

### What is and isn't allowed

There are some scenarios in which the Kubernetes documentation includes content from non-Kubernetes projects.
Below are general categories of non-Kubernetes project content along with guidelines of what is and is not allowed:

1. Instructional content involving non-Kubernetes projects during setup or operation of Kubernetes
- Allowed:
- Referring to or linking to existing documentation about a CNCF project or a project in the kubernetes or kubernetes-sigs GitHub organizations
- Example: for installating Kubernetes in a learning environment, including a prerequisite stating that successful installation and configuration of minikube is required and linking to the relevant minikube documentation
- Adding content for kubernetes or kubernetes-sigs projects that don't have their own instructional content
- Example: including [kubeadm](https://github.com/kubernetes/kubeadm) installation and troubleshooting instructions
- Not Allowed:
- Adding content that duplicates documentation in another repository
- Examples:
- Including minikube installation and configuration instructions; minikube has its own [documentation](https://minikube.sigs.k8s.io/docs/) that provides those instructions
- Including instructions for installing Docker, CRI-O, containerd, and other container runtimes on various operating systems
- Including instructions for installing Kubernetes on production environments using various projects:
- Kubernetes Rebar Integrated Bootstrap (KRIB) is a vendor-specific project and content belongs in the vendor's documentation
- [Kubernetes Operations (kops)](https://github.com/kubernetes/kops) has installation instructions and tutorials in its GitHub repository
- [Kubespray](https://kubespray.io) has its own documentation
- Adding a tutorial that explains how to perform a task using a vendor-specific product or an open source project that is not a CNCF project or a project in the kubernetes or kubnetes-sigs GitHub organizations
- Adding a tutorial on how to use a CNCF project or a project in the kubernetes or kubnetes-sigs GitHub organizations if the project has its own documentation
1. Detailed technical content about how to use a non-Kubernetes project or how that project is designed

Adding this type of content to the Kubernetes documentation is not allowed.
1. Content that describes a non-Kubernetes project
- Allowed:
- Adding a brief introductory paragraph about a CNCF project or a project in the kubernetes or kubernetes-sigs GitHub organizations; the paragraph may contain links to the project
- Not Allowed:
- Adding content describing a vendor-specific product
- Adding content describing an open source project that is not a CNCF project or a project in the kubernetes or kubnetes-sigs GitHub organizations
- Adding content that duplicates documentation from another project, regardless of source repository
- Example: adding [Kubernetes in Docker (KinD)](https://kind.sigs.k8s.io) documentation to the Kubernetes documentation
1. Content that simply links to information about a non-Kubernetes project
- Allowed:
- Linking to projects in the kubernetes and kubernetes-sigs GitHub organizations
- Example: linking to Kubernetes in Docker (KinD) [documentation](https://kind.sigs.k8s.io/docs/user/quick-start), which resides in the kubernetes-sigs GitHub organization
- Linking to active CNCF projects
- Example: linking to the Prometheus [documentation](https://prometheus.io/docs/introduction/overview/); Prometheus is an active CNCF project
- Not Allowed:
- Linking to vendor-specific products
- Linking to archived CNCF projects
- Linking to inactive projects in the kubernetes and kubernetes-sigs GitHub organizations
- Linking to open source projects that are not CNCF projects or do not reside in the kubernetes or kubernetes-sigs GitHub organizations
1. Content about training courses
- Allowed:
- Linking to vendor-neutral Kubernetes training courses offered by the [CNCF](https://www.cncf.io/), the [Linux Foundation](https://www.linuxfoundation.org/), and the [Linux Academy](https://linuxacademy.com/), which is a partner of the Linux Foundation
- Example: linking to Linux Academy courses such as [Kubernetes Quick Start](https://linuxacademy.com/course/kubernetes-quick-start/) and [Kubernetes Security](https://linuxacademy.com/course/kubernetes-security/)
- Not Allowed:
- Linking to online training outside of the CNCF, the Linux Foundation, or the Linux Academy; the Kubernetes documentation does not link to third-party content
- Example: linking to Kubernetes tutorials or courses on Medium, KodeKloud, Udacity, Coursera, learnk8s, and similar websites
- Linking to vendor-specific tutorials regardless of the training provider
- Example: linking to Linux Academy courses such as [Google Kubernetes Engine Deep Dive](https://linuxacademy.com/google-cloud-platform/training/course/name/google-kubernetes-engine-deep-dive) and [Amazon EKS Deep Dive](https://linuxacademy.com/course/amazon-eks-deep-dive/)
majority of Kubernetes documentation is specific to the [Kubernetes
project](https://github.com/kubernetes/kubernetes).

## What's allowed

Kubernetes docs permit only some kinds of content.

### Third party content
Kubernetes documentation includes applied examples of projects in the Kubernetes project&emdash;projects that live in the [kubernetes](https://github.com/kubernetes) and
[kubernetes-sigs](https://github.com/kubernetes-sigs) GitHub organizations.

Links to active content in the Kubernetes project are always allowed.

Kubernetes requires some third party content to function. Examples include container runtimes (containerd, CRI-O, Docker),
[networking policy](/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) (CNI plugins), [Ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/), and [logging](https://kubernetes.io/docs/concepts/cluster-administration/logging/).

Docs can link to third-party open source software (OSS) outside the Kubernetes project if it's necessary for Kubernetes to function.

### Dual sourced content

Wherever possible, Kubernetes docs link to canonical sources instead of hosting
dual-sourced content.

Dual-sourced content requires double the effort (or more!) to maintain
and grows stale more quickly.

{{< note >}}

If you're a maintainer for a Kubernetes project and need help hosting your own docs,
ask for help in [#sig-docs on Kubernetes Slack](https://kubernetes.slack.com/messages/C1J0BPD2M/).

{{< /note >}}

### More information

If you have questions about allowed content, join the [Kubernetes Slack](http://slack.k8s.io/) #sig-docs channel and ask!

{{% /capture %}}

{{% capture whatsnext %}}

* Read the [Style guide](/docs/contribute/style/style-guide).

{{% /capture %}}
@@ -53,63 +53,6 @@ If you're learning Kubernetes, use the Docker-based solutions: tools supported b

When evaluating a solution for a production environment, consider which aspects of operating a Kubernetes cluster (or _abstractions_) you want to manage yourself or offload to a provider.

Some possible abstractions of a Kubernetes cluster are {{< glossary_tooltip text="applications" term_id="applications" >}}, {{< glossary_tooltip text="data plane" term_id="data-plane" >}}, {{< glossary_tooltip text="control plane" term_id="control-plane" >}}, {{< glossary_tooltip text="cluster infrastructure" term_id="cluster-infrastructure" >}}, and {{< glossary_tooltip text="cluster operations" term_id="cluster-operations" >}}.

The following diagram lists the possible abstractions of a Kubernetes cluster and whether an abstraction is self-managed or managed by a provider.

Production environment solutions![Production environment solutions](/images/docs/KubernetesSolutions.svg)

{{< table caption="Production environment solutions table lists the providers and the solutions." >}}
The following production environment solutions table lists the providers and the solutions that they offer.

|Providers | Managed | Turnkey cloud | On-prem datacenter | Custom (cloud) | Custom (On-premises VMs)| Custom (Bare Metal) |
| --------- | ------ | ------ | ------ | ------ | ------ | ----- |
| [Agile Stacks](https://www.agilestacks.com/products/kubernetes)| | &#x2714; | &#x2714; | | |
| [Alibaba Cloud](https://www.alibabacloud.com/product/kubernetes)| | &#x2714; | | | |
| [Amazon](https://aws.amazon.com) | [Amazon EKS](https://aws.amazon.com/eks/) |[Amazon EC2](https://aws.amazon.com/ec2/) | | | |
| [AppsCode](https://appscode.com/products/pharmer/) | &#x2714; | | | | |
| [APPUiO](https://appuio.ch/)  | &#x2714; | &#x2714; | &#x2714; | | | |
| [Banzai Cloud Pipeline Kubernetes Engine (PKE)](https://banzaicloud.com/products/pke/) | | &#x2714; | | &#x2714; | &#x2714; | &#x2714; |
| [CenturyLink Cloud](https://www.ctl.io/) | | &#x2714; | | | |
| [Cisco Container Platform](https://cisco.com/go/containers) | | | &#x2714; | | |
| [Cloud Foundry Container Runtime (CFCR)](https://docs-cfcr.cfapps.io/) | | | | &#x2714; |&#x2714; |
| [CloudStack](https://cloudstack.apache.org/) | | | | | &#x2714;|
| [Canonical](https://ubuntu.com/kubernetes) | &#x2714; | &#x2714; | &#x2714; | &#x2714; |&#x2714; | &#x2714;
| [Containership](https://containership.io) | &#x2714; |&#x2714; | | | |
| [D2iQ](https://d2iq.com/) | | [Kommander](https://docs.d2iq.com/ksphere/kommander/) | [Konvoy](https://d2iq.com/solutions/ksphere/konvoy) | [Konvoy](https://d2iq.com/solutions/ksphere/konvoy) | [Konvoy](https://d2iq.com/solutions/ksphere/konvoy) | [Konvoy](https://d2iq.com/solutions/ksphere/konvoy) |
| [Digital Rebar](https://provision.readthedocs.io/en/tip/README.html) | | | | | | &#x2714;
| [DigitalOcean](https://www.digitalocean.com/products/kubernetes/) | &#x2714; | | | | |
| [Docker Enterprise](https://www.docker.com/products/docker-enterprise) | |&#x2714; | &#x2714; | | | &#x2714;
| [Gardener](https://gardener.cloud/) | &#x2714; | &#x2714; | &#x2714; | &#x2714; | &#x2714; | [Custom Extensions](https://github.com/gardener/gardener/blob/master/docs/extensions/overview.md) |
| [Giant Swarm](https://www.giantswarm.io/) | &#x2714; | &#x2714; | &#x2714; | |
| [Google](https://cloud.google.com/) | [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine/) | [Google Compute Engine (GCE)](https://cloud.google.com/compute/)|[GKE On-Prem](https://cloud.google.com/gke-on-prem/) | | | | | | | |
| [Hidora](https://hidora.com/) | &#x2714; | &#x2714;| &#x2714; | | | | | | | |
| [IBM](https://www.ibm.com/in-en/cloud) | [IBM Cloud Kubernetes Service](https://cloud.ibm.com/kubernetes/catalog/cluster)| |[IBM Cloud Private](https://www.ibm.com/in-en/cloud/private) | |
| [Ionos](https://www.ionos.com/enterprise-cloud) | [Ionos Managed Kubernetes](https://www.ionos.com/enterprise-cloud/managed-kubernetes) | [Ionos Enterprise Cloud](https://www.ionos.com/enterprise-cloud) | |
| [Kontena Pharos](https://www.kontena.io/pharos/) | |&#x2714;| &#x2714; | | |
| [KubeOne](https://kubeone.io/) | | &#x2714; | &#x2714; | &#x2714; | &#x2714; | &#x2714; |
| [Kubermatic](https://kubermatic.io/) | &#x2714; | &#x2714; | &#x2714; | &#x2714; | &#x2714; | &#x2714; |
| [KubeSail](https://kubesail.com/) | &#x2714; | | | | |
| [Kubespray](https://kubespray.io/#/) | | | |&#x2714; | &#x2714; | &#x2714; |
| [Kublr](https://kublr.com/) |&#x2714; | &#x2714; |&#x2714; |&#x2714; |&#x2714; |&#x2714; |
| [Microsoft Azure](https://azure.microsoft.com) | [Azure Kubernetes Service (AKS)](https://azure.microsoft.com/en-us/services/kubernetes-service/) | | | | |
| [Mirantis Cloud Platform](https://www.mirantis.com/software/kubernetes/) | | | &#x2714; | | |
| [NetApp Kubernetes Service (NKS)](https://cloud.netapp.com/kubernetes-service) | &#x2714; | &#x2714; | &#x2714; | | |
| [Nirmata](https://www.nirmata.com/) | | &#x2714; | &#x2714; | | |
| [Nutanix](https://www.nutanix.com/en) | [Nutanix Karbon](https://www.nutanix.com/products/karbon) | [Nutanix Karbon](https://www.nutanix.com/products/karbon) | | | [Nutanix AHV](https://www.nutanix.com/products/acropolis/virtualization) |
| [OpenNebula](https://www.opennebula.org) |[OpenNebula Kubernetes](https://marketplace.opennebula.systems/docs/service/kubernetes.html) | | | | |
| [OpenShift](https://www.openshift.com) |[OpenShift Dedicated](https://www.openshift.com/products/dedicated/) and [OpenShift Online](https://www.openshift.com/products/online/) | | [OpenShift Container Platform](https://www.openshift.com/products/container-platform/) | | [OpenShift Container Platform](https://www.openshift.com/products/container-platform/) |[OpenShift Container Platform](https://www.openshift.com/products/container-platform/)
| [Oracle Cloud Infrastructure Container Engine for Kubernetes (OKE)](https://docs.cloud.oracle.com/iaas/Content/ContEng/Concepts/contengoverview.htm) | &#x2714; | &#x2714; | | | |
| [oVirt](https://www.ovirt.org/) | | | | | &#x2714; |
| [Pivotal](https://pivotal.io/) | | [Enterprise Pivotal Container Service (PKS)](https://pivotal.io/platform/pivotal-container-service) | [Enterprise Pivotal Container Service (PKS)](https://pivotal.io/platform/pivotal-container-service) | | |
| [Platform9](https://platform9.com/) | [Platform9 Managed Kubernetes](https://platform9.com/managed-kubernetes/) | | [Platform9 Managed Kubernetes](https://platform9.com/managed-kubernetes/) | &#x2714; | &#x2714; | &#x2714;
| [Rancher](https://rancher.com/) | | [Rancher 2.x](https://rancher.com/docs/rancher/v2.x/en/) | | [Rancher Kubernetes Engine (RKE)](https://rancher.com/docs/rke/latest/en/) | | [k3s](https://k3s.io/)
| [Supergiant](https://supergiant.io/) | |&#x2714; | | | |
| [SUSE](https://www.suse.com/) | | &#x2714; | | | |
| [SysEleven](https://www.syseleven.io/) | &#x2714; | | | | |
| [Tencent Cloud](https://intl.cloud.tencent.com/) | [Tencent Kubernetes Engine](https://intl.cloud.tencent.com/product/tke) | &#x2714; | &#x2714; | | | &#x2714; |
| [VEXXHOST](https://vexxhost.com/) | &#x2714; | &#x2714; | | | |
| [VMware](https://cloud.vmware.com/) | [VMware Cloud PKS](https://cloud.vmware.com/vmware-cloud-pks) |[VMware Enterprise PKS](https://cloud.vmware.com/vmware-enterprise-pks) | [VMware Enterprise PKS](https://cloud.vmware.com/vmware-enterprise-pks) | [VMware Essential PKS](https://cloud.vmware.com/vmware-essential-pks) | |[VMware Essential PKS](https://cloud.vmware.com/vmware-essential-pks)
| [Z.A.R.V.I.S.](https://zarvis.ai/) | &#x2714; | | | | | |
For a list of [Certified Kubernetes](https://github.com/cncf/k8s-conformance/#certified-kubernetes) providers, see "[Partners](https://kubernetes.io/partners/#conformance)".

{{% /capture %}}

0 comments on commit 329c823

Please sign in to comment.
You can’t perform that action at this time.