Where should the karpenter.sh Docs Live?

[jonathan-innis]

Description

What problem are you trying to solve?

karpenter.sh is currently AWS-owned and lives inside of the aws/karpenter repository inside of the website directory. These docs are currently AWS-specific and include details that are both relevant to the upstream karpenter project that lives in this repo as well as the CloudProvider specific details for AWS.

Now that the Karpenter project has been migrated over to kubernetes-sigs and Azure has their own CloudProvider implementation of Karpenter (https://github.com/Azure/karpenter), we need to find a more natural home for the docs as well as we need to define some structure around how we are planning to organize the docs.

IMO, we need to settle on the following things:

• How do we delineate the CloudProvider-specific concepts in Karpenter from the neutral ones? CAPI has chosen to take an approach by sub-domaining their docs sites, having a neutral site with some shared details (as well as a little bit of cloudprovider-specific details) while allowing cloudproviders to make changes as needed to their specific docs sites. Do we want to take the same approach or is there another way that we can handle the merge?
• How do we want to version the docs? Currently, karpenter.sh has some versioning information, including breaking change information that is specific to the AWS CloudProvider release of Karpenter. Since these docs are meant to be a user-facing site, I don't think it makes sense to change these docs to only be about the breaking changes or release changes in the Karpenter kubernetes-sigs library; however, we need to come to some conclusion if it makes sense to provider cloudprovider version-specific information in the docs and understand how that is going to affect the overall versioning of the site.
• (smaller item) Do we want the docs to live in the same kubernetes-sigs/karpenter repo or do we want the docs to live in their own repo like kubernetes-sigs/karpenter-docs? One benefit of the docs living in their own repo is that it is a bit easier to track changes and version the docs separately. The downside of doing this is that you can't submit PRs that contain both docs changes and code changes (though this might not be a big deal practically for the kubernetes-sigs repo)

Please feel free to expand on this set of initial questions if you think I missed anything and provide any feedback based on learnings from other project or how the upstream K8s docs evolved.

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
• Please do not leave "+1" or "me too" comments, they generate extra noise for issue followers and do not help prioritize the request
• If you are interested in working on this issue or have submitted a pull request, please leave a comment

[jonathan-innis]

/kind documentation

[jonathan-innis]

cc: @jackfrancis @tallaxes @Bryce-Soghigian @ellistarn @dtzar

[dtzar]

I started down the path of creating a provider-specific docs page for the Azure provider here.

IMO:

1. The central kubernetes-sigs/karpenter (previously karpenter-core) should also be the shared location of the website content at aws/karpenter, but refactored. I have a spreadsheet with content mapping I can share soon.
2. The version number on that website should be pinned to the version of kubernetes-sigs/karpenter
3. Any provider-specific documentation there should embed docs from the provider's webpage and not have versions, simply use the latest version there. Provide a general notice there of something like, this is the latest version of the provider. For other versions, visit .

[sftim]

Hi. SIG Docs tech lead here.

For any code that is part of Kubernetes, even if it only integrates with one cloud provider, we're happy to document it and its behavior. Donating code to Kubernetes means you get a SIG willing to help you do that: Docs.
If there's out-of-project code, even using our open source code, we prefer to signpost readers rather than provide documentation.

For example, we - Kubernetes - are more than happy document the AWS Load Balancer Controller and the GCP integration for Cluster API. We don't document kube2iam or EKS Pod Identity because those are not part of Kubernetes itself.

[sftim]

How about making a website https://karpenter.dev/ that documents the open-source core? AWS could set up https://karpenter.aws/

In this world, https://karpenter.sh/ becomes a service that does redirection and signposting only.

---

And, ideally, all the related websites share a common, usable look-and-feel.

[Bryce-Soghigian]

Sig Docs contributions would be greatly appreciated! Thank you for offering @sftim!!

I disagree that provider specific documentation should be completely separate. I think a majority of the ideas in karpenter.sh apply broadly to both providers. But Ideally each section of the docs would be able to have conditional content to showcase any differences between providers in one place(Not familiar how easy this is to do with hugo). There are a few major differences but would be good to see things in one place.

I would suggest we create a separate docs repo for all karpenter providers to contribute to. Even if we do decide to do provider specific documentation, it would be nice for all the code to live in one place.

Just general ideas/thoughts I have here.

[dtzar]

I like the hybrid approach best where there is local repo control of documents at the provider, but an embed mode for the core content. This is a balance between what @sftim and @Bryce-Soghigian are saying.

So effectively you have https://karpenter.sh having the core documents but also some essential docs included which are embeded from the provider's website (e.g. a quick start guide). The provider's website has content more specific to JUST the provider itself with reference to learn more go to karpenter.sh. Things like developing the specific karpenter provider doesn't make sense to include in karpenter.sh but does in the local karpenter provider website.
You can see a sample deployment of the Azure site here: https://deploy-preview-1--karpenter-azure.netlify.app/

The trick is in the embed code - see this issue on docsy for more details or it being used in the PR.

Regardless, this is a lot of work and it would be great to have support from CNCF and Sig Docs.

[github-actions]

This issue has been inactive for 14 days. StaleBot will close this stale issue after 14 more days of inactivity.

[jonathan-innis]

This appeared to be mistakenly marked as stale. I think we need to update our StaleBot to deal with the new issue labels in kubernetes-sigs. I'll create an issue to track the update if someone wants to pick it up.

Edit: Linking the bot issue: #891

[sftim]

Kubernetes SIG Testing can help with the bot work.

[dtzar]

I created a karpenter content map google sheet we could use for the bigger content architecture plan.

If we want karpenter core to have docs specific to its version AND we want docs specific to the provider version, then this only reasonably makes sense to have both a core AND a provider website.

Once you're over this hurdle, now you can minimize the content duplication and maximize visibility for providers by the following methods:

1. Provider website either just links to core website OR embeds the relevant core website content
2. Core website embeds the core content (such as quick start) for each of the providers

Again, the embed mechanism I'm talking about is listed in the comment above.

I believe this pattern could be helpful for other folks such as CAPI.

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[Bryce-Soghigian]

/remove-lifecycle stale

[Bryce-Soghigian]

/lifecycle frozen

[chrisnegus]

I'm negotiating with the two cloud providers (AWS and Azure) that are currently working on Karpenter implementations for their Kubernetes products on how to move forward with a shared Karpenter docs site. I will have a proposal to share soon for others who are interested as well.

[dtzar]

@chrisnegus - unfortunately, the karpenter.sh website still appears to be 100% AWS-centric. Can we please move forward with any plan which allows Azure and other providers to have a presence?

[sftim]

@dtzar - help is welcome! Do you know any vendors willing to lend time to this effort?

[chrisnegus]

@dtzar Yes, that's on me. I do have a proposal for making the site less AWS-centric. I can get back to that next week and we can talk through ideas for how to do this.