Add generator kustomization references #5447

ncapps · 2023-11-14T23:05:39Z

Add generator references per #5352

Additional kustomization references will be updated in subsequent PRs.

k8s-ci-robot · 2023-11-14T23:05:41Z

This PR has multiple commits, and the default merge method is: merge.
You can request commits to be squashed using the label: tide/merge-method-squash

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.

k8s-ci-robot · 2023-11-14T23:05:41Z

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

ncapps · 2023-11-14T23:19:08Z

/label tide/merge-method-squash

annasong20

@ncapps, From a quick glance, I think this looks really good! Commented on some high-level suggestions. Discussion welcome!

annasong20 · 2023-11-14T23:29:15Z

site/content/en/docs/Reference/API/Kustomization File/configMapGenerator.md

@@ -6,3 +6,81 @@ weight: 6
 description: >
    Generate ConfigMap resources.
 ---
+
+## configMapGenerator


I think it'll save you time to document the configMapGenerator field with the built-in ConfigMapGenerator transformer: https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_configmapgenerator_. configMapGenerator uses the built-in ConfigMapGenerator under the hood and they have essentially the same sub-fields. It'll be much easier for the documentation of one to reference the other instead of repeating ourselves. The built-in transformers are a bit confusing. LMK if you need help understanding.

I added an API/Generators section. The ConfigMap and Secret generator types reference the common GeneratorArgs type. Please let me know if this is what you had in mind.

annasong20 · 2023-11-14T23:30:05Z

site/content/en/docs/Reference/API/Kustomization File/configMapGenerator.md

+
+---
+
+* **apiVersion**: kustomize.config.k8s.io/v1beta1


We probably want to move kind: Kustomization into its own Reference Kustomization file, just so we don't repeat ourselves or overwhelm the reader with multiple contexts. In that file, we can include all the supported fields and point them to the respective field Reference pages, like this one.

I like this idea! I added a new kustomization.md file.

annasong20 · 2023-11-14T23:30:58Z

site/content/en/docs/Reference/API/Kustomization File/configMapGenerator.md

+    List of ConfigMaps to generate.
+
+
+### ConfigMapArgs


I don't think ConfigMapArgs is exposed to the user. It is an implementation detail. We might not want to document it, unless it's re-used by secretGenerator (can't remember off the top of my head, I think it's re-used at least partially). We can potentially document the re-used fields on a separate page.

The ConfigMap and Secret generators use type.ConfigMapArgs and type.SecretArgs. These types share type.GeneratorArgs though they are different because the secret specifies a type.

Do you have a suggestion for another way to represent this? We could specify a GeneratorArgs in the common definitions?

I added GeneratorArgs to common definitions. Let me know if you are okay with this approach.

I see these files refer specifically to the kustomization file. configMapArgs, secretArgs, and generatorArgs are all fields that the end user is not expected to have in their kustomization.yaml. I feel there might be a confusion potential if these are described in this section, but it is useful to have them described in a separate API section for people onboarding to the project as contributors.

I am definitely open to suggestions for how best to describe the generator arguments. I was attempting to document that Secret and ConfigMap generators share many of the same arguments while avoiding listing the same fields in multiple places.

Using env in the PodSpec as an example, users are not expected to specify an EnvVar field. It is understood that EnvVar is a type used to define the fields to include in the env list.

If this is using Hugo, we can create a shortcode for including partial pages inside of other pages, similar to what docs.k8s.io currently does:

Sample shortcode: https://github.com/kubernetes/website/blob/022634424d27cb1b3aa5ca0b45999977f5be3c9b/layouts/shortcodes/include.html

Sample usage: https://github.com/kubernetes/website/blob/bc7cbf6e530acd3e4332cc257041e39a9f5e102c/content/en/docs/tasks/tools/install-kubectl-linux.md

Thank you for sharing this hugo feature. Though I am not sure this addresses how to document a list of generator arguments. For example, the configMapGenerator field is a list of the ConfigMapArgs type. I recognize that users don't specify configMapArgs anywhere in the Kustomization file, but I believe there should be a way to document what arguments are available for each ConfigMap object in the list.

Please disregard my previous comment. I used your suggestion to create a shortcode to include other markdown and I think the result is improved for the reader. Thank you again for the tip.

I just checked the rendered preview and it looks nice! 🎉

annasong20 · 2023-11-14T23:31:33Z

site/content/en/docs/Reference/API/Kustomization File/configMapGenerator.md

+
+    Options override global `generatorOptions` field.
+
+### GeneratorOptions


I think GeneratorOptions is re-used by secretGenerator , so it can be better referenced on its own page.

Great point. I updated the generatorOptions page and referenced it from the GeneratorArgs page.

annasong20 · 2023-11-14T23:33:41Z

site/content/en/docs/Reference/API/Kustomization File/configMapGenerator.md

+
+    Name of the generated ConfigMap. A hash suffix will be added to the Name by default.
+
+* **namespace** (string)


Probably good to point out optional fields. @koba1t suggested this: #5247 (comment)

I added an "optional" to the applicable fields. It looks like upstream Kubernetes docs typically notes which fields are required and omits the optional label. I don't feel strongly about either style so long as we are consistent.

annasong20 · 2023-12-04T16:30:55Z

/unassign
Sorry @ncapps @stormqueen1990 @natasha41575, I don't think I'll have time to give this PR prompt reviews. Please proceed without me.

natasha41575 · 2023-12-05T22:02:35Z

@stormqueen1990 let me know when you give this one an LGTM and I can take a quick look for a final approval!

stormqueen1990

This looks good to me as-is. I have some food for thought though that we might want to check whether it'd be possible to use https://github.com/kubernetes-sigs/reference-docs to generate these pages.

