whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

KEP 1327: Apply feedback for third party and dual sourced content (#19486)

Browse Source 
* Apply feedback for third party and dual sourced content

Add feedback from sftim

clarify which slack

* Limit third-party content to OSS

See https://github.com/kubernetes/enhancements/pull/1327#discussion_r392966251 for more discussion
This commit is contained in:
Zach Corleissen
2020-03-17 15:45:25 -07:00
committed by GitHub
parent a2844f7390
commit 329c823aa6
2 changed files with 46 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/contribute/style/content-guide.md
+45 -84
View File
@@ -10,107 +10,68 @@ card:
--- ---
{{% capture overview %}} {{% 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 This page contains guidelines for Kubernetes documentation.
docs, follow the instructions in the [Style guide](/docs/contribute/style/style-guide).
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 %}}
{{% capture body %}} {{% capture body %}}
## Contributing content
The Kubernetes documentation comprises the content of the ## Overview
[kubernetes/website](https://github.com/kubernetes/website) source repository.
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 Located in the `kubernetes/website/content/<language_code>/docs` folder, the
majority of the Kubernetes documentation is specific to the [Kubernetes majority of Kubernetes documentation is specific to the [Kubernetes
project](https://github.com/kubernetes/kubernetes). The Kubernetes project](https://github.com/kubernetes/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 ## What's allowed
Kubernetes documentation does not include duplicate content sourced from multiple Kubernetes docs permit only some kinds of content.
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? ### Third party content
- If yes, then: Kubernetes documentation includes applied examples of projects in the Kubernetes project&emdash;projects that live in the [kubernetes](https://github.com/kubernetes) and
- Does the project have its own documentation? [kubernetes-sigs](https://github.com/kubernetes-sigs) GitHub organizations.
- 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 Links to active content in the Kubernetes project are always allowed.
There are some scenarios in which the Kubernetes documentation includes content from non-Kubernetes projects. Kubernetes requires some third party content to function. Examples include container runtimes (containerd, CRI-O, Docker),
Below are general categories of non-Kubernetes project content along with guidelines of what is and is not allowed: [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/).
1. Instructional content involving non-Kubernetes projects during setup or operation of Kubernetes Docs can link to third-party open source software (OSS) outside the Kubernetes project if it's necessary for Kubernetes to function.
- 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. ### Dual sourced content
1. Content that describes a non-Kubernetes project
- Allowed: Wherever possible, Kubernetes docs link to canonical sources instead of hosting
- 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 dual-sourced content.
- Not Allowed:
- Adding content describing a vendor-specific product Dual-sourced content requires double the effort (or more!) to maintain
- Adding content describing an open source project that is not a CNCF project or a project in the kubernetes or kubnetes-sigs GitHub organizations and grows stale more quickly.
- 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 {{< note >}}
1. Content that simply links to information about a non-Kubernetes project
- Allowed: If you're a maintainer for a Kubernetes project and need help hosting your own docs,
- Linking to projects in the kubernetes and kubernetes-sigs GitHub organizations ask for help in [#sig-docs on Kubernetes Slack](https://kubernetes.slack.com/messages/C1J0BPD2M/).
- 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 {{< /note >}}
- Example: linking to the Prometheus [documentation](https://prometheus.io/docs/introduction/overview/); Prometheus is an active CNCF project
- Not Allowed: ### More information
- 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/)
If you have questions about allowed content, join the [Kubernetes Slack](http://slack.k8s.io/) #sig-docs channel and ask! If you have questions about allowed content, join the [Kubernetes Slack](http://slack.k8s.io/) #sig-docs channel and ask!
{{% /capture %}} {{% /capture %}}
{{% capture whatsnext %}} {{% capture whatsnext %}}
* Read the [Style guide](/docs/contribute/style/style-guide). * Read the [Style guide](/docs/contribute/style/style-guide).
{{% /capture %}} {{% /capture %}}
content/en/docs/setup/_index.md
+1 -58
View File
@@ -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. 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" >}}. For a list of [Certified Kubernetes](https://github.com/cncf/k8s-conformance/#certified-kubernetes) providers, see "[Partners](https://kubernetes.io/partners/#conformance)".
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; | | | | | |
{{% /capture %}} {{% /capture %}}