Consolidate kustomize documentation

[natasha41575]

Now that the domain kustomize.io has been transferred to us, we should figure out what we want to do with all of our fragmented documentation.

There's the outdated kustomize.io, the small and very hard to find kustomize section on kubernetes.io, our core docs on kubernetes-sigs.github.io/kustomize, and the examples in this repo. We should consolidate these docs into a single, easy to find place.

It would be nice to have everything cleanly on kustomize.io, with links or redirects to it from the other websites. We like having the examples in this repo as tests, and I imagine it would be possible to have all the doc contents and examples and tests in this repo - perhaps under a site directory - and point that to kustomize.io. Though we now have the domain, the source code for kustomize.io currently lives in a repository owned by Replicated. If we wish to change or contribute to that code, we should move it over to a repository owned by CNCF.

It would also be helpful to have documentation for kustomize commands (see #3464)

This would be a decently sized project, and it is likely we would need a dedicated person that can spend time on this.

/kind documentation
/triage accepted

cc @KnVerey @yuwenma @mikebz

Contribution process

To help us see the work to be done and coordinate more easily, we've put together a spreadsheet. Everyone on the SIG CLI mailing list should be able to edit it. If you're interested in contributing to this effort, please:

1. Consult the spreadsheet to find content that hasn't been moved yet. Give priority to content from the old site (as opposed to the section at the bottom with other repos) since getting that moved is the MVP for launching the new site.
2. Assign yourself to the specific page(s) you're tackling by writing your name in the "Assignee" column.
3. Move the content into the appropriate place in Kustomize's site/content/en directory.
4. Review the content, keeping any comments from the spreadsheet in mind. In particular, please make sure that all links are live and that kustomize build can successfully be run with the latest version of Kustomize on any examples given (if it doesn't and the fix isn't obvious, just flag it on the PR). Other improvements jump out at you? Feel free to make those too!
5. When your PR is ready, tag maintainers as usual, but please also link it in the spreadsheet. Please confirm in your PR description that you have validated the links and examples. We'll take your word for it, which will speed up the review process.
6. When your PR merges, check the "merged" box in the spreadsheet so we can track progress.

[mikebz]

Huge fan of this initiative. We do owe it to our users to create something coherent instead of sending them all around with bits and pieces of information.

A good example is the information architecture of https://kpt.dev
Overview, Guide/Book, CLI and data reference, FAQ.

[thepaulmacca]

This would be a welcome update. I'm quite new to kustomize, and having a tough time finding a good list of CLI commands. Currently doing a lot manually and finding it a pain

[MyIgel]

Hi, did you had any time to investigate the "Try It" function? Is it by itself versioned somewhere/is there a repo where i can find it? It was a pretty useful tool and being able to at least run it on my machine would be great!

[natasha41575]

Hi, did you had any time to investigate the "Try It" function? Is it by itself versioned somewhere/is there a repo where i can find it? It was a pretty useful tool and being able to at least run it on my machine would be great!

The "Try It" function was not created by us nor is it in a repo owned by us. Like the rest of the functionality that is/was on kustomize.io, it currently lives in a repo owned by replicated: https://github.com/replicatedcom/kustomize-www, I believe you will be able to find it there.

[MyIgel]

Sadly it isn't (at least i could not find it in that repo / only the commit that adds a link to it) so i would think its a different application -> is it possible to ask them if they have it laying around somewhere and want to publish it too?

[natasha41575]

I imagine you could open an issue in the repo I linked to request something like that.

[MyIgel]

The tutorial page is now available at https://github.com/replicatedhq/kustomize-demo 🎉

Is there a way to support you with its integration?

[natasha41575]

We would love to have someone help to revamp the documentation, eventually resolving this issue, because we are very limited on resources. As stated in the issue, this will be a big task that may take some dedicated time and effort. It would involve consolidating all of the information we have across the various domains and moving docs code into this repo. Would you (or anyone else who is reading this) be interested in working on it? If so, please reach out on slack, and we can chat with @KnVerey about the best way for contributors to help.

If you are interested in fixing just the tutorial page, feel free to make a PR to wherever appropriate. I'm not familiar with the docs architecture but if you have an idea for how to fix it, we can take a look at your PRs and try to get approval from the right people.

[MyIgel]

The demo page also needs an API which now can be found at https://github.com/replicatedhq/kustomize-demo-api

[MyIgel]

I'm not the best docs writer by myself so I could just help with for example some deployment files (as i have already a successful tutorial app setup on a k8s cluster). For that I think it would be best to first move both repos to the kubernetes-sigs group and then decide how to deploy it to google cloud where kustomize.io seems to be hosted. Whats the current env there?

[KnVerey]

I don't know how kustomize.io is currently hosted by Replicated, but we'll need to do whatever the community infra supports, which is unrelated. For the static content, the standard stack is Hugo+Netlify. I don't know if we host anything like that tutorial. I'd suggest talking to SIG k8s infra and/or SIG Docs about the options as a first step.

That said, we really need someone with the bandwidth to tackle the docs project holistically, part of which is deciding what exactly to do with the content from the Replicated sites. Since moving the content over is not straightforward or quick, I'd say the pragmatic thing to do re: the demo for now is to fix it in the existing Replicated repos at let it continue to ship the way it always has, for now.

[k8s-triage-robot]

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

This bot triages issues and PRs 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 or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

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

/lifecycle stale

[KnVerey]

/remove-lifecycle stale

To help us see the work to be done and coordinate more easily, I've put together a spreadsheet. Everyone on the SIG CLI mailing list should be able to edit it. If you're interested in contributing to this effort, please:

1. Consult the spreadsheet to find content that hasn't been moved yet. Give priority to content from the old site (as opposed to the section at the bottom with other repos) since getting that moved is the MVP for launching the new site.
2. Assign yourself to the specific page(s) you're tackling by writing your name in the "Assignee" column.
3. Move the content into the appropriate place in Kustomize's site/content/en directory.
4. Review the content, keeping any comments from the spreadsheet in mind. In particular, please make sure that all links are live and that kustomize build can successfully be run with the latest version of Kustomize on any examples given (if it doesn't and the fix isn't obvious, just flag it on the PR). Other improvements jump out at you? Feel free to make those too!
5. When your PR is ready, tag maintainers as usual, but please also link it in the spreadsheet. Please confirm in your PR description that you have validated the links and examples. We'll take your word for it, which will speed up the review process.
6. When your PR merges, check the "merged" box in the spreadsheet so we can track progress.

I've left suggestions as to where the content should move as well as some thoughts on any adaptations that seem necessary. This is based on a quick look + reference to David's notes. If you have a different idea once you start working with the content, go for it! Also feel free to ask clarifying questions using the comments feature in the spreadsheet.

[aabouzaid]

Hi 👋

I've created an Awesome Kustomize list.
Right now the list has 6 plugins, 10 guides (novice, intermediate, and advanced), and a couple of tips and tricks.

Maybe it's a good idea to include it on the Kustomize website.
However, I'm not sure where to put that suggestion 🤔

[k8s-triage-robot]

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

• Confirm that this issue is still relevant with /triage accepted (org members only)
• Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted

[koba1t]

/triage accepted

[ashnehete]

I'm willing to take up ownership of this entire task. Would appreciate any insights into the ongoing work and current planning for this task.

/assign

[mikebz]

That is great news! I think kustomize is due for a big overhaul. The docs might be 4+ years old