/lgtm

stormqueen1990 · 2023-12-11T03:53:30Z

site/content/en/docs/Reference/API/Generators/ConfigMapGenerator.md

+description: >
+  Generate ConfigMap objects.


I noticed this description is being rendered on both the parent page and in this page as well. I don't want to hold up this PR on that, but is it fair to create an issue to address it separately?

If we want to copy the behaviour from docs.k8s.io, this description would render solely on the parent page and never in the body of the page that defines it.

Thanks for catching this! I was curious about how this is configured. I created this issue to remove the description from the body of the page: #5488

stormqueen1990 · 2023-12-11T04:01:06Z

@natasha41575 LGTM'd!

ncapps · 2023-12-13T17:51:50Z

This is related to #5379

k8s-ci-robot · 2024-01-10T19:11:30Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: natasha41575, ncapps

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [natasha41575]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Nov 14, 2023

k8s-ci-robot requested review from natasha41575 and yuwenma November 14, 2023 23:05

k8s-ci-robot added the tide/merge-method-squash Denotes a PR that should be squashed by tide when it merges. label Nov 14, 2023

annasong20 reviewed Nov 14, 2023

View reviewed changes

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Nov 16, 2023

ncapps force-pushed the docs/ref/kustomization branch from 450ab5d to b5ab6a8 Compare November 17, 2023 00:32

ncapps marked this pull request as ready for review November 17, 2023 01:14

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Nov 17, 2023

k8s-ci-robot requested a review from koba1t November 17, 2023 01:14

ncapps requested a review from annasong20 November 17, 2023 01:14

ncapps force-pushed the docs/ref/kustomization branch from ef62596 to c11786b Compare November 22, 2023 17:06

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 26, 2023

ncapps added 11 commits November 26, 2023 08:34

Initial configMapGenerator ref

4953258

Draft configMapGenerator options

ef5989a

ConfigMapArgs

c63cc66

Add sources

9efe822

Begin to restructure generator spec

81f06f0

Add ObjectMeta

358a6c2

Draft kustomization.md

20187af

Draft kustomization file links

905a124

Move bases weight

de2c366

Update generatorArgs link to commmon generatorOptions

e7fe7b1

Remove api/generators for now

ca7fd81

ncapps added 12 commits November 26, 2023 08:34

Update generatorOptions

f2ec387

Add generatorArgs header

e1014d9

Add secretGenerator

62acfa1

Remove ObjectMeta for now

e614e95

Draft generators

c35cb31

Fix secretGenerator

1c38225

Cleanup

70d8060

Add include shortcode, cleanup generators

dcee02d

Use common includes

62460af

Update object metadata description

e06dcd0

spelling

62822dd

Improve args description

c3dfc06

ncapps force-pushed the docs/ref/kustomization branch from c11786b to c3dfc06 Compare November 26, 2023 16:35

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Nov 26, 2023

natasha41575 assigned stormqueen1990 and annasong20 Nov 29, 2023

k8s-ci-robot unassigned annasong20 Dec 4, 2023

stormqueen1990 reviewed Dec 11, 2023

View reviewed changes

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Dec 11, 2023

ncapps mentioned this pull request Dec 13, 2023

Document API Specs in Reference section #5379

Open

natasha41575 self-assigned this Jan 10, 2024

natasha41575 approved these changes Jan 10, 2024

View reviewed changes

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jan 10, 2024

k8s-ci-robot merged commit f3fedac into kubernetes-sigs:master Jan 10, 2024
9 checks passed

ncapps deleted the docs/ref/kustomization branch January 11, 2024 00:01

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add generator kustomization references #5447

Add generator kustomization references #5447

ncapps commented Nov 14, 2023

k8s-ci-robot commented Nov 14, 2023

k8s-ci-robot commented Nov 14, 2023

ncapps commented Nov 14, 2023

annasong20 left a comment •

edited

Loading

annasong20 Nov 14, 2023

ncapps Nov 17, 2023

annasong20 Nov 14, 2023

ncapps Nov 17, 2023

annasong20 Nov 14, 2023

ncapps Nov 16, 2023

ncapps Nov 17, 2023

stormqueen1990 Nov 17, 2023

ncapps Nov 17, 2023

stormqueen1990 Nov 17, 2023

ncapps Nov 17, 2023

ncapps Nov 17, 2023

stormqueen1990 Nov 18, 2023

annasong20 Nov 14, 2023

ncapps Nov 17, 2023

annasong20 Nov 14, 2023

ncapps Nov 17, 2023

annasong20 commented Dec 4, 2023

natasha41575 commented Dec 5, 2023

stormqueen1990 left a comment

stormqueen1990 Dec 11, 2023

ncapps Dec 13, 2023

stormqueen1990 commented Dec 11, 2023

ncapps commented Dec 13, 2023

k8s-ci-robot commented Jan 10, 2024


		Options override global `generatorOptions` field.

		### GeneratorOptions


		Name of the generated ConfigMap. A hash suffix will be added to the Name by default.

		* namespace (string)

Add generator kustomization references #5447

Add generator kustomization references #5447

Conversation

ncapps commented Nov 14, 2023

k8s-ci-robot commented Nov 14, 2023

k8s-ci-robot commented Nov 14, 2023

ncapps commented Nov 14, 2023

annasong20 left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

annasong20 commented Dec 4, 2023

natasha41575 commented Dec 5, 2023

stormqueen1990 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stormqueen1990 commented Dec 11, 2023

ncapps commented Dec 13, 2023

k8s-ci-robot commented Jan 10, 2024

annasong20 left a comment •

edited

Loading