Umbrella Issue: Remove Third-Party Content

[aimeeu]

This is a Bug Report

Problem:
Relates to #15576 - Clarify Style Guide
Some pages contain provider-or-project-specific content from projects that are not inside the kubernetes or kubernetes-sigs GitHub organizations, or are not inside the CNCF.

For discussion around removing third-party content, please refer to these Slack threads:

• https://kubernetes.slack.com/archives/C1J0BPD2M/p1565388220171400
• Simply put: feature docs are not a place for vendor pitches.

Also refer to the Documentation Content Guide when deciding what third-party content should be removed.

This issue is an umbrella tracking issue. Below is a list of check boxes for individual items that need fixing. Some are easy, others require some expertise/experience as a contributor. Please add to this list when you find another page with third-party content.

Proposed Solution:

• Remove content that targets how to do something in k8s installed on specific cloud platforms.
• Remove content that explains how to use a third-party tool with k8s.

Note: Ensure removing English content does not break localizations! Coordinate with language leads.

Pages Being Considered:

• https://kubernetes.io/docs/tasks/debug-application-cluster/logging-elasticsearch-kibana/
• https://kubernetes.io/docs/tasks/debug-application-cluster/events-stackdriver/
• https://kubernetes.io/docs/tasks/debug-application-cluster/logging-stackdriver/
• https://kubernetes.io/docs/tutorials/online-training/overview/ -- an entire page of links to third-party courses; the page says "Here are some of the sites that offer online training for Kubernetes" - yet it isn't a distinct, sorted list of training providers, it's a list of courses
• https://kubernetes.io/docs/setup/#production-environment - the table that lists k8s production environment providers should this be removed
• https://kubernetes.io/docs/tutorials/ - many links to third-party tutorials
• https://kubernetes.io/docs/setup/production-environment/tools/krib/ - this is a whole page about a third party tool
• https://kubernetes.io/docs/setup/production-environment/turnkey/aws/ and the rest of the pages under the Turnkey Cloud Solutions section
• https://kubernetes.io/docs/setup/production-environment/on-premises-vm/cloudstack/ and the rest of the pages in the On-Premises VMs section
• https://kubernetes.io/docs/reference/access-authn-authz/authentication/#configuring-the-api-server mentions and links to third-party Identity Providers because Kubernetes does not provide an OpenID Connect Identity Provider - reexamine providers listed

[aimeeu]

/sig docs
/priority important-soon

[aimeeu]

/lifecycle frozen

[zacharysarah]

Additions to the list:

• https://kubernetes.io/docs/tasks/administer-cluster/network-policy-provider/
• https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/
• https://kubernetes.io/docs/concepts/cluster-administration/addons/
• https://kubernetes.io/docs/concepts/cluster-administration/networking/

[neolit123]

@aimeeu

Some pages contain provider-or-project-specific content from projects that are not inside the kubernetes or kubernetes-sigs GitHub organizations, or are not inside the CNCF.

if we look at the current landscape Docker as a container runtime is not even in the list of supported runtimes by the CNCF:

does this make it third party and we have to remove the installation guide for it?
i would like to remind that we estimated that the Docker users are 70% of our container runtime users.

@zacharysarah

https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/

what particular items from the above link do you want removed?
perhaps some of the CNIs that are not in the above image?

[liggitt]

https://kubernetes.io/docs/setup/#production-environment - the table that lists k8s production environment providers should this be removed

If there's a principled approach to inclusion in that list (e.g. conformance participants), I don't see why it should be removed

[dims]

Agree with @liggitt.

Can we please hold this work?

[dims]

I've raised this on steering@ for guidance as well:
https://groups.google.com/a/kubernetes.io/d/msg/steering/8v8_IkHFX8M/2MXV0z6PAgAJ

[BenTheElder]

Re: https://kubernetes.io/docs/tasks/debug-application-cluster/monitor-node-health/#enable-disable-in-gce-cluster

kube-up.sh IS in project (in the main Kubernetes repo) and this is talking about how to toggle this with that tool FWIW. The project CI uses kube-up extensively for the moment.

Edit: https://github.com/kubernetes/kubernetes/blob/8126201b73b3fa52bd376fc98cb00637af493b72/cluster/kube-up.sh

[aimeeu]

