+ + + + + + +
+

buildMetadata

+
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:

+
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:

+
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

+
apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+- service.yaml
+buildMetadata: [managedByLabel]
+

service.yaml

+
apiVersion: v1
+kind: Service
+metadata:
+  name: myService
+spec:
+  ports:
+  - port: 7002
+

kustomize build will produce a resource with an output like the following:

+
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:

+
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 tofoo/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:

+
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:

+
resources:
+- deployment.yaml
+
+buildMetadata: [originAnnotations]
+

would produce a resource with an annotation like the following:

+
config.kubernetes.io/origin: |
+    path: deployment.yaml
+
Local custom generator
+

A kustomization such as the following:

+
generators:
+- generator.yaml
+
+buildMetadata: [originAnnotations]
+

would produce a resource with an annotation like the following:

+
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:

+
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:

+
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:

+
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:

+
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 tofoo/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:

+
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:

+
transformers:
+- transformer.yaml
+
+buildMetadata: [transformerAnnotations]
+
+

would produce a resource with an annotation like the following:

+
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:

+
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:

+
resources:
+- deployment.yaml
+
+namePrefix: pre-
+

deployment.yaml contains the following:

+
apiVersion: v1
+kind: Deployment
+metadata:
+  name: deploy
+

Running kustomize build on the top-level kustomization would produce the following output:

+
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    
+
+
+ + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + +
+ + +
Last modified February 1, 2022: document kustomize buildmetadata field (6ea0f91b) +
+
+ +