Skip to content

Commit

Permalink
Improve kustomization.go comments.
Browse files Browse the repository at this point in the history
  • Loading branch information
@monopole
monopole committed Oct 17, 2018
1 parent bad3ccd commit a5f5602
Show file tree
Hide file tree
Showing 2 changed files with 143 additions and 77 deletions.
119 changes: 81 additions & 38 deletions docs/glossary.md
View file
Original file line number Diff line number Diff line change
@@ -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/
Expand All @@ -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
Expand Down Expand Up @@ -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],
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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.
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.
_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].
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
Expand Down
101 changes: 62 additions & 39 deletions pkg/types/kustomization.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,68 +34,91 @@ 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"`

// 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"`
// 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
// 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.
// Format documented at https://tools.ietf.org/html/rfc6902
// and http://jsonpatch.com
PatchesJson6902 []patch.Json6902 `json:"patchesJson6902,omitempty" yaml:"patchesJson6902,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"`

// 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"`

//
// Operands - what kustomize operates on.
//

// Resources specifies the relative paths for resource files within the package.
// URLs and globs are not supported
// 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.
// 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"`

// 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.
// https://github.com/kubernetes/community/blob/master/contributors/devel/strategic-merge-patch.md
Patches []string `json:"patches,omitempty" yaml:"patches,omitempty"`
PatchesStrategicMerge []patch.StrategicMerge `json:"patchesStrategicMerge,omitempty" yaml:"patchesStrategicMerge,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"`

// 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/.
PatchesJson6902 []patch.Json6902 `json:"patchesJson6902,omitempty" yaml:"patchesJson6902,omitempty"`
//
// Generators (operators that create operands)
//

// 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 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"`

// 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 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"`

// Variables which will be substituted at runtime
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"`
//
// Deprecated fields - See DealWithDeprecatedFields
//

// ImageTags is a list of ImageTag for changing image tags
ImageTags []ImageTag `json:"imageTags,omitempty" yaml:"imageTags,omitempty"`
// Deprecated.
Patches []string `json:"patches,omitempty" yaml:"patches,omitempty"`
}

// DealWithDeprecatedFields should be called immediately after
Expand Down

0 comments on commit a5f5602

Please sign in to comment.