Revision of third-party content in documentation #292
Comments
The comment that sugested opening the issue in steering, does not match the issue opened here. That referenced KEP was merged and in effect since May, 2020 indicating the rationale and the exceptions in the KEP itself. Coming back to the content of the original comment, quoting it here:
I personally don't see why we should differentiate betewen OSS projects depending on what foundation they belong to |
While it’s true that the kubernetes/enhancements#1327 was merged in May 2020 and includes rationale and exceptions, the reality is that it was not actively enforced until quite recently. This sudden application of the policy caught many contributors—particularly those involved in multi-tenancy—by surprise ( most of us are not even aware of that KEP ). While I won’t summarize every comment, the key point is that this PR removed valuable community-provided content addressing gaps not yet filled by Kubernetes itself—particularly in multi-tenancy, given that wg-multitenancy and its HNS project were archived. By contrast, documentation around Ingress Controllers, which similarly lacks in-tree implementations, continues to reference multiple third-party solutions.
|
Perhaps it was not applied to already existing content for reasons mentioned before "we've lacked the time and active maintainers to do so, or, quite simply [...] other issues and fixes took priority", but I'm pretty sure it was enforced for new content. Or even better, because of this policy, SIG Docs didn't need to enforce it because contributors already considered it when writing documentation. I definitely did. |
It doesn't seem the case, especially with the Multi Tenancy section: kubernetes/website#48648 has been merged "recently" (2024) along with a disclaimer of third party tools. Not here to point fingers, as @Svarrogh1337 suggested, we'd like to understand the rationale behind this policy, and add exceptions for the projects addressing missing features of Kubernetes such as multi-tenancy. In the original PR reviewed by the community, a maintainer stated that multi tenancy is not required for Kubernetes to work: although this is true, the said documentation is available in the official documentation explaining the challenges of bringing real multi tenancy in Kubernetes, and the several Open Source projects available, as well as their adopters, clearly show there's a niche of users interested on the topic. Taking as example the multi tenancy one, Kubernetes offers the basic tools to implement your desired level, but requiring real code such as mutations and policy enforcement: just theory, no direct implementation. This is a case pretty similar to the Gateway API: https://gateway-api.sigs.k8s.io/implementations/ Just because Kubernetes doesn't have an API for a Tenant definition, it doesn't mean there's no advanced multi tenancy need by users: this is applicable to multiple areas of interest. I'm focusing on Multi Tenancy one since I indirectly contributed to it. Given the lack of implementation, allowing links in this section, the community can benefit of having a clear stance of how it's been addressed in multiple projects: developers can easily give it a try with third party tools, or rather, start to implement their own implementation by browsing real code.
Mostly because we all know there's a difference between a project maintained by a commercial entity vs. the one maintained by a foundation such as the CNCF, like Kubernetes. Correct me if I'm wrong, it seems to me the rationale here isn't about the user but rather avoiding the outbound traffic to projects that wouldn't foster the Kubernetes ecosystem. Talking of multi tenancy, the projects are heavily depending on Kubernetes, and directly foster it. Instead, if we think outbound links are ruining users browsing, this should be true also for Kubernetes SIG projects themselves: any external link should be disallowed at all. |
sorry but that is not true, I think you are confusing the role of OSS foundations on OSS projects, there is a difference between maintaining an OSS project as working on the code, review, adding docs, maintain CI, do releases, organize the community ... that is done by the project contributors, in this case Kubernetes community. Another is to provide legal frameworks, community support, and resources to help projects thrive that is what a foundation does, in this case CNCF CNCF does not do daily work in kubernetes, nor review code or participate in the SIGs, ... what offers is certain guarantees of neutrality, but as an example CNCF projects like linkerd, nats, cilium, kgateway ... are practically "single company", one company maintain the project (modulo sporadic contributions) with their employees , and that is not bad, on the contrary, that a company decide to open source its product is a great benefit for all of us .... what I'm trying to point out is that even in a foundation, there is no guarantee something like https://www.cncf.io/blog/2025/05/01/protecting-nats-and-the-integrity-of-open-source-cncfs-commitment-to-the-community/ can happen. So, I stand on my opinion that we should not use Foundation as discriminator and focus on OSS and benefits to the kubernetes project. |
I have my opinion but I think it's more profitable if we stick to the topic we're discussing here, such as external links on documentation. |
|
|
I'm with @aojea regarding the interpretation of "third-party" from the KEP: the Kubernetes project is one entity, everyone else is a "third-party". Whether some third-party content that gets linked to is from a commercial vendor selling closed source software or from truly vendor-neutral CNCF project doesn't matter. One could of course argue that the KEP should make a distinction and allow links to certain types of third-party content. But then Kubernetes maintainers and SIG Docs become gatekeepers for what is or isn't suitable. Based on popularity? That excludes new projects. Based on merit? Most doc reviews won't have the skills to determine that. Everything? That could turn the Kubernetes documentation into a dumping ground for links, which doesn't help users. This issue was created to "to better understand the rationale behind the policy". My personal answer: to avoid giving some projects/companies/people preferred treatment over others, and to avoid disputes because the policy is trying to avoid human judgment calls. Has it been applied sufficiently? Apparently not, and also more work seems to remain ("Revise the documentation when the KEP is approved"). But that does not mean that the KEP became invalid or obsolete. |
That's exactly the point of the discussion, but it started going sideways with us vs them arguments. |
|
I'm still confused by the whole point here, can you help me to understand if the third party link policy applies here too? https://kubernetes.io/docs/setup/production-environment/turnkey-solutions/ |
|
Note that https://kubernetes.io/docs/setup/production-environment/turnkey-solutions explicitly does not make the Kubernetes project the gatekeeper. It's a single link (https://landscape.cncf.io/embed/embed.html?key=platform--certified-kubernetes-hosted&headers=false&style=shadowed&size=md&bg-color=%233371e3&fg-color=%23ffffff&iframe-resizer=true) that resolves to several different projects. This meets the goals of the KEP (no preferred treatment because the CNCF certification is open to everyone on equal terms, no disputes). I think it is supported by the allowed exception ("necessary for Kubernetes to function") because in practice most users will not install and run Kubernetes from scratch. |
|
Overall, I appreciate the all tradeoffs and challenges discussed, but do feel that that there are cases beyond the stated exception where referencing projects is helpful for Kubernetes users and the community. I think we can all agree that:
The gray area I see with the allowed exception ("necessary for Kubernetes to function") is interpreting it for features like multi-tenancy. Kubernetes does not require multi-tenancy or workload isolation to function, but most users's do. And to properly implement multi-tenancy (and other similar features) projects and tools are required. We had debated this in the multi-tenancy WG, and at that time decided to proceed with the end user's best interest in mind. Solving the second issue (maintainer's burden) is also important. I feel that it can be achieved with some strict processes and shifting the burden of proof to contributors. On CNCF projects vs other OSS: in my conversations with end users several have mentioned they specifically favor CNCF projects especially at the higher levels of project maturity, as there is an understandable notion of greater stability, a vetting process, and open governance. A potential challenge with allowing all OSS 3rd party projects, is the maintenance burden as projects evolve, or when there are governance changes, etc. |
Based on whether it helps users accomplish their goals, as that's the purpose of documentation — whether that includes links or not.
And it's a good example of how a policy like that doesn't help accomplish that goal. This discussion started in a PR removing links relevant to the topic, likely to be helpful for users trying to solve problems in that space. Spraying a hundred corporate logos on a page without context doesn't do any of that. FWIW, links to external resources don't necessarily have to be embedded directly in docs pages. Having a dedicated "Ecosystem" section listing relevant projects based on category or use case, and then link to that category from relevant documentation, is one way to accomplish a buffer of sorts between documentation and direct links to external resources. OPA does this, as do many other projects. As the purpose of links should be to help its readers, I also don't think the value of links should be weighed based on which foundation some project belongs to. Jim makes a good point though that CNCF projects at least come with some guarantees around licensing and such. Perhaps a little CNCF marker on those projects would work to have them stand out a little. |
Nobody has made that argument. The kubernetes project doesn't want to sit in the middle of infighting to be listed, preferred etc. Users have tons of options to discover more about the ecosystem, but special care must be taken for what we ourselves implicitly or explicitly endorse. The TOC has some good language on this problem:
💯
While the CNCF runs the certification program, Kubernetes defines and maintains the APIs, the behavior definition, and the tests that enforce this. Nothing is listed in that link without being certified. The referenced multi-tenancy tools are entirely third party APIs and no aspect of this is maintained by Kubernetes.
This ... is a lot of opinion. "properly implement" etc. We have upstream groups that determine if something is necessarily part of Kubernetes (SIG Architecture, Node, Security, Auth ...), if they do, we typically include it in the core. There are lots of things you could argue many users have found necessary from their point of view in building a platform atop Kubernetes, but those are all choices of the platform being built. Those things are not necessarily things the project maintains or endorses. Kubernetes is fundamentally built to enable building on top of in ways nobody even considered originally. Those things do not all become part of our docs. There are lots of existing venues including our blog and the CNCF's resources for showcasing extensions etc atop Kubernetes. We don't intend to document the entire ecosystem ourselves, nor do we want to burden our maintainers with this sort of controversy.
Agreed, I've already widely seen this considered for years with no major complaints. Sure there are some legacy gaps, but we haven't been expanding them, and we've slowly been cleaning them up (e.g. you will no longer see docs for kube-up.sh GCE scripts even though those are in the main repo). You'll also note pages like https://kubernetes.io/docs/tasks/tools/ only contain Kubernetes subprojects, not third party, and not CNCF.
The CNCF has resources (e.g. the landscape) for showcasing CNCF projects broadly. This is outside of the scope of the Kubernetes organization. kubernetes/enhancements#1327 is a rather old, accepted KEP. |
Agree. CNCF already provides resources like the Landscape, whitepapers (perhaps a Multi-Tenancy whitepaper?), and the Radar reports. It might be more appropriate to present this kind of work as a third-party reference in a similar format. BTW, when the working group was archived, it was mentioned that some of the follow-up work would be more suitable to continue under a CNCF TAG. |
Problem Statement
This issue serves as a follow-up to kubernetes/website#51014.
To summarize: kubernetes/enhancements#1327 introduced a new policy regarding third-party content. However, this change went largely unnoticed until it surfaced during the review of PR #51014.
Several maintainers and contributors shared their concerns about the policy, and it was suggested that the conversation be continued here to more effectively address feedback from the community.
Proposed Solution
Initiate a formal discussion with the Kubernetes Steering Committee to better understand the rationale behind the policy introduced in kubernetes/enhancements#1327. This will help clarify the intent, scope, and long-term vision for third-party content guidelines.
The text was updated successfully, but these errors were encountered: