buildMetadata

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    

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.