From a5f56027b5d0cb8df3282cf5650d47a733803983 Mon Sep 17 00:00:00 2001 From: jregan Date: Wed, 17 Oct 2018 06:39:32 -0700 Subject: [PATCH] Improve kustomization.go comments. --- docs/glossary.md | 119 +++++++++++++++++++++++++------------ pkg/types/kustomization.go | 105 +++++++++++++++++++------------- 2 files changed, 145 insertions(+), 79 deletions(-) diff --git a/docs/glossary.md b/docs/glossary.md index 8a3aaca1a..9cdb32f18 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -1,5 +1,6 @@ # Glossary - +[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/community/blob/master/contributors/design-proposals/architecture/declarative-application-management.md [JSON]: https://www.json.org/ @@ -23,13 +24,14 @@ [patch]: #patch [patches]: #patch [patchJson6902]: #patchjson6902 +[patchExampleJson6902]: https://github.com/kubernetes-sigs/kustomize/blob/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 [rpm]: https://en.wikipedia.org/wiki/Rpm_(software) -[strategic merge]: https://github.com/kubernetes/community/blob/master/contributors/devel/strategic-merge-patch.md +[strategic-merge]: https://github.com/kubernetes/community/blob/master/contributors/devel/strategic-merge-patch.md [target]: #target [variant]: #variant [variants]: #variant @@ -97,6 +99,19 @@ simpler than the workflow associated with an 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], @@ -134,18 +149,23 @@ Here's an [example](kustomization.yaml). A kustomization contains fields falling into these categories: - * Immediate customization declarations, e.g. - _namePrefix_, _commonLabels_, etc. - * Resource _generators_ for configmaps and secrets. - * References to _external files_ in these categories: + * _Customization operators_ for modifying operands, e.g. + _namePrefix_, _commonLabels_, _patches_, etc. + + * _Customization operands_: * [resources] - completely specified k8s API objects, e.g. `deployment.yaml`, `configmap.yaml`, etc. - * [patches] - _partial_ resources that modify full - resources defined in a [base] - (only meaningful in an [overlay]). - * [bases] - path to a directory containing - a [kustomization] (only meaningful in an [overlay]). - * (_TBD_) Standard k8s API kind-version fields. + * [bases] - paths or github URLs specifying directories + containing a [kustomization]. These bases may + be subjected to more customization, or merely + included in the output. + * [CRD]s - custom resource definition files, to allow use + of _custom_ resources in the _resources_ list. + Not an actual operand - but allows the use of new operands. + + * Generators, for creating more resources + (configmaps and secrets) which can then be + customized. ## kubernetes @@ -249,45 +269,68 @@ management tool in the tradition of, say, [apt] or ## patch -A _patch_ is a partially defined k8s resource with a -name that must match a resource already known per -traversal rules built into [kustomize]. +General instructions to modify a resource. -_Patch_ is a field in the kustomization, distinct from -resources, because a patch file looks like a resource -file, but has different semantics. A patch depends on -(modifies) a resource, whereas a resource has no -dependencies. Since any resource file can be used as a -patch, one cannot reliably distinguish a resource from -a patch just by looking at the file's [YAML]. +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 +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 include _replace_ (the default), _merge_ +(avoid replacing a list), _delete_ and a few more +(see [these notes][strategic-merge]). + +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 object and a [JSONPatch] -that can patch the object. A [JSONPatch] contains a list of operations to change the object's field directly. -This is different from [patch], which is -applied to a target kubernetes object by [strategic merge]. -_patchesJson6902_ is a field in kustomization. It contains a list of -_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]. ## resource -A _resource_, in the context of kustomize, is a path to -a [YAML] or [JSON] file that completely defines a -functional k8s API object, like a deployment or a -configmap. +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 kustomization file, +is a path to a [YAML] or [JSON] file describing +a k8s API object, like a Deployment or a +ConfigmMap. 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. -A _resource_ in the content of a REST-ful API is the -target of an HTTP operation like _GET_, _PUT_ or -_POST_. k8s offers a RESTful API surface to interact -with clients. - - ## sub-target / sub-application / sub-package A _sub-whatever_ is not a thing. There are only diff --git a/pkg/types/kustomization.go b/pkg/types/kustomization.go index c1b4a0395..3e64ee4e1 100644 --- a/pkg/types/kustomization.go +++ b/pkg/types/kustomization.go @@ -34,6 +34,10 @@ type TypeMeta struct { type Kustomization struct { TypeMeta `json:",inline" yaml:",inline"` + // + // Operators - what kustomize can do. + // + // NamePrefix will prefix the names of all resources mentioned in the kustomization // file including generated configmaps and secrets. NamePrefix string `json:"namePrefix,omitempty" yaml:"namePrefix,omitempty"` @@ -41,61 +45,80 @@ type Kustomization struct { // Namespace to add to all objects. Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"` - // Labels to add to all objects and selectors. - // These labels would also be used to form the selector for apply --prune - // Named differently than “labels” to avoid confusion with metadata for - // this object + // CommonLabels to add to all objects and selectors. CommonLabels map[string]string `json:"commonLabels,omitempty" yaml:"commonLabels,omitempty"` - // Annotations to add to all objects. + // CommonAnnotations to add to all objects. CommonAnnotations map[string]string `json:"commonAnnotations,omitempty" yaml:"commonAnnotations,omitempty"` - // Each entry should be either a path to a directory containing kustomization.yaml - // Or a repo URL pointing to a remote directory containing kustomization.yaml - // The repo URL should follow hashicorp/go-getter URL format - // https://github.com/hashicorp/go-getter#url-format - Bases []string `json:"bases,omitempty" yaml:"bases,omitempty"` - - // Resources specifies the relative paths for resource files within the package. - // URLs and globs are not supported - Resources []string `json:"resources,omitempty" yaml:"resources,omitempty"` - - // Crds specifies relative paths to custom resource definition files. - Crds []string `json:"crds,omitempty" yaml:"crds,omitempty"` - - // An Patch entry is very similar to an Resource entry. - // It specifies the relative paths for patch files within the package. - // URLs and globs are not supported. - // The patch files should be Strategic Merge Patch, the default patching behavior for kubectl. + // PatchesStrategicMerge specifies the relative path to a file + // containing a strategic merge patch. Format documented at // https://github.com/kubernetes/community/blob/master/contributors/devel/strategic-merge-patch.md - Patches []string `json:"patches,omitempty" yaml:"patches,omitempty"` + // URLs and globs are not supported. PatchesStrategicMerge []patch.StrategicMerge `json:"patchesStrategicMerge,omitempty" yaml:"patchesStrategicMerge,omitempty"` // JSONPatches is a list of JSONPatch for applying JSON patch. - // The JSON patch is documented at https://tools.ietf.org/html/rfc6902 - // and http://jsonpatch.com/. + // Format documented at https://tools.ietf.org/html/rfc6902 + // and http://jsonpatch.com PatchesJson6902 []patch.Json6902 `json:"patchesJson6902,omitempty" yaml:"patchesJson6902,omitempty"` - // List of configmaps to generate from configuration sources. - // Base/overlay concept doesn't apply to this field. - // If a configmap want to have a base and an overlay, it should go to Bases - // and Overlays fields. - ConfigMapGenerator []ConfigMapArgs `json:"configMapGenerator,omitempty" yaml:"configMapGenerator,omitempty"` + // ImageTags is a list of (image name, new tag) pairs for simply + // changing a an image tag. This can also be achieved with a + // patch, but this operator is simpler to specify. + ImageTags []ImageTag `json:"imageTags,omitempty" yaml:"imageTags,omitempty"` - // List of secrets to generate from secret commands. - // Base/overlay concept doesn't apply to this field. - // If a secret want to have a base and an overlay, it should go to Bases and - // Overlays fields. - SecretGenerator []SecretArgs `json:"secretGenerator,omitempty" yaml:"secretGenerator,omitempty"` - - // Variables which will be substituted at runtime + // Vars allow things modified by kustomize to be injected into a + // container specification. A var is a name (e.g. FOO) associated + // with a field in a specific resource instance. The field must + // contain a value of type string, and defaults to the name field + // of the instance. Any appearance of "$(FOO)" in the container + // spec will be replaced at kustomize build time, after the final + // value of the specified field has been determined. Vars []Var `json:"vars,omitempty" yaml:"vars,omitempty"` - // If set to true, all images need to have tags - RequireTag bool `json:"requireTag,omitempty" yaml:"requireTag,omitempty"` + // + // Operands - what kustomize operates on. + // - // ImageTags is a list of ImageTag for changing image tags - ImageTags []ImageTag `json:"imageTags,omitempty" yaml:"imageTags,omitempty"` + // Resources specifies relative paths to files holding YAML representations + // of kubernetes API objects. URLs and globs not supported. + Resources []string `json:"resources,omitempty" yaml:"resources,omitempty"` + + // Crds specifies relative paths to Custom Resource Definition files. + // This allows custom resources to be recognized as operands, making + // it possible to add them to the Resources list. + // CRDs themselves are not modified. + Crds []string `json:"crds,omitempty" yaml:"crds,omitempty"` + + // Bases are relative paths or github repository URLs specifying a + // directory containing a kustomization.yaml file. + // URL format: https://github.com/hashicorp/go-getter#url-format + Bases []string `json:"bases,omitempty" yaml:"bases,omitempty"` + + // + // Generators (operators that create operands) + // + + // ConfigMapGenerator is a list of configmaps to generate from + // local data (one configMap per list item). + // The resulting resource is a normal operand, subject to + // name prefixing, patching, etc. By default, the name of + // the map will have a suffix hash generated from its contents. + ConfigMapGenerator []ConfigMapArgs `json:"configMapGenerator,omitempty" yaml:"configMapGenerator,omitempty"` + + // SecretGenerator is a list of secrets to generate from + // local data (one secret per list item). + // The resulting resource is a normal operand, subject to + // name prefixing, patching, etc. By default, the name of + // the map will have a suffix hash generated from its contents. + SecretGenerator []SecretArgs `json:"secretGenerator,omitempty" yaml:"secretGenerator,omitempty"` + + // + // Deprecated fields - See DealWithDeprecatedFields + // + + // Deprecated. + Patches []string `json:"patches,omitempty" yaml:"patches,omitempty"` } // DealWithDeprecatedFields should be called immediately after