Note: This KEP does not target any release; SIG Docs follows a continuous release process for website content.
This KEP seeks consensus on how Kubernetes docs handle two types of content:
- Content from or about third-party providers ("third-party content")
Minimize and eliminate third-party content except when necessary for Kubernetes to function in-project.
- Content hosted on multiple sites ("dual-sourced content")
Minimize and eliminate dual-sourced content except when necessary for Kubernetes to function in-project.
Note: This KEP defines "in project" to mean projects in the Kubernetes org, which includes the kubernetes and kubernetes-sigs repositories.
Kubernetes documentation teaches Kubernetes users about how Kubernetes works, how to use in-project Kubernetes features, and how to build on top of Kubernetes infrastucture.
Feature docs are not a place for vendor pitches. Nonetheless, SIG Docs sometimes receives pull requests to place advertising-like content on the Kubernetes website. Some PRs clearly do not belong in feature docs, but other instances are less clear.
Feature docs also contain dual-sourced content. A good practice for code project docs is to host single-sourced content only, and to provide links to other providers’ single-sourced content. This simplifies version management and reduces the work required to maintain content.
This KEP defines how to handle third-party and dual-sourced content in documentation, so that authors can judge what is appropriate to propose and so that PR approvers can make consistent, fair decisions during the review process.
SIG Docs publishes Kubernetes documentation on kubernetes.io in line with its charter and sets standards for website content. Prior to this KEP, there are no clear guidelines or standards for third-party and dual-sourced content.
The Kubernetes documentation is currently a mix of both 1) documentation describing the Kubernetes open source project; and 2) content describing how to install or use Kubernetes on several third party Kubernetes offerings.
Some third party content is necessary in order for Kubernetes to function. For example: container runtimes (containerd, CRI-o, Docker), networking policy (CNI plugins), Ingress controllers, and logging all require third party components. Pages like Logging Using Stackdriver are highly specific to a third party offering and seem more like third party product documentation than Kubernetes open source documentation.
The goal of Kubernetes documentation is to accurately document in-project functionality for Kubernetes, and to eliminate barriers to effective contribution and understanding.
The goal of this KEP is to reach and document a consensus on what types of third-party content are appropriate for inclusion in Kubernetes documentation; standards for including third-party content; and to create consistent policies for docs handle third-party and dual-sourced content.
To address its goal, this KEP focuses on the following issues:
- What third party content is appropriate for inclusion in the Kubernetes documentation?
Proposed: Third-party content is permitted if it is required for Kubernetes to function in-project.
- Does third party content in sections such as Getting Started in the docs provide sufficient value to the reader that they should remain?
Casual consensus says yes, with one modification:
- Eliminate the production environment table with a link to certified conformance partners.
- Is there a list of content pages that are so focused on third party product usage that they should be removed or updated from the Kubernetes documentation?
- When should the Kubernetes documentation host third party content that isn't maintained by a Kubernetes SIG?
As infrequently as possible, with linking preferred to hosting.
- How does the Kubernetes project handle third party content that is not kept up to date or hosts?
If content isn't refreshed within 180 days, notify stakeholders of 90 days to update content or migrate it elsewhere before removing it. Notification specifically includes:
- Mailing an initial list of affected pages to kubernetes-dev@googlegroups.com
- Announcing the policy change in two Kubernetes community meetings in a row
- Posting a notification of the policy change on the Kubernetes blog
- Notifying SIG PR review aliases on GitHub in PRs that remove affected content
- Can feature owners flag when third party content is required, as opposed to preferable or common?
Is this capability required for KEP approval?
- Who decides when to include third-party content?
SIGs responsible for particular features can include third-party content at their discretion, preferably by linking to the third party's own documentation.
- What standard of quality and review must be met before docs include third-party content?
Third-party content must be necessary for Kubernetes to function in-project.
- To what extent should SIG Docs advocate for third-party content providers to host their own content, or decline to host third-party content altogether?
Kubernetes docs publish third-party content only if:
-
It's necessary for Kubernetes to function. For example: container runtimes (containerd, CRI-o, Docker), networking policy (CNI plugins), Ingress controllers, and logging.
-
It's an applied example of another project in the Kubernetes GitHub org. This includes the kubernetes and kubernetes-sigs repositories.
Third-party content should be linked instead of hosted whenever possible.
- Clearly define what documentation is required so that readers understand how to deploy, operate and consume Kubernetes clusters using features from in-project code and its mandatory dependencies.
- Outright removal of all content relating to vendors and projects outside the Kubernetes project.
- Revise the content guide to achieve the KEP goal:
- Specify that Kubernetes docs are limited to content required for Kubernetes to function in-project. Docs may include third-party OSS content for components that require a third-party solution to function. Docs may include content for other projects in the Kubernetes org, and content from other OSS projects that are necessary for Kubernetes to function. Third-party content must be linked whenever possible, rather than duplicated or hosted in k/website.
- Revise the documentation when the KEP is approved:
- Third-party content: Notify stakeholders of all affected content via GitHub issues and via a single message containing a summary of all affected content to kubernetes-dev@googlegroups.com that non-conforming content will be removed after 90 days.
This limits the impact to out-of-project content and gives current stakeholders approximately one Kubernetes release cycle to migrate third-party content to an alternate platform before removing content from Kubernetes docs.
- Dual-sourced content: Where sourcing is obvious, replace dual-sourced content with links to an authoritative single source. Where sourcing is unclear, notify stakeholders via GitHub issues in k/website and via a single message containing a summary of all affected content to kubernetes-dev@googlegroups.com that non-conforming content will be removed after 90 days.
In all cases where content would be removed, provide adequate time for the relevant SIG to review changes and notify stakeholders.
Alice works for ACME, Inc and wants to gain visibility for ACME Cloud Services, which has just launched a managed Kubernetes cluster product. Alice drafts a change to a concept page so that that it mentions ACME Cloud Services’ Kubernetes product, and submits a pull request.
Bob is a documentation approver. Bob explains that Alice’s proposed change does not meet community standards, because it is functionally an advertisement.
Charlie uses Linux, specifically Ubuntu. Charlie notices that the page
about installing kubethingy has instructions for installing kubethingy
on Windows and on CentOS/RHEL but not on Ubuntu. Charlie reads the
guidelines on content and sees that this kind of change is acceptable
(Ubuntu is one of the most popular Linux distributions, and kubethingy
documentation is acceptable as it is already documented).
Charlie drafts a change and submits a pull request.
Rafael wanted to share a Kubernetes course from an online education provider. Rafael submitted PR #15962 to add the course to Overview of Kubernetes Online Training.
The PR was not approved because SIG Docs didn’t want to add a link to third-party content over which SIG Docs have no control.
Website PR #16203 removes Stackdriver and Elasticsearch vendor content. Since logging falls into the external add-ons category, SIG Docs decided to remove this vendor-specific content that had not been meaningfully updated in three years.
SIG Docs had buy-in from SIG Instrumentation Bugs for removal; however, that PR was held pending the outcome of this KEP and later closed.
In PR #16766 @pouledodue proposed adding Hertzner Cloud Controller to the list of vendors that have implemented a cloud controller manager. That PR was held pending the outcome of this KEP, then later merged.
As hyperkube transitions to third-party maintenance, it's unclear how to handle hyperkube content in the Kubernetes docs or re-point related links.
This KEP originally included language around considering intent of contributors. Because intent is effectively impossible to judge (and because contributions are nearly always made with the best intent), this KEP now specifies that third-party content is limited to what's required for in-project functionality.
SIG Docs may add its own guidelines for writing and reviewing ambiguous content.
For example:
Kubernetes requires out-of-tree software and tools to implement: cluster networking, Ingress, persistent storage, and logging. Hyperlinking to vendor software and documentation is allowed; creating “how to use” content for a specific vendor is discouraged.
Pages that fit with that example guideline:
- Cluster Networking
- Ingress Controllers
- Persistent Volumes
Pages to review and possibly revise, if that guideline were in place:
- Install a Network Policy Provider and child pages: how to use Calico, Cilium, Kube-router, Romana, and Weave Net for NetworkPolicy
- Audit
- Use fluentd to collect and distribute audit events from log file (dual-sourced)
- Use logstash to collect and distribute audit events from webhook backend (vendor-specific content)
- Auditing with Falco (dual-sourced)
- Events in Stackdriver (vendor-specific content)
- Logging Using Elasticsearch and Kibana (vendor-specific content)
- Logging using Stackdriver (vendor-specific content)
None known
Note: this KEP does not target any release
Once the community have reached consensus, prepare a PR to update the existing content guide.
Once the KEP is approved, merge the KEP and then update website content accordingly.
SIG Docs identified no meaningful drawbacks.
The only real alternative—approving third-party content without a vetting policy—is unacceptable, and would degrade site outcomes across metrics of quality, searchability, and trust.