From 22a56596c28aaaa2ce802fb005610929097bfcb7 Mon Sep 17 00:00:00 2001 From: Aashish Nehete Date: Sat, 28 Sep 2024 23:54:07 -0500 Subject: [PATCH 1/7] Add FAQ from kubectl.docs.kubernetes.io --- .../contribute/features/eschewedfeatures.md | 161 +++++++++++ .../en/docs/Reference/versioningPolicy.md | 272 ++++++++++++++++++ site/content/en/faq/_index.md | 83 +++++- site/content/en/faq/eschewedfeatures.md | 12 - site/content/en/faq/versioningPolicy.md | 9 - 5 files changed, 513 insertions(+), 24 deletions(-) create mode 100644 site/content/en/contribute/features/eschewedfeatures.md create mode 100644 site/content/en/docs/Reference/versioningPolicy.md delete mode 100644 site/content/en/faq/eschewedfeatures.md delete mode 100644 site/content/en/faq/versioningPolicy.md diff --git a/site/content/en/contribute/features/eschewedfeatures.md b/site/content/en/contribute/features/eschewedfeatures.md new file mode 100644 index 0000000000..90a365f510 --- /dev/null +++ b/site/content/en/contribute/features/eschewedfeatures.md @@ -0,0 +1,161 @@ +--- +title: "Eschewed Features" +linkTitle: "Eschewed Features" +type: docs +weight: 99 +description: > + List of non-goal features +--- + +The maintainers established this list to +place bounds on the kustomize feature +set. The bounds can be changed with +a consensus on the risks. + +For a bigger picture about why kustomize +does some things and not others, see the +glossary entry for [DAM]. + +## Removal directives + +`kustomize` supports configurations that can be reasoned about as +_compositions_ or _mixins_ - concepts that are widely accepted as +a best practice in various programming languages. + +To this end, `kustomize` offers various _addition_ directives. +One may add labels, annotations, patches, resources, bases, etc. +Corresponding _removal_ directives are not offered. + +Removal semantics would introduce many possibilities for +inconsistency, and the need to add code to detect, report and +reject it. It would also allow, and possibly encourage, +unnecessarily complex configuration layouts. + +When faced with a situation where removal is desirable, it's +always possible to remove things from a base like labels and +annotations, and/or split multi-resource manifests into individual +resource files - then add things back as desired via the +[kustomization]. + +If the underlying base is outside of one's control, an [OTS +workflow] is the recommended best practice. Fork the base, remove +what you don't want and commit it to your private fork, then use +kustomize on your fork. As often as desired, use _git rebase_ to +capture improvements from the upstream base. + +## Unstructured edits + +_Structured edits_ are changes controlled by +knowledge of the k8s API, and YAML or JSON syntax. + +Most edits performed by kustomize can be expressed as +[JSON patches] or [SMP patches]. +Those can be verbose, so common patches, +like adding labels or annotatations, get dedicated +transformer plugins - `LabelTransformer`, +`AnnotationsTransformer`, etc. +These accept relatively simple YAML configuration +allowing easy targeting of any number of resources. + +Another class of edits take data from one specific +object's field and use it in another (e.g. a service +object's name found and copied into a container's +command line). These reflection-style edits +are called _replacements_. + +The above edits create valid output given valid input, +and can provide syntactically and semantically +informed error messages if inputs are invalid. + +_Unstructured edits_, edits that don't limit +themselves to a syntax or object structure, +come in many forms. A common one in the +configuration domain is the template or +parameterization approach. + +In this technique, the source +material is sprinkled with strings of the +form `${VAR}`. A scanner replaces them +with a value taken from a map using `VAR` +as the map key. It's trivial to implement. + +kustomize eschews parameterization, because + +- The source yaml gets polluted with `$VARs` + and can no longed be applied as is + to the cluster (it _must_ be processed). +- The source material is no longer structured, + making it unusable with any YAML processor. + It's no longer _data_, it's now logic that + must be compiled. +- Errors in the output are disconnected from + the edit that caused it. +- The input becomes [unintelligible] as the project + scales in any number of dimensions (resource + count, cluster count, environment count, etc.) + +Kustomizations are meant to be sharable and stackable. +Imagine tracing down a problem rooted in a +clever set of stacked regexp replacements +performed by various overlays on some remote base. +We've used such systems, and never want to again. + +Other tools (sed, jinja, erb, envsubst, kafka, helm, ksonnet, +etc.) provide varying degrees of unstructured editting +and/or embedded languages, and can be used instead +of, or in a pipe with, kustomize. If you want to +go all-in on _configuration as a language_, consider [cue]. + +kustomize is going to stick to YAML in / YAML out. + +## Build-time side effects from CLI args or env variables + +`kustomize` supports the best practice of storing one's +entire configuration in a version control system. + +Changing `kustomize build` configuration output as a result +of additional arguments or flags to `build`, or by +consulting shell environment variable values in `build` +code, would frustrate that goal. + +`kustomize` insteads offers [kustomization] file `edit` +commands. Like any shell command, they can accept +environment variable arguments. + +For example, to set the tag used on an image to match an +environment variable, run + +``` +kustomize edit set image nginx:$MY_NGINX_VERSION +``` + +as part of some encapsulating work flow executed before +`kustomize build`. + +## Globs in kustomization files + +`kustomize` supports the best practice of storing one's +entire configuration in a version control system. + +Globbing the local file system for files not explicitly +declared in the [kustomization] file at `kustomize build` time +would violate that goal. + +Allowing globbing in a kustomization file would also introduce +the same problems as allowing globbing in [java import] +declarations or BUILD/Makefile dependency rules. + +`kustomize` will instead provide kustomization file editting +commands that accept globbed arguments, expand them at _edit +time_ relative to the local file system, and store the resulting +explicit names into the kustomization file. + +[DAM]: /docs/references/glossary/#declarative-application-management +[java import]: https://www.codebyamir.com/blog/pitfalls-java-import-wildcards +[JSON patches]: /docs/references/glossary/#patchjson6902 +[kustomization]: /docs/references/glossary/#kustomization +[OTS workflow]: /docs/references/glossary/#off-the-shelf-configuration +[SMP patches]: /docs/references/glossary/#patchstrategicmerge +[parameterization pitfall discussion]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/declarative-application-management.md#parameterization-pitfalls +[unintelligible]: https://github.com/helm/charts/blob/e002378c13e91bef4a3b0ba718c191ec791ce3f9/stable/artifactory/templates/artifactory-deployment.yaml +[cue]: https://cuelang.org/ diff --git a/site/content/en/docs/Reference/versioningPolicy.md b/site/content/en/docs/Reference/versioningPolicy.md new file mode 100644 index 0000000000..3703393994 --- /dev/null +++ b/site/content/en/docs/Reference/versioningPolicy.md @@ -0,0 +1,272 @@ +--- +title: "Versioning Policy" +linkTitle: "Versioning Policy" +weight: 99 +type: docs +description: > + CLI and API Versioning +--- + +Running `kustomize` means one is running a +particular version of a program (a CLI), using a +particular version of underlying packages (a Go +API), and reading a particular version of a +[kustomization] file. + +> If you're having trouble with `go get`, please +> read [Go API Versioning](#go-api-versioning) +> and be patient. + +## CLI Program Versioning + +The command `kustomize version` prints a three +field version tag (e.g. `v3.0.0`) that aspires to +[semantic versioning]. + +This notion of semver applies only to the CLI; +the command names, their arguments and their flags. + +The major version changes when some backward +incompatibility appears in how the commands +behave. + +### Installation + +See the [installation docs]. + +## Go API Versioning + +The public methods in the public packages +of module `sigs.k8s.io/kustomize/api` constitute +the _kustomize Go API_. + +#### Version sigs.k8s.io/kustomize/v3 and earlier + +[import path]: https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher + +In `kustomize/v3` (and preceding major versions), the +kustomize program and the API live the same Go +module at `sigs.k8s.io/kustomize`, at [import path] +`sigs.k8s.io/kustomize/v3`. + +This has been fine for the CLI, but it presents a +problem for the Go API. + +[minimal version selection]: https://research.swtch.com/vgo-mvs + +The process around Go modules, in particular the +notion of [minimal version selection], demands +that the module respect semver. + +Almost all the code in module +`sigs.k8s.io/kustomize/v3` is exposed (not in a +directory named `internal`). Even a minor +refactor changing a method name or argument type +in some deeply buried (but still public) method is +a backward incompatible change. As a result, Go +API semver hasn't been followed. This was a mistake. + +Some options are + +- continue to ignore Go API semver and stick to + CLI semver (eliminating the usefullness of + minimal version selection), + +- obey semver, and increment the module's major + version number with every release (drastically + reducing the usefullness of minimal version + selection - since virtually all releases will + be major), + +- slow down change in the huge API in favor of + stability, yet somehow continue to deliver + features, + +- drastically reduce the API surface, stabilize on + semver there, and refactor as needed inside + `internal`. + +The last option seems the most appealing. + +#### The first stable API version is coming + +The first stable API version will launch +as the Go module + +``` +sigs.k8s.io/kustomize/api +``` + +The _kustomize_ program itself (`main.go` +and CLI specific code) will have moved out of +`sigs.k8s.io/kustomize` and into the new module +`sigs.k8s.io/kustomize/kustomize`. This is a +submodule in the same repo, and it will retain its +current notion of semver (e.g. a backward +incompatible change in command behavior will +trigger a major version bump). This module will +not export packages; it's just home to a `main` +package. + +The `sigs.k8s.io/kustomize/api` module will +obey semver with a sustainable public +surface, informed by current usage. Clients +should import packages from this module, i.e. +from import paths prefixed by +`sigs.k8s.io/kustomize/api/` at first, +and later by `sigs.k8s.io/kustomize/api/v2/`. +The kustomize binary +itself is an API client requiring this module. + +The clients and API will evolve independently. + +## Kustomization File Versioning + +The kustomization file is a struct that is part of +the kustomize Go API (the `sigs.k8s.io/kustomize` +module), but it also evolves as a k8s API object - +it has an `apiVersion` field containing its +own version number. + +### Field Change Policy + +- A field's meaning cannot be changed. +- A field may be deprecated, then removed. +- Deprecation means triggering a _minor_ (semver) + version bump in the kustomize Go API, and + defining a migration path in a non-fatal error + message. +- Removal means triggering a _major_ (semver) + version bump in the kustomize Go API, and fatal + error if field encountered (as with any unknown + field). Likewise a change in `apiVersion`. + +### The `edit fix` Command + +This `kustomize` command reads a Kustomization +file, converts deprecated fields to new +fields, and writes it out again in the latest +format. + +This is a type version upgrade mechanism that +works within _major_ API revisions. There is no +downgrade capability, as there's no use case for +it (see discussion below). + +### Examples + +With the 2.0.0 release, there were three field +removals: + +- `imageTag` was deprecated when `images` was + introduced, because the latter offers more + general features for image data manipulation. + `imageTag` was removed in v2.0.0. +- `patches` was deprecated and replaced by + `patchesStrategicMerge` when `patchesJson6902` + was introduced, to make a clearer + distinction between patch specification formats. + `patches` was removed in v2.0.0. +- `secretGenerator/commands` was removed + due to security concerns in v2.0.0 + with no deprecation period. + +The `edit fix` command in a v2.0.x binary +will no longer recognize these fields. + +## Relationship to the k8s API + +### Review of k8s API versioning + +The k8s API has specific [conventions] and a +process for making [changes]. + +The presence of an `apiVersion` field in a k8s +native type signals: + +- its reliability level (alpha vs beta vs + generally available), +- the existence of code to provide default values + to fields not present in a serialization, +- the existence of code to provide both forward + and backward conversion between different + versions of types. + +The k8s API promises a lossless _conversion_ +between versions over a specific range. This +means that a recent client can write an object +bearing the newest possible value for its version, +the server will accept it and store it in +"versionless" JSON form in storage, and can +convert it to a range of older versions should +an older client request data. + +For native k8s types, this all requires writing Go +code in the kubernetes core repo, to provide +defaulting and conversions. + +For CRDs, there's a [proposal] on how to manage +versioning (e.g. a remote service can offer type +defaulting and conversions). + +### Differences + +- A k8s API server is able to go _forward_ and + _backward_ in versioning, to work with older + clients, over [some range]. +- The `kustomize edit fix` command only moves + _forward_ within a _major_ API + version. + +At the time of writing, the YAML in a +kustomization file does not represent a [k8s API] +object, and the kustomize command and associated +library is neither a server of, nor a client to, +the k8s API. + +### Additional Kustomization file rules + +In addition to the [field change policy] described +above, kustomization files conform to +the following rules. + +#### Eschew classic k8s fields + +Field names with dedicated meaning in k8s +(`metadata`, `spec`, `status`, etc.) aren't used. +This is enforced via code review. + +#### Default values for k8s `kind` and `apiVersion` + +In `v3` or below, the two [special] k8s +resource fields [`kind`] and [`apiVersion`] may +be omitted from the kustomization file. + +If either field is present, they both must be. +If present, the value of `kind` must be: + +> ``` +> kind: Kustomization +> ``` + +If missing, the value of `apiVersion` defaults to + +> ``` +> apiVersion: kustomize.config.k8s.io/v1beta1 +> ``` + +[field change policy]: #field-change-policy +[some range]: https://kubernetes.io/docs/reference/using-api/deprecation-policy +[proposal]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/customresources-versioning.md +[beta-level rules]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md#alpha-beta-and-stable-versions +[changes]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md +[special]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#resources +[k8s API]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md +[conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md +[release page]: https://github.com/kubernetes-sigs/kustomize/releases +[release process]: https://github.com/kubernetes-sigs/kustomize/tree/master/releasing/README.md +[kustomization]: /references/kustomize/glossary#kustomization +[`kind`]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds +[`apiVersion`]: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning +[semantic versioning]: https://semver.org +[installation docs]: /docs/getting-started/installation/ diff --git a/site/content/en/faq/_index.md b/site/content/en/faq/_index.md index 7ca1a4510b..ef83948fed 100644 --- a/site/content/en/faq/_index.md +++ b/site/content/en/faq/_index.md @@ -2,11 +2,88 @@ title: "FAQ" linkTitle: "FAQ" type: docs +description: + "Frequently asked questions on Kustomize" menu: main: weight: 70 --- - +## kubectl doesn't have the latest kustomize, when will it be updated? + +TLDR: This is blocked on either moving kubectl into its own repo, or changing its dependencies. ETA k8s ~1.20. + +The adoption of go modules in the kubernetes/kubernetes repo broke the update process for kustomize. +This is due to the kustomize libraries depending on the kubernetes apimachinery libraries, which are +published out of the kubernetes staging directory. + +2 pieces of work are underway which will allow kustomize to be updated in kubectl: + +- migrating kubectl out of kubernetes/kubernetes (expected Kubernetes ~1.20) +- migrating kustomize off of the apimachinery libraries (expected Kubernetes ~1.20) + - [2506](https://github.com/kubernetes-sigs/kustomize/issues/2506) + +Once either of these issues is resolved we will then update kubectl with the latest kustomize version. + +## security: file 'foo' is not in or below 'bar' + +v2.0 added a security check that prevents +kustomizations from reading files outside their own +directory root. + +This was meant to help protect the person inclined to +download kustomization directories from the web and use +them without inspection to control their production +cluster +(see [#693](https://github.com/kubernetes-sigs/kustomize/issues/693), +[#700](https://github.com/kubernetes-sigs/kustomize/pull/700), +[#995](https://github.com/kubernetes-sigs/kustomize/pull/995) and +[#998](https://github.com/kubernetes-sigs/kustomize/pull/998)) + +Resources (including configmap and secret generators) +can _still be shared_ via the recommended best practice +of placing them in a directory with their own +kustomization file, and referring to this directory as a +[`base`](/docs/reference/glossary/#base) from any kustomization that +wants to use it. This encourages modularity and +relocatability. + +To disable this in v3, use the `load_restrictor` flag: + +```bash +kustomize build --load_restrictor none $target +``` + +To disable this in v4+, use the `load-restrictor` flag: + +```bash +kustomize build --load-restrictor LoadRestrictionsNone $target +``` + +## Some field is not transformed by kustomize + +Example: [#1319](https://github.com/kubernetes-sigs/kustomize/issues/1319), [#1322](https://github.com/kubernetes-sigs/kustomize/issues/1322), [#1347](https://github.com/kubernetes-sigs/kustomize/issues/1347) and etc. + +The fields transformed by kustomize is configured explicitly in [defaultconfig](https://github.com/kubernetes-sigs/kustomize/tree/master/api/konfig/builtinpluginconsts/defaultconfig.go). The configuration itself can be customized by including `configurations` in `kustomization.yaml`, e.g. + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +configurations: +- kustomizeconfig.yaml +``` + +The configuration directive allows customization of the following transformers: + +```yaml +commonAnnotations: [] +commonLabels: [] +nameprefix: [] +namespace: [] +varreference: [] +namereference: [] +images: [] +replicas: [] +``` + +To persist the changes to default configuration, submit a PR like [#1338](https://github.com/kubernetes-sigs/kustomize/pull/1338), [#1348](https://github.com/kubernetes-sigs/kustomize/pull/1348) and etc. diff --git a/site/content/en/faq/eschewedfeatures.md b/site/content/en/faq/eschewedfeatures.md deleted file mode 100644 index a68e3f6295..0000000000 --- a/site/content/en/faq/eschewedfeatures.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Eschewed Features" -linkTitle: "Eschewed Features" -type: docs -weight: 99 -description: > - Eschewed Features ---- - - diff --git a/site/content/en/faq/versioningPolicy.md b/site/content/en/faq/versioningPolicy.md deleted file mode 100644 index bd206928fe..0000000000 --- a/site/content/en/faq/versioningPolicy.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "Versioning Policy" -linkTitle: "Versioning Policy" -weight: 99 -type: docs ---- - From 7f6d9de767c6a80b5ab195b716aa5a953f80b597 Mon Sep 17 00:00:00 2001 From: Aashish Nehete Date: Sun, 29 Sep 2024 10:34:25 -0500 Subject: [PATCH 2/7] Add title to Contributing Features --- site/content/en/contribute/features/_index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/site/content/en/contribute/features/_index.md b/site/content/en/contribute/features/_index.md index d5ebf3e613..59fcf1ef88 100644 --- a/site/content/en/contribute/features/_index.md +++ b/site/content/en/contribute/features/_index.md @@ -7,4 +7,6 @@ description: > How to contribute features --- +### Kustomize Enhancement Proposal + For feature proposals, please refer to [Kustomize Enhancement Proposal Processes](https://github.com/kubernetes-sigs/kustomize/tree/master/proposals) documentation From ea8125cd046e2504d890e62fd2a92ddcf42d1aad Mon Sep 17 00:00:00 2001 From: Aashish Nehete Date: Sun, 29 Sep 2024 10:36:59 -0500 Subject: [PATCH 3/7] Set sidebar_menu_compact to true --- site/hugo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/hugo.toml b/site/hugo.toml index 0097b6debe..d11240aa85 100644 --- a/site/hugo.toml +++ b/site/hugo.toml @@ -159,7 +159,7 @@ navbar_logo = false # Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage. navbar_translucent_over_cover_disable = false # Enable to show the side bar menu in its compact state. -sidebar_menu_compact = false +sidebar_menu_compact = true # Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled) sidebar_search_disable = false From 6861d648454e1486e501edb65b8a126e746aa09a Mon Sep 17 00:00:00 2001 From: Aashish Nehete Date: Sun, 29 Sep 2024 18:06:51 -0500 Subject: [PATCH 4/7] Add glossary, fix broken links --- .../contribute/features/eschewedfeatures.md | 12 +- site/content/en/docs/Reference/glossary.md | 472 +++++++++++++++++- .../en/docs/Reference/versioningPolicy.md | 8 +- 3 files changed, 480 insertions(+), 12 deletions(-) diff --git a/site/content/en/contribute/features/eschewedfeatures.md b/site/content/en/contribute/features/eschewedfeatures.md index 90a365f510..4b8c10a5ba 100644 --- a/site/content/en/contribute/features/eschewedfeatures.md +++ b/site/content/en/contribute/features/eschewedfeatures.md @@ -150,12 +150,12 @@ commands that accept globbed arguments, expand them at _edit time_ relative to the local file system, and store the resulting explicit names into the kustomization file. -[DAM]: /docs/references/glossary/#declarative-application-management +[DAM]: /docs/reference/glossary/#declarative-application-management [java import]: https://www.codebyamir.com/blog/pitfalls-java-import-wildcards -[JSON patches]: /docs/references/glossary/#patchjson6902 -[kustomization]: /docs/references/glossary/#kustomization -[OTS workflow]: /docs/references/glossary/#off-the-shelf-configuration -[SMP patches]: /docs/references/glossary/#patchstrategicmerge -[parameterization pitfall discussion]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/declarative-application-management.md#parameterization-pitfalls +[JSON patches]: /docs/reference/glossary/#patchjson6902 +[kustomization]: /docs/reference/glossary/#kustomization +[OTS workflow]: /docs/reference/glossary/#off-the-shelf-configuration +[SMP patches]: /docs/reference/glossary/#patchstrategicmerge +[parameterization pitfall discussion]: https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/declarative-application-management.md#parameterization-pitfalls [unintelligible]: https://github.com/helm/charts/blob/e002378c13e91bef4a3b0ba718c191ec791ce3f9/stable/artifactory/templates/artifactory-deployment.yaml [cue]: https://cuelang.org/ diff --git a/site/content/en/docs/Reference/glossary.md b/site/content/en/docs/Reference/glossary.md index 92c883c4ae..6b78839f7e 100644 --- a/site/content/en/docs/Reference/glossary.md +++ b/site/content/en/docs/Reference/glossary.md @@ -3,6 +3,474 @@ title: "Glossary" linkTitle: "Glossary" weight: 1 date: 2023-07-28 +type: docs description: > - Glossary defines terminology used to interact with Kustomize. ---- \ No newline at end of file + Terminology used to interact with Kustomize. +--- + +[CRD spec]: https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/ +[CRD]: #custom-resource-definition +[DAM]: #declarative-application-management +[Declarative Application Management]: https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/declarative-application-management.md +[JSON]: https://www.json.org/ +[JSONPatch]: https://tools.ietf.org/html/rfc6902 +[JSONMergePatch]: https://tools.ietf.org/html/rfc7386 +[Resource]: #resource +[YAML]: https://www.yaml.org/ +[application]: #application +[apply]: #apply +[apt]: https://en.wikipedia.org/wiki/APT_(Debian) +[base]: #base +[bases]: #base +[bespoke]: #bespoke-configuration +[gitops]: #gitops +[k8s]: #kubernetes +[kubernetes]: #kubernetes +[kustomize]: #kustomize +[kustomization]: #kustomization +[kustomizations]: #kustomization +[off-the-shelf]: #off-the-shelf-configuration +[overlay]: #overlay +[overlays]: #overlay +[patch]: #patch +[patches]: #patch +[patchJson6902]: #patchjson6902 +[patchExampleJson6902]: https://github.com/kubernetes-sigs/kustomize/tree/master/examples/jsonpatch.md +[patchesJson6902]: #patchjson6902 +[proposal]: https://github.com/kubernetes/community/pull/1629 +[rebase]: https://git-scm.com/docs/git-rebase +[resource]: #resource +[resources]: #resource +[root]: #kustomization-root +[rpm]: https://en.wikipedia.org/wiki/Rpm_(software) +[strategic-merge]: https://git.k8s.io/community/contributors/devel/sig-api-machinery/strategic-merge-patch.md +[target]: #target +[transformer]: #transformer +[variant]: #variant +[variants]: #variant + +## application + +An _application_ is a group of k8s resources related by +some common purpose, e.g. a load balancer in front of a +webserver backed by a database. +[Resource] labelling, naming and metadata schemes have +historically served to group resources together for +collective operations like _list_ and _remove_. + +This [proposal] describes a new k8s resource called +_application_ to more formally describe this idea and +provide support for application-level operations and +dashboards. + +[kustomize] configures k8s resources, and the proposed +application resource is just another resource. + +## apply + +The verb _apply_ in the context of k8s refers to a +kubectl command and an in-progress [API +endpoint](https://goo.gl/UbCRuf) for mutating a +cluster. + +One _applies_ a statement of what one wants to a +cluster in the form of a complete resource list. + +The cluster merges this with the previously applied +state and the actual state to arrive at a new desired +state, which the cluster's reconciliation loop attempts +to create. This is the foundation of level-based state +management in k8s. + +## base + +A _base_ is a [kustomization] referred to +by some other [kustomization]. + +Any kustomization, including an [overlay], can be a base to +another kustomization. + +A base has no knowledge of the overlays that refer to it. + +For simple [gitops] management, a base configuration +could be the _sole content of a git repository +dedicated to that purpose_. Same with [overlays]. +Changes in a repo could generate a build, test and +deploy cycle. + +## bespoke configuration + +A _bespoke_ configuration is a [kustomization] and some +[resources] created and maintained internally by some +organization for their own purposes. + +The workflow associated with a _bespoke_ config is +simpler than the workflow associated with an +[off-the-shelf] config, because there's no notion of +periodically capturing someone else's upgrades to the +[off-the-shelf] config. + +## custom resource definition + +One can extend the k8s API by making a +Custom Resource Definition ([CRD spec]). + +This defines a custom [resource] (CD), an entirely +new resource that can be used alongside _native_ +resources like ConfigMaps, Deployments, etc. + +Kustomize can customize a CD, but to do so +kustomize must also be given the corresponding CRD +so that it can interpret the structure correctly. + +## declarative application management + +Kustomize aspires to support [Declarative Application Management], +a set of best practices around managing k8s clusters. + +In brief, kustomize should + +* Work with any configuration, be it bespoke, + off-the-shelf, stateless, stateful, etc. +* Support common customizations, and creation of + [variants] (e.g. _development_ vs. + _staging_ vs. _production_). +* Expose and teach native k8s APIs, rather than + hide them. +* Add no friction to version control integration to + support reviews and audit trails. +* Compose with other tools in a unix sense. +* Eschew crossing the line into templating, domain + specific languages, etc., frustrating the other + goals. + +## generator + +A generator makes resources that can be used as is, +or fed into a [transformer]. + +## gitops + +Devops or CICD workflows that use a git repository as a +single source of truth and take action (e.g., build, +test or deploy) when that truth changes. + +## kustomization + +The term _kustomization_ refers to a +`kustomization.yaml` file, or more generally to a +directory (the [root]) containing the +`kustomization.yaml` file and all the relative file +paths that it immediately references (all the local +data that doesn't require a URL specification). + +I.e. if someone gives you a _kustomization_ for use +with [kustomize], it could be in the form of + +* one file called `kustomization.yaml`, +* a tarball (containing that YAML file plus what it references), +* a git archive (ditto), +* a URL to a git repo (ditto), etc. + +A kustomization file contains fields +falling into four categories: + +* _resources_ - what existing [resources] are to be customized. + Example fields: _resources_, _crds_. + +* _generators_ - what _new_ resources should be created. + Example fields: _configMapGenerator_ (legacy), + _secretGenerator_ (legacy), _generators_ (v2.1). + +* _transformers_ - what to _do_ to the aforementioned resources. + Example fields: _namePrefix_, _nameSuffix_, _images_, + _commonLabels_, _patchesJson6902_, etc. and the more + general _transformers_ (v2.1) field. + +* _meta_ - fields which may influence all or some of + the above. Example fields: _vars_, _namespace_, + _apiVersion_, _kind_, etc. + +## kustomization root + +The directory that immediately contains a +`kustomization.yaml` file. + +When a kustomization file is processed, it may or may +not be able to access files outside its root. + +Data files like resource YAML files, or text files +containing _name=value_ pairs intended for a ConfigMap +or Secret, or files representing a patch to be used in +a patch transformation, must live _within or below_ the +root, and as such are specified via _relative +paths_ exclusively. + +A special flag (in v2.1), `--load_restrictions none`, +is provided to relax this security feature, to, say, +allow a patch file to be shared by more than one +kustomization. + +Other kustomizations (other directories containing a +`kustomization.yaml` file) may be referred to by URL, by +absolute path, or by relative path. + +If kustomization __A__ depends on kustomization __B__, then + +* __B__ may not _contain_ __A__. +* __B__ may not _depend on_ __A__, even transitively. + +__A__ may contain __B__, but in this case it might be +simplest to have __A__ directly depend on __B__'s +resources and eliminate __B__'s kustomization.yaml file +(i.e. absorb __B__ into __A__). + +Conventionally, __B__ is in a directory that's sibling +to __A__, or __B__ is off in a completely independent +git repository, referencable from any kustomization. + +A common layout is + +> ``` +> ├── base +> │   ├── deployment.yaml +> │   ├── kustomization.yaml +> │   └── service.yaml +> └── overlays +> ├── dev +> │   ├── kustomization.yaml +> │   └── patch.yaml +> ├── prod +> │   ├── kustomization.yaml +> │   └── patch.yaml +> └── staging +> ├── kustomization.yaml +> └── patch.yaml +> ``` + +The three roots `dev`, `prod` and `staging` +(presumably) all refer to the `base` root. One would +have to inspect the `kustomization.yaml` files to be +sure. + +## kubernetes + +[Kubernetes](https://kubernetes.io) is an open-source +system for automating deployment, scaling, and +management of containerized applications. + +It's often abbreviated as _k8s_. + +## kubernetes-style object + +[fields required]: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields + +An object, expressed in a YAML or JSON file, with the +[fields required] by kubernetes. Basically just a +_kind_ field to identify the type, a _metadata/name_ +field to identify the particular instance, and an +_apiVersion_ field to identify the version (if there's +more than one version). + +## kustomize + +_kustomize_ is a command line tool supporting +template-free, structured customization of declarative +configuration targeted to k8s-style objects. + +_Targeted to k8s means_ that kustomize has some +understanding of API resources, k8s concepts like +names, labels, namespaces, etc. and the semantics of +resource patching. + +kustomize is an implementation of [DAM]. + +## off-the-shelf configuration + +An _off-the-shelf_ configuration is a kustomization and +resources intentionally published somewhere for others +to use. + +E.g. one might create a github repository like this: + +> ``` +> github.com/username/someapp/ +> kustomization.yaml +> deployment.yaml +> configmap.yaml +> README.md +> ``` + +Someone could then _fork_ this repo (on github) and +_clone_ their fork to their local disk for +customization. + +This clone could act as a [base] for the user's +own [overlays] to do further customization. + +## overlay + +An _overlay_ is a kustomization that depends on +another kustomization. + +The [kustomizations] an overlay refers to (via file +path, URI or other method) are called [bases]. + +An overlay is unusable without its bases. + +An overlay may act as a base to another overlay. + +Overlays make the most sense when there is _more than +one_, because they create different [variants] of a +common base - e.g. _development_, _QA_, _staging_ and +_production_ environment variants. + +These variants use the same overall resources, and vary +in relatively simple ways, e.g. the number of replicas +in a deployment, the CPU to a particular pod, the data +source used in a ConfigMap, etc. + +One configures a cluster like this: + +> ``` +> kustomize build someapp/overlays/staging |\ +> kubectl apply -f - +> +> kustomize build someapp/overlays/production |\ +> kubectl apply -f - +> ``` + +Usage of the base is implicit - the overlay's +kustomization points to the base. + +See also [root]. + +## package + +The word _package_ has no meaning in kustomize, as +kustomize is not to be confused with a package +management tool in the tradition of, say, [apt] or +[rpm]. + +## patch + +General instructions to modify a resource. + +There are two alternative techniques with similar +power but different notation - the +[strategic merge patch](#patchstrategicmerge) +and the [JSON patch](#patchjson6902). + +## patchStrategicMerge + +A _patchStrategicMerge_ is [strategic-merge]-style patch (SMP). + +An SMP looks like an incomplete YAML specification of +a k8s resource. The SMP includes `TypeMeta` +fields to establish the group/version/kind/name of the +[resource] to patch, then just enough remaining fields +to step into a nested structure to specify a new field +value, e.g. an image tag. + +By default, an SMP _replaces_ values. This is +usually desired when the target value is a simple +string, but may not be desired when the target +value is a list. + +To change this +default behavior, add a _directive_. Recognized +directives in YAML patches are _replace_ (the default) +and _delete_ (see [these notes][strategic-merge]). + +Note that for custom resources, SMPs are treated as +[json merge patches][JSONMergePatch]. + +Fun fact - any resource file can be used as +an SMP, overwriting matching fields in another +resource with the same group/version/kind/name, +but leaving all other fields as they were. + +TODO(monopole): add ptr to example. + +## patchJson6902 + +A _patchJson6902_ refers to a kubernetes [resource] and +a [JSONPatch] specifying how to change the resource. + +A _patchJson6902_ can do almost everything a +_patchStrategicMerge_ can do, but with a briefer +syntax. See this [example][patchExampleJson6902]. + +## plugin + +A chunk of code used by kustomize, but not necessarily +compiled into kustomize, to generate and/or transform a +kubernetes resource as part of a kustomization. + +Details [here](/docs/extending_kustomize). + +## resource + +A _resource_ in the context of a REST-ful API is the +target object of an HTTP operation like _GET_, _PUT_ or +_POST_. k8s offers a REST-ful API surface to interact +with clients. + +A _resource_, in the context of a kustomization, is a +[root] relative path to a [YAML] or [JSON] file +describing a k8s API object, like a Deployment or a +ConfigMap, or it's a path to a kustomization, or a URL +that resolves to a kustomization. + +More generally, a resource can be any correct YAML file +that [defines an object](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields) +with a _kind_ and a _metadata/name_ field. + +## root + +See [kustomization root][root]. + +## sub-target / sub-application / sub-package + +A _sub-whatever_ is not a thing. There are only +[bases] and [overlays]. + +## target + +The _target_ is the argument to `kustomize build`, e.g.: + +> ``` +> kustomize build $target +> ``` + +`$target` must be a path or a url to a [kustomization]. + +The target contains, or refers to, all the information +needed to create customized resources to send to the +[apply] operation. + +A target can be a [base] or an [overlay]. + +## transformer + +A transformer can modify a resource, or merely +visit it and collect information about it in the +course of a `kustomize build`. + +## variant + +A _variant_ is the outcome, in a cluster, of applying +an [overlay] to a [base]. + +E.g., a _staging_ and _production_ overlay both modify +some common base to create distinct variants. + +The _staging_ variant is the set of resources exposed +to quality assurance testing, or to some external users +who'd like to see what the next version of production +will look like. + +The _production_ variant is the set of resources +exposed to production traffic, and thus may employ +deployments with a large number of replicas and higher +cpu and memory requests. diff --git a/site/content/en/docs/Reference/versioningPolicy.md b/site/content/en/docs/Reference/versioningPolicy.md index 3703393994..98bb70e4dd 100644 --- a/site/content/en/docs/Reference/versioningPolicy.md +++ b/site/content/en/docs/Reference/versioningPolicy.md @@ -205,9 +205,8 @@ For native k8s types, this all requires writing Go code in the kubernetes core repo, to provide defaulting and conversions. -For CRDs, there's a [proposal] on how to manage -versioning (e.g. a remote service can offer type -defaulting and conversions). +[CRDs versioning] gives an overview on +how to manage versioning in CustomResourceDefinitions. ### Differences @@ -258,6 +257,7 @@ If missing, the value of `apiVersion` defaults to [field change policy]: #field-change-policy [some range]: https://kubernetes.io/docs/reference/using-api/deprecation-policy [proposal]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/customresources-versioning.md +[CRDs versioning]: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#overview [beta-level rules]: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md#alpha-beta-and-stable-versions [changes]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api_changes.md [special]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#resources @@ -265,7 +265,7 @@ If missing, the value of `apiVersion` defaults to [conventions]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md [release page]: https://github.com/kubernetes-sigs/kustomize/releases [release process]: https://github.com/kubernetes-sigs/kustomize/tree/master/releasing/README.md -[kustomization]: /references/kustomize/glossary#kustomization +[kustomization]: /docs/reference/glossary#kustomization [`kind`]: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#types-kinds [`apiVersion`]: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning [semantic versioning]: https://semver.org From 57eecf399e468b258f43a4b467e26798c76d9c1c Mon Sep 17 00:00:00 2001 From: Aashish Nehete Date: Sat, 9 Nov 2024 16:13:16 -0600 Subject: [PATCH 5/7] Update site/content/en/contribute/features/eschewedfeatures.md Co-authored-by: Mauren <698465+stormqueen1990@users.noreply.github.com> --- site/content/en/contribute/features/eschewedfeatures.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/content/en/contribute/features/eschewedfeatures.md b/site/content/en/contribute/features/eschewedfeatures.md index 4b8c10a5ba..07e8acdded 100644 --- a/site/content/en/contribute/features/eschewedfeatures.md +++ b/site/content/en/contribute/features/eschewedfeatures.md @@ -145,7 +145,7 @@ Allowing globbing in a kustomization file would also introduce the same problems as allowing globbing in [java import] declarations or BUILD/Makefile dependency rules. -`kustomize` will instead provide kustomization file editting +`kustomize` will instead provide kustomization file editing commands that accept globbed arguments, expand them at _edit time_ relative to the local file system, and store the resulting explicit names into the kustomization file. From b21bc17060df6833c6423c078d42fd1e8ca7d09f Mon Sep 17 00:00:00 2001 From: Aashish Nehete Date: Sat, 9 Nov 2024 16:13:24 -0600 Subject: [PATCH 6/7] Update site/content/en/contribute/features/eschewedfeatures.md Co-authored-by: Mauren <698465+stormqueen1990@users.noreply.github.com> --- site/content/en/contribute/features/eschewedfeatures.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/content/en/contribute/features/eschewedfeatures.md b/site/content/en/contribute/features/eschewedfeatures.md index 07e8acdded..1c47cf2a5a 100644 --- a/site/content/en/contribute/features/eschewedfeatures.md +++ b/site/content/en/contribute/features/eschewedfeatures.md @@ -142,7 +142,7 @@ declared in the [kustomization] file at `kustomize build` time would violate that goal. Allowing globbing in a kustomization file would also introduce -the same problems as allowing globbing in [java import] +the same problems as allowing globbing in [Java import] declarations or BUILD/Makefile dependency rules. `kustomize` will instead provide kustomization file editing From 0da38fde296c8cd2f4cc31bbbb417fbd88ac167a Mon Sep 17 00:00:00 2001 From: Aashish Nehete Date: Sat, 9 Nov 2024 16:13:32 -0600 Subject: [PATCH 7/7] Update site/content/en/contribute/features/eschewedfeatures.md Co-authored-by: Mauren <698465+stormqueen1990@users.noreply.github.com> --- site/content/en/contribute/features/eschewedfeatures.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/content/en/contribute/features/eschewedfeatures.md b/site/content/en/contribute/features/eschewedfeatures.md index 1c47cf2a5a..49cf2fb4f3 100644 --- a/site/content/en/contribute/features/eschewedfeatures.md +++ b/site/content/en/contribute/features/eschewedfeatures.md @@ -151,7 +151,7 @@ time_ relative to the local file system, and store the resulting explicit names into the kustomization file. [DAM]: /docs/reference/glossary/#declarative-application-management -[java import]: https://www.codebyamir.com/blog/pitfalls-java-import-wildcards +[Java import]: https://www.codebyamir.com/blog/pitfalls-java-import-wildcards [JSON patches]: /docs/reference/glossary/#patchjson6902 [kustomization]: /docs/reference/glossary/#kustomization [OTS workflow]: /docs/reference/glossary/#off-the-shelf-configuration