From 3168b2a1ed382fafdb6ca8b202abfe7de431570f Mon Sep 17 00:00:00 2001 From: Chris Carty Date: Mon, 18 Feb 2019 08:57:54 -0500 Subject: [PATCH] added link to examples --- docs/fields.md | 298 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 298 insertions(+) create mode 100644 docs/fields.md diff --git a/docs/fields.md b/docs/fields.md new file mode 100644 index 000000000..41caffa58 --- /dev/null +++ b/docs/fields.md @@ -0,0 +1,298 @@ +# Kustomize Fields + +You can find a list of examples [here](https://github.com/kubernetes-sigs/kustomize/tree/master/examples). + +## Operators + +### Namespace + +Adds namespace to all resources + +``` +namespace: my-namespace +``` + +### namePrefix + +Prepends value to the names of all resources +Ex. a deployment named `wordpress` would become `alices-wordpress` + +``` +namePrefix: alices- +``` + +### nameSuffix + +The value is appended to the names of all resources. +Ex. A deplou,ent names "wordpress" would become "wordpress-v2" +The suffix is appended before content has if resource type is ConfigMap or Secret +``` +nameSuffix: -v2 +``` + +### commonLabels + +Adds labels to all resources and selectors +``` +commonLabels: + someName: someValue + owner: alice + app: bingo +``` + +### commonAnnotations + +Adds annotions (non-identifying metadata) to add all resources. Like labls, these are key value pairs. + +``` +commonAnnotations: + oncallPager: 800-555-1212 +``` + +### resources + +Each entry in this list must resolve to an existing +resource definition in YAML. These are the resource +files that kustomize reads, modifies and emits as a +YAML string, with resources separated by document +markers ("---"). + +``` +resource: +- some-service.yaml +- sub-dir/some-deployment.yaml +``` + +### crds + +Each entry in this list should be a relative path to +a file for custom resource definition(CRD). + +The presence of this field is to allow kustomize be +aware of CRDs and apply proper +transformation for any objects in those types. + +Typical use case: A CRD object refers to a ConfigMap object. +In kustomization, the ConfigMap object name may change by adding namePrefix, nameSuffix, or hashing +The name reference for this ConfigMap object in CRD object need to be +updated with namePrefix, nameSuffix, or hashing in the same way. + +``` +crds: +- crds/typeA.yaml +- crds/typeB.yaml +``` + +### vars + +Vars are used to capture text from one resource's field +and insert that text elsewhere. + +For example, suppose one specify the name of a k8s Service +object in a container's command line, and the name of a +k8s Secret object in a container's environment variable, +so that the following would work: +``` + containers: + - image: myimage + command: ["start", "--host", "$(MY_SERVICE_NAME)"] + env: + - name: SECRET_TOKEN + value: $(SOME_SECRET_NAME) +``` + +To do so, add an entry to `vars:` as follows: + +``` +vars: + - name: SOME_SECRET_NAME + objref: + kind: Secret + name: my-secret + apiVersion: v1 + - name: MY_SERVICE_NAME + objref: + kind: Service + name: my-service + apiVersion: v1 + fieldref: + fieldpath: metadata.name + - name: ANOTHER_DEPLOYMENTS_POD_RESTART_POLICY + objref: + kind: Deployment + name: my-deployment + apiVersion: apps/v1 + fieldref: + fieldpath: spec.template.spec.restartPolicy +``` + +### images + +``` +images: + - name: postgres + newName: my-registry/my-postgres + newTag: v1 + - name: nginx + newTag: 1.8.0 + - name: my-demo-app + newName: my-app + - name: alpine + digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3 + +``` + +## Generators + +### configMapGenerator + +Each entry in this list results in the creation of +one ConfigMap resource (it's a generator of n maps). +The example below creates two ConfigMaps. One with the +names and contents of the given files, the other with +key/value as data. + +``` +configMapGenerator: +- name: myJavaServerProps + files: + - application.properties + - more.properties +- name: myJavaServerEnvVars + literals: + - JAVA_HOME=/opt/java/jdk + - JAVA_TOOL_OPTIONS=-agentlib:hprof +``` + +### secretGenerator + +Each entry in this list results in the creation of +one Secret resource (it's a generator of n secrets). + +``` +secretGenerator: +- name: app-tls + files: + - secret/tls.cert + - secret/tls.key + type: "kubernetes.io/tls" +- name: app-tls-namespaced + # you can define a namespace to generate secret in, defaults to: "default" + namespace: apps + files: + - tls.crt=catsecret/tls.cert + - tls.key=secret/tls.key + type: "kubernetes.io/tls" +- name: env_file_secret +``` + +env is a path to a file to read lines of key=val +you can only specify one env file per secret. + +``` +env: env.txt +type: Opaque +``` + +### generatorOptions +generatorOptions modify behavior of all ConfigMap and Secret generators + +``` +generatorOptions: +# labels to add to all generated resources +labels: + kustomize.generated.resources: somevalue +# annotations to add to all generated resources +annotations: + kustomize.generated.resource: somevalue +# disableNameSuffixHash is true disables the default behavior of adding a +# suffix to the names of generated resources that is a hash of +# the resource contents. +disableNameSuffixHash: true +``` +## Operands + +### bases + +Each entry in this list should resolve to a directory +containing a kustomization file, else the +customization fails. + +The entry could be a relative path pointing to a local directory +or a url pointing to a directory in a remote repo. +The url should follow hashicorp/go-getter URL format +https://github.com/hashicorp/go-getter#url-format + +The presence of this field means this file (the file +you a reading) is an _overlay_ that further +customizes information coming from these _bases_. + +Typical use case: a dev, staging and production +environment that are mostly identical but differing +crucial ways (image tags, a few server arguments, +etc. that differ from the common base). +``` +bases: +- ../../base +- github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6 +- github.com/Liujingfang1/mysql +- github.com/Liujingfang1/kustomize//examples/helloWorld?ref=test-branch +``` + +### patchesStrategicMerge + +Each entry in this list should resolve to +a partial or complete resource definition file. + +The names in these (possibly partial) resource files +must match names already loaded via the `resources` +field or via `resources` loaded transitively via the +`bases` entries. These entries are used to _patch_ +(modify) the known resources. + +Small patches that do one thing are best, e.g. modify +a memory request/limit, change an env var in a +ConfigMap, etc. Small patches are easy to review and +easy to mix together in overlays. + +### patchesJson6902 + +Each entry in this list should resolve to +a kubernetes object and a JSON patch that will be applied +to the object. +The JSON patch is documented at https://tools.ietf.org/html/rfc6902 + +target field points to a kubernetes object within the same kustomization +by the object's group, version, kind, name and namespace. +path field is a relative file path of a JSON patch file. +The content in this patch file can be either in JSON format as + +``` + [ + {"op": "add", "path": "/some/new/path", "value": "value"}, + {"op": "replace", "path": "/some/existing/path", "value": "new value"} + ] + ``` + +or in YAML format as + +- op: add + path: /some/new/path + value: value +- op:replace + path: /some/existing/path + value: new value + +``` +patchesJson6902: +- target: + version: v1 + kind: Deployment + name: my-deployment + path: add_init_container.yaml +- target: + version: v1 + kind: Service + name: my-service + path: add_service_annotation.yaml + ``` \ No newline at end of file