Thanks for your comment @neolit123 ! Yes, instructions for installing Docker should be removed and replaced with something like

Successful installation of Docker is required. Please consult the [Docker Docs](https://docs.docker.com/) for OS-specific installation instructions.

@zacharysarah is at a conference and then on holiday for the rest of September.

Removing items from the https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/ page:

I see you are a kubeadm approver - great!! Since kubeadm is in the kubernetes GitHub org && doesn't have its own instructional content, most of the kubeadm content is OK to stay in the k8s docs. Ideally, as time permits, SIG Docs would like to work with the kubeadm team to move kubeadm-specific content to the kubeadm docs repo. Keep the project docs close to the source code so it's easier (and faster) for developers to keep docs up-to-date.

How about moving moving kubeadm maturity and Support timeframes to the kubernetes/kubeadm README? Then point to that page from the k8s.io page.

See the [kubeadm README](https://github.com/kubernetes/kubeadm) for feature maturity levels and support timeframes.

Installing a pod network add-on section: I could be wrong, but it doesn't look like any of the products listed are CNCF projects or in the kubernetes or kubernetes-sigs, so I would remove the entire tabbed section and replace with something like

You must install a pod network add-on so that your pods can communicate with each other. Detailed installation and configuration instructions for third-party products are beyond the scope of the Kubernetes documentation. You can find network add-ons in the  [CNCF Cloud Native Interactive Landscape](https://landscape.cncf.io/category=cloud-native-network&format=card-mode&grouping=category).

Also remove the Explore other add-ons section.

[aimeeu]

@liggitt, @dims, @BenTheElder - thanks for your feedback!

zacharysarah is at a conference and then on holiday for the rest of September.

The SIG Docs team decided in August to remove third-party content from the k8s docs.
For discussion, please refer to these Slack threads:

• https://kubernetes.slack.com/archives/C1J0BPD2M/p1565388220171400
• Simply put: feature docs are not a place for vendor pitches.

Removing third-party content was discussed at the 20 Aug SIG Docs meeting

We have a new Documentation Content Guide that provides guidance on what content is allowed. I will be changing the content presentation style to replace the bullet point list with sections (Issue #16143) .

Please feel free to add an agenda item to the 1 October SIG Docs meeting (Zach will be back from his vacation). Thanks!

[liggitt]

Most consumers of and contributors to the kubernetes.io site are not represented in SIG docs meetings. Removing helpful links and content wholesale needs broader discussion, in my opinion. I agree there should be guidelines and principles for links to external content, but this direction seems unnecessarily detrimental to users.

[liggitt]

Specifically, I'd expect broad removal of content contributed by SIGs covering use and configuration of their components and features (including extension point documentation that references known/tested external implementations) to be proposed in a KEP with buy-in from the affected component owners

[BenTheElder]

ER ...

My only point so far is that the entire heading linked there discusses using tooling with source contained wholly within the primary Kubernetes repo and used extensively for developing the project. It seems quite relevant to know that this is on by default when kube-up is set to run on GCE (where most of our CI is due to resources being available) and how to toggle it... I disagree that this content is third party. It is maximally first party being in the Kubernetes repo.

This also doesn't seem to be afoul of the guidelines you linked as there aren't docs for this elsewhere.

[neolit123]

@aimeeu

The SIG Docs team decided in August to remove third-party content from the k8s docs.
For discussion, please refer to these Slack threads:

i think a problem with this decision is that it did not get buy-in by other SIGs, such as cluster-lifecycle. who are the maintainers of most of these documents. SIG docs does give the final /approve, but we are doing the heavy lifting there.

SIG Docs would like to work with the kubeadm team to move kubeadm-specific content to the kubeadm docs repo.

the kubeadm documentation is in a pretty good shape. both the maintainers and the users are mostly happy with it. such fragmentation is undesired and maybe sig-docs is ultimately suggesting that it's time to move all the kubeadm docs out of k8s.io?

personally i think we should hold on taking action in these efforts until @zacharysarah is back and we can book a zoom meeting. also as @dims mentioned this issue is already on the Steering radar.

[timothysc]

@kubernetes/sig-docs-en-reviews
/hold
On this effort. You are impacting a number of stakeholders where you have not solicited their feedback or buy-in from those stakeholders. History has taught us that unilateral action that affects multiple stakeholders is against the core values of this project.
cc @kubernetes/steering-committee

[dims]

@timothysc let me /hold the PR(s) since this is a issue :)

whoops the other 3 linked are issues as well!

[timothysc]

I know, I did it for symbolism ;-)

[philips]

Follow-up question for eventual KEP: "Why do we care whether a project is in the CNCF?". Reading the current policy there are several references to policies that differ whether a project is a CNCF project or not:

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

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 an open source project that is not a CNCF project or a project in the kubernetes or kubnetes-sigs GitHub organizations

Content that simply links to information about a non-Kubernetes project
Allowed:
Linking to active CNCF projects
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

This is troubling to me because a non-goal of the CNCF to is to host every piece and part required to make Kubernetes technically successful. It may happen but it shouldn't be a consideration for quality user facing docs.

[aimeeu]

Additions to the list:

• https://kubernetes.io/docs/concepts/cluster-administration/addons/

FYI kubernetes/kubernetes/cluster/addons/README.md links to https://kubernetes.io/docs/concepts/cluster-administration/addons/

[bgrant0607]

To echo what other Steering Committee members have voiced, and as a CNCF TOC member: I don't think this issue is cut and dry.

Kubernetes depended on Etcd and Docker at the time it was donated to CNCF, neither of which was a CNCF project at the time (there were no other CNCF projects!), and still has lots of dependencies on other open-source repos. The CNCF has more projects now, but the full space isn't covered by the CNCF. For instance, there is no equivalent of Elasticsearch in CNCF.

I understand SIG Docs wants to bound its scope, we don't want to host blatant vendor pitches, and we don't want to host documentation that the community can't maintain.

Is there a single list of all the pages being evaluated? Has there been any effort to contact stakeholders of those pages and/or publicize the content guidelines?

I saw some mention of pages actually documenting code that is in kubernetes project github orgs. Is only dual-sourced content being moved/removed?

With respect to Kubernetes providers, is the plan to point to CNCF documentation, such as https://www.cncf.io/certification/software-conformance/?

[bgrant0607]

And regarding KEP: I don't think the intent was to request a KEP for each individual change. KEP is the mechanism we've adopted for significant project changes, especially across SIGs.

[bgrant0607]

Also, I looked at #15892, #15576, and #15774, but the origin of the CNCF project requirement is not clear. There's no precedent in the Kubernetes project for such a distinction that I can recall.

I also looked at the Slack archives, though I have to say that Slack is a poor system of record and a poor mechanism for outreach, and it was no more illuminating.

And I saw no obvious threads on https://groups.google.com/forum/#!forum/kubernetes-sig-docs this year relating to this topic.

I do see it in the meeting agenda in August, but it just refers to the issue above.

[sftim]

My understanding of how this issue came to be opened: the ecosystem is growing, and where there once were a few interfaces to a few cloud providers there could now be hundreds of vendors each wanting to have their control plane / kubeadm alternative / training course / special Ingress controller listed.

SIG Docs wanted to make sure there was some way to manage the potential sprawl of PRs, and it sounds like the approach from circa 2019-08-08 goes too far and drops too much.

[sftim]

Is there a KEP being drafted?

[zacharysarah]

@sftim

Is there a KEP being drafted?

Not yet, I just got back from vacation today. If you'd like to start drafting one, I'd support that. 👍

[zacharysarah]

Hi, folks. 👋 I'm back from vacation. Some thoughts before the steering committee meeting on Wednesday.

From @sftim:

SIG Docs wanted to make sure there was some way to manage the potential sprawl of PRs, and it sounds like the approach from circa 2019-08-08 goes too far and drops too much.

I think that's an elegant summary. I'd add some things:

Out of scope

From @philips:

This is troubling to me because a non-goal of the CNCF to is to host every piece and part required to make Kubernetes technically successful. It may happen but it shouldn't be a consideration for quality user facing docs.

Respectfully, this seems out of scope to the current discussion and doesn't bear directly on the third-party content policy as implemented/proposed.

Moving forward in the near term

Folks have commented that the third-party content policy here doesn't meet the collaborative bar for changes of its size and scope. That's valid.

I'd like to propose (mainly by affirming @liggitt's suggestion) that we proceed by:

1. Putting a /hold on any further PRs for this issue.
2. Per @liggitt:

   reverting Style Guide: Clarify Adding Third-Party Content  #15892 or updating https://kubernetes.io/docs/contribute/style/content-guide/#what-is-and-isn-t-allowed to clarify that those guidelines are proposed and referencing the in-progress KEP.

3. SIG Docs drafts a KEP proposing changes to how K8s docs handle third-party content.
4. The KEP gets adequate review and approval.

Does that seem reasonable?

The relationship of the CNCF to third-party content

Per @bgrant0607's observations, the requirement tying third-party projects to their CNCF status is mine alone, and I take responsibility for it.

The three requirements (that projects reside in kubernetes, kubernetes-sigs, or the CNCF sandbox) for third-party content were an attempt to scope docs to projects with some level of vetting in the larger Kubernetes ecosystem. It is not an attempt to provide an artificial advantage to CNCF projects per @liggitt, nor do I think that the CNCF sandbox requirement is an adequate end state for third-party content requirements. Nonetheless, we had to start somewhere.

I am in no way vested in any CNCF-related requirement for third-party content, for exactly the reasons that @neolit123 (re:Docker) and @philips (re:contradictory internal definitions) point out. It clearly doesn't work, so let's remove it and iterate accordingly.

Effectiveness and scarcity

I agree that SIG Docs hasn't collaborated across SIGs effectively, especially in the past six months. There are some reasons for this:

• SIG Docs has three chairs. Two have been absent.

@jaredbhatti was on sabbatical for three months before transitioning away from K8s altogether. @jimangel has stepped up to replace him, effective September 15 (several days after the comment thread began.)

@Bradamant3 had significantly reduced availability for several months due to a role change at work. While her availability for K8s docs has recently increased, the result was that for several months, one person had to fill a three person job, with results to match.

• SIG Docs has fewer trained writers.

SIG Docs faces an ongoing struggle with scarcity of resources (Google has pulled all of its writers from K8s), and we're trying to address it creatively and actively--but it's not an overnight fix.

Better collaboration

Thanks, @dims, for empathy toward the human impact of responses. 🙇

@liggitt:

Working with component teams to understand why some external links or content exist when putting together the guidelines would be more appropriate than teams finding out about the new policy as their documentation started to get removed.

I agree. That's on me as the chair most directly responsible for this policy and its implementation. I apologize, and I'll make sure we do better going forward.

However, consider these responses:

@neolit123:

SIG docs does give the final /approve, but we are doing the heavy lifting there.

@timothysc:

You are impacting a number of stakeholders where you have not solicited their feedback or buy-in from those stakeholders. History has taught us that unilateral action that affects multiple stakeholders is against the core values of this project.

Please note that these responses were to @aimeeu who, as of September 12, had been a contributor for ~45 days. Are these comments really how the project's most prolific contributors, including a steering committee member, want to respond to new contributors, especially from underrepresented groups?

To date, @neolit123, @dims, and @bgrant0607 are the only commenters to ask questions, rather than make pronouncements. That's not so great. @neolit123 I appreciate that you've asked some salient questions in this issue, but inferring that SIG Docs only makes lightweight contributions to content is pretty gross. 😞

Please, folks:

1. Ask clarifying questions before making judgements.
2. Presume good intent on each others' behalf.
3. Make collaboration an invitation rather than a punishment, especially for new contributors.

TLDR

This issue needs a KEP in order to proceed. SIG Docs can collaborate better, as can everyone.

[neolit123]

@zacharysarah

SIG docs does give the final /approve, but we are doing the heavy lifting there.

@neolit123 I appreciate that you've asked some salient questions in this issue, but inferring that SIG Docs only makes lightweight contributions to content is pretty gross. disappointed

to clarify, content i was referring to like:
https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/
(which is one of the targets for 3rd party content removal)

is maintained and written by the kubeadm maintainers. it's the result of years of improvements and interactions with users, knowing which steps are problematic for them and grading on the content. SIG Docs does provide a quality wordsmith review and ultimately approval and while i wouldn't consider that light weight, i think it's the kubeadm maintainers who should maintain what contents are included in the documentation. unless it's completely out of order, of course.

[zacharysarah]

@neolit123

i think it's the kubeadm maintainers who should maintain what contents are included in the documentation. unless it's completely out of order, of course.

No, agreed, that's as it should be. Feature owners should absolutely maintain their content; what we're trying to do is provide guidance on how to handle content for third party solutions. Right now there's no differentiation (and consequently no enforcement) in docs between content that's unique to k8s.io, content that's hosted in multiple places (leading to content that's stale on k8s.io but current on a third party site, or vice versa), vendors trying to elbow their way into feature docs, and content provided by feature maintainers themselves.

