document kustomize buildmetadata field

site/content/en/references/kustomize/kustomization/buildmetadata/_index.md

@@ -0,0 +1,316 @@
+---
+title: "buildMetadata"
+linkTitle: "buildMetadata"
+type: docs
+weight: 18
+description: >
+    Specify options for including information about the build in annotations or labels. 
+---
+
+The `buildMetadata` field is a list of strings. The strings can be one of three builtin
+options that add some metadata to each resource about how the resource was built. 
+
+These options are:
+
+- `managedByLabel`
+- `originAnnotations`
+- `transformerAnnotations`
+
+It is possible to set one or all of these options in the kustomization file:
+
+```yaml
+buildMetadata: [managedByLabel, originAnnotations, transformerAnnotations]
+```
+
+### Managed By Label
+To mark the resource as having been managed by kustomize, you can specify the `managedByLabel`
+option in the `buildMetadata` field of the kustomization:
+
+```yaml
+buildMetadata: [managedByLabel]
+```
+
+This will add the label `app.kubernetes.io/managed-by` to each resource with the version of kustomize 
+that has built it. For example, given the following input:
+
+kustomization.yaml
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+- service.yaml
+buildMetadata: [managedByLabel]
+```
+
+service.yaml
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: myService
+spec:
+  ports:
+  - port: 7002
+```
+
+`kustomize build` will produce a resource with an output like the following:
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    app.kubernetes.io/managed-by: kustomize-v4.4.1
+  name: myService
+spec:
+  ports:
+  - port: 7002
+```
+
+
+### Origin Annotation
+To annotate resources with information about their origin, you can specify the `originAnnotations`: 
+
+```yaml
+buildMetadata: [originAnnotations]
+```
+
+When this option is set, generated resources will receive an annotation with key `config.kubernetes.io/origin`,
+containing data about the generator that produced it. If the resource is from the `resources` field, this annotation
+contains data about the file it originated from. 
+
+The possible fields of these annotations are:
+
+- `path`: The path to a resource file itself
+- `ref`: If from a remote file or generator, the ref of the repo URL.
+- `repo`: If from a remote file or generator, the repo source
+- `configuredIn`: If a generated resource, the path to the generator config. If a generator is invoked via a field 
+in the kustomization file, this would point to the kustomization file itself. 
+- `configuredBy`: If a generated resource, the ObjectReference of the generator config.  
+
+
+All local file paths are relative to the top-level kustomization, i.e. the kustomization file in the directory upon 
+which `kustomize build` was invoked. For example, if someone were to run `kustomize build foo`, all file paths 
+in the annotation output would be relative to`foo/kustomization.yaml`. All remote file paths are relative to the root of the 
+remote repository. Any fields that are not applicable would be omitted from the final output.  
+
+Here is an example of what this would look like:
+```yaml
+config.kubernetes.io/origin: |
+  path: path.yaml 
+  ref: v0.0.0 
+  repo: http://github.com/examplerepo 
+  configuredIn: path/to/generatorconfig 
+  configuredBy: 
+    kind: Generator
+    apiVersion: builtin 
+    name: foo
+    namespace: default
+```
+
+#### Examples
+
+##### Resource declared from `resources`
+A kustomization such as the following:
+
+```yaml
+resources:
+- deployment.yaml
+
+buildMetadata: [originAnnotations]
+```
+
+would produce a resource with an annotation like the following:
+
+```yaml
+config.kubernetes.io/origin: |
+  path: deployment.yaml
+```
+
+##### Local custom generator
+A kustomization such as the following:
+
+```yaml
+generators:
+- generator.yaml
+
+buildMetadata: [originAnnotations]
+```
+
+would produce a resource with an annotation like the following:
+
+```yaml
+config.kubernetes.io/origin: |
+  configuredIn: generator.yaml
+  configuredBy: 
+    kind: MyGenerator
+    apiVersion: v1
+    name: generator
+```
+
+##### Remote builtin generator
+We have a top-level kustomization such as the following:
+
+```yaml
+resources:
+- github.com/examplerepo/?ref=v1.0.6
+
+buildMetadata: [originAnnotations]
+```
+
+which uses `github.com/examplerepo/?ref=v1.0.6` as a remote base. This remote base has the following kustomization
+defined in `github.com/examplerepo/kustomization.yaml`:
+
+```yaml
+configMapGenerator:
+- name: my-java-server-env-vars
+  literals:
+  - JAVA_HOME=/opt/java/jdk
+  - JAVA_TOOL_OPTIONS=-agentlib:hprof
+```
+
+Running `kustomize build` on the top-level kustomization would produce the following output:
+
+```yaml
+apiVersion: v1
+data:
+  JAVA_HOME: /opt/java/jdk
+  JAVA_TOOL_OPTIONS: -agentlib:hprof
+kind: ConfigMap
+metadata:
+  name: my-java-server-env-vars-44k658k8gk
+  annotations:
+    config.kubernetes.io/origin: |
+      ref: v1.0.6 
+      repo: github.com/examplerepo 
+      configuredIn: kustomization.yaml
+      configuredBy: 
+        kind: ConfigMapGenerator
+        apiVersion: builtin 
+```
+
+### Transformer Annotations [Alpha]
+
+To annotate resources with information about the transformers that have acted on them, you can add the
+`transformerAnnotations` option to the `buildMetadata` field of the kustomization:
+
+```yaml
+buildMetadata: [transformerAnnotations]
+```
+
+When the `transformerAnnotations` option is set, kustomize will add annotations with information about what transformers 
+have acted on each resource. Transformers can be invoked either through various fields in the kustomization file 
+(e.g. the `replacements` field will invoke the ReplacementTransformer), or through the `transformers` field.
+
+The annotation key for transformer annotations will be `config.kubernetes.io/transformations`, which will contain a list of
+transformer data. The possible fields in each item in this list is identical to the possible fields in `config.kubernetes.io/origin`,
+except that the transformer annotation does not have a `path` field: 
+
+The possible fields of these annotations are:
+
+- `path`: The path to a resource file itself
+- `ref`: If from a remote file or generator, the ref of the repo URL.
+- `repo`: If from a remote file or generator, the repo source
+- `configuredIn`: The path to the transformer config. If a transformer is invoked via a field 
+in the kustomization file, this would point to the kustomization file itself. 
+- `configuredBy`: The ObjectReference of the transformer config.  
+
+All local file paths are relative to the top-level kustomization, i.e. the kustomization file in the directory upon 
+which `kustomize build` was invoked. For example, if someone were to run `kustomize build foo`, all file paths 
+in the annotation output would be relative to`foo/kustomization.yaml`. All remote file paths are relative to the root of the 
+remote repository. Any fields that are not applicable would be omitted from the final output.  
+
+Here is an example of what this would look like:
+```yaml
+config.kubernetes.io/transformations: |
+  - ref: v0.0.0 
+    repo: http://github.com/examplerepo 
+    configuredIn: path/to/transformerconfig 
+    configuredBy: 
+      kind: Transformer
+      apiVersion: builtin 
+      name: foo
+      namespace: default
+```
+
+
+While this field is in alpha, it will receive the `alpha` prefix, so you will see the annotation key 
+`alpha.config.kubernetes.io/transformations` instead. We are not guaranteeing that the annotation content will be stable during
+alpha, and reserve the right to make changes as we evolve the feature. 
+
+
+#### Examples
+
+#### Local custom transformer
+A kustomization such as the following:
+
+```yaml
+transformers:
+- transformer.yaml
+
+buildMetadata: [transformerAnnotations]
+
+```
+
+would produce a resource with an annotation like the following:
+
+```yaml
+config.kubernetes.io/transformations: |
+- configuredIn: transformer.yaml
+  configuredBy: 
+    kind: MyTransformer
+    apiVersion: v1
+    name: transformer
+```
+
+##### Remote builtin transformer + local builtin transformer
+We have a top-level kustomization such as the following:
+
+```yaml
+resources:
+- github.com/examplerepo/?ref=v1.0.6
+
+buildMetadata: [transformerAnnotations]
+
+namespace: my-ns
+```
+
+which uses `github.com/examplerepo/?ref=v1.0.6` as a remote base. This remote base has the following kustomization
+defined in `github.com/examplerepo/kustomization.yaml`:
+
+```yaml
+resources:
+- deployment.yaml
+
+namePrefix: pre-
+```
+
+`deployment.yaml` contains the following:
+
+```yaml
+apiVersion: v1
+kind: Deployment
+metadata:
+  name: deploy
+```
+
+Running `kustomize build` on the top-level kustomization would produce the following output:
+
+```yaml
+apiVersion: v1
+kind: Deployment
+metadata:
+  name: pre-deploy
+  annotations:
+    config.kubernetes.io/transformations: |
+    - ref: v1.0.6 
+      repo: github.com/examplerepo 
+      configuredIn: kustomization.yaml
+      configuredBy: 
+        kind: PrefixSuffixTransformer
+        apiVersion: builtin 
+    - configuredIn: kustomization.yaml
+      configuredBy:
+        kind: NamespaceTransformer
+        apiVersion: builtin
+```