The goal isn't purity. The goal is greater service to users by making sure what they find on k8s.io is current, accurate, and well-bounded.

EDIT: This is also an example of how scarcity (@Bradamant3 has the greatest familiarity with kubeadm docs) leads to confusion.

[neolit123]

Right now there's no differentiation (and consequently no enforcement) in docs between content that's unique to k8s.io, content that's hosted in multiple places (leading to content that's stale on k8s.io but current on a third party site, or vice versa), vendors trying to elbow their way into feature docs, and content provided by feature maintainers themselves.

i can see the problem of duplication and k8s.io vendor docs becoming out of date.

interestingly for some projects like Flannel, which is a CNCF hosted project, we are keeping the k8s website more up to date than the upstream state.

in this particular, this section:
https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/#pod-network

currently contains a certain git SHA that is the result of users reporting breakages, if they followed the upstream docs trying to install this CNI plugin with the latest Kubernetes.

The goal isn't purity. The goal is greater service to users by making sure what they find on k8s.io is current, accurate, and well-bounded.

definitely agreed that better rules should be applied to the website.

EDIT: This is also an example of how scarcity (@Bradamant3 has the greatest familiarity with kubeadm docs) leads to confusion.

we are actually pretty good on the kubeadm side and apart from Docker and the CNI setup i don't see any major third party content offenders for kubeadm.

[sftim]

This is SREcon week for me. I don't know if that means more available time or less for Kubernetes (I'll guess the latter); anyway, I might well be able to contribute towards a KEP.

[zacharysarah]

@bgrant0607

I understand SIG Docs wants to bound its scope, we don't want to host blatant vendor pitches, and we don't want to host documentation that the community can't maintain.

That's the goal, in service of helping users.

Is there a single list of all the pages being evaluated?

Yes: the description for this issue. ☝️

Has there been any effort to contact stakeholders of those pages and/or publicize the content guidelines?

No. The original plan was to contact stakeholders in the case of outright removals and ensure that docs linked to their upstream source, if they met criteria; to engage with stakeholders and help parse freshness of information and hosting location where neither freshness nor upstream source were clear; and for outright removals, to at-mention the original contributors to raise visibility.

I saw some mention of pages actually documenting code that is in kubernetes project github orgs. Is only dual-sourced content being moved/removed?

Removing dual-sourcing is one of the goals. Where projects have their own documentation, it's a best practice to link upstream rather than host the same information twice. It may also make sense to encourage projects to host project-specific docs on their site, rather than in K8s feature docs, which is definitely an opportunity to raise visibility and contact stakeholders about where specific docs should live.

With respect to Kubernetes providers, is the plan to point to CNCF documentation, such as https://www.cncf.io/certification/software-conformance/?

I think the CNCF would be happy with that. I think it's an open question about what will best serve users. Even so--we still need guidelines about where and how that pointing would happen. For example, earlier this year we refactored https://kubernetes.io/docs/setup/ and its subpages to remove the overly vendor-y content from previous versions. (For example, in 1.12: https://v1-12.docs.kubernetes.io/docs/setup/) Do we constrain vendor information (including conformance status) to a single page? That's a good question for a KEP, which we're on board to open.

[aimeeu]

@zacharysarah @jimangel As part of a KEP, I think we need to address the complete lack of documentation guidance in the Kubernetes Repository Guidelines. It would be nice to clarify what content should reside in a project's repo vs the k8s docs. Guidelines would vary between kubernetes and kubernetes-sigs.

[aimeeu]

KEP: kubernetes/enhancements#1327

[sftim]

Give the status and that this is pending a KEP:
/remove-priority important-soon

[sftim]

/priority important-longterm
kubernetes/enhancements#1327 is now doc-policies-for-third-party-content.

[zacharysarah]

This issue is replaced by #20232.

/close

[k8s-ci-robot]

@zacharysarah: Closing this issue.

In response to this:

This issue is replaced by #20232.

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.