Build Metadata

Kustomize build information can be added to resource labels or annotations with the buildMetadata field.

Add Managed By Label

Specify the managedByLabel option in the buildMetadata field to mark the resource as having been managed by Kustomize.

The following example adds the app.kubernetes.io/managed-by label to a resource.

1. Create a Kustomization file.

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- service.yaml
buildMetadata:
- managedByLabel

2. Create a Service manifest.

# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: myService
spec:
  ports:
  - port: 7002

3. Add label with kustomize build.

The output shows that the managedByLabel option adds the app.kubernetes.io/managed-by label with Kustomize build information.

apiVersion: v1
kind: Service
metadata:
  name: myService
  labels:
    app.kubernetes.io/managed-by: kustomize-v5.2.1
spec:
  ports:
  - port: 7002

Add Origin Annotation with Local Resource

Specify the originAnnotations option in the buildMetadata field to annotate resources with information about their origin.

The possible fields of these annotations are:

• path: The path to a resource file itself.
• ref: If from a remote file or generator, the git reference of the repository URL.
• repo: If from a remote file or generator, the repository source.
• configuredIn: The path to the generator configuration for a generated resource. This would point to the Kustomization file itself if a generator is invoked via a field.
• configuredBy: The ObjectReference of the generator configuration for a generated resource.

If the resource is from the resources field, this annotation contains data about the file it originated from. 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.

The following example adds the config.kubernetes.io/origin annotation to a non-generated resource defined in a local file.

1. Create a Kustomization file.

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- service.yaml
buildMetadata:
- originAnnotations

2. Create a Service manifest.

# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: myService
spec:
  ports:
  - port: 7002

3. Add origin annotation with kustomize build.

The output shows that the originAnnotations option adds the config.kubernetes.io/origin annotation with Kustomize build information.

apiVersion: v1
kind: Service
metadata:
  name: myService
  annotations:
    config.kubernetes.io/origin: |
      path: service.yaml      
spec:
  ports:
  - port: 7002

Add Origin Annotation with Local Generator

Generated resources will receive an annotation containing data about the generator that produced it with the originAnnotations option.

The following example adds the config.kubernetes.io/origin annotation to a generated resource.

1. Create a Kustomization file.

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
configMapGenerator:
- name: my-java-server-env-vars
  literals:
  - JAVA_HOME=/opt/java/jdk
  - JAVA_TOOL_OPTIONS=-agentlib:hprof
buildMetadata:
- originAnnotations

2. Generate a ConfigMap that includes an origin annotation with kustomize build.

The output shows that the originAnnotations option adds the config.kubernetes.io/origin annotation with information about the local ConfigMapGenerator that generated the ConfigMap.

kind: ConfigMap
apiVersion: v1
metadata:
  name: my-java-server-env-vars-c68g99m4hf
  annotations:
    config.kubernetes.io/origin: |
      configuredIn: kustomization.yaml
      configuredBy:
        kind: ConfigMapGenerator
        apiVersion: builtin      
data:
  JAVA_HOME: /opt/java/jdk
  JAVA_TOOL_OPTIONS: -agentlib:hprof

Add Origin Annotation with Remote Generator

A remote file or generator will receive an annotation containing the repository URL and git reference with the originAnnotations option.

The following example adds the config.kubernetes.io/origin annotation to a resource generated with a remote generator.

1. Create a Kustomization file.

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- github.com/examplerepo/?ref=v1.0.6
buildMetadata:
- originAnnotations

2. This example uses a remote base with the following Kustomization.

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
configMapGenerator:
- name: my-java-server-env-vars
  literals:
  - JAVA_HOME=/opt/java/jdk
  - JAVA_TOOL_OPTIONS=-agentlib:hprof

3. Generate a ConfigMap that includes an origin annotation with kustomize build.

The output shows that the originAnnotations option adds the config.kubernetes.io/origin annotation with build information about the remote ConfigMapGenerator that generated the ConfigMap.

kind: ConfigMap
apiVersion: v1
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      
data:
  JAVA_HOME: /opt/java/jdk
  JAVA_TOOL_OPTIONS: -agentlib:hprof

Add Annotation with Local Transformer

FEATURE STATE: [alpha]

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.

Add the transformerAnnotations option to the buildMetadata field to annotate resources with information about the transformers that have acted on them.

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 alpha.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:

• ref: If from a remote file or generator, the git reference of the repository URL.
• repo: If from a remote file or generator, the repository source.
• configuredIn: The path to the transformer configuration. This would point to the Kustomization file itself if a transformer is invoked via a field.
• configuredBy: The ObjectReference of the transformer configuration.

All local file paths are relative to the top-level Kustomization. This behavior is similar to how the originAnnotations option works.

The following example adds the alpha.config.kubernetes.io/transformations annotation to a resource updated with the NamespaceTransformer.

1. Create a Kustomization file.

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: app
resources:
- service.yaml
buildMetadata:
- transformerAnnotations

2. Create a Service manifest.

# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: myService
spec:
  ports:
  - port: 7002

3. Add transformer annotation with kustomize build.

The output shows that the transformerAnnotations option adds the alpha.config.kubernetes.io/transformations annotation with build information about the transformer that updated the resource.

apiVersion: v1
kind: Service
metadata:
  name: myService
  namespace: app
  annotations:
    alpha.config.kubernetes.io/transformations: |
      - configuredIn: kustomization.yaml
        configuredBy:
          apiVersion: builtin
          kind: NamespaceTransformer      
spec:
  ports:
  - port: 7002

Add Annotation with Local and Remote Transformer

The following example adds the alpha.config.kubernetes.io/transformations annotation to a resource updated by a local and remote transformer.

1. Create a Kustomization file.

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: app
resources:
- github.com/examplerepo/?ref=v1.0.6
buildMetadata:
- transformerAnnotations

2. This example uses a remote base with the following Kustomization.

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- service.yaml
namePrefix: pre-

The service.yaml contains the following:

# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: myService
spec:
  ports:
  - port: 7002

3. Run kustomize build.

The output shows that the transformerAnnotations option adds the alpha.config.kubernetes.io/transformations annotation with build information about the transformers that updated the resource.

apiVersion: v1
kind: Deployment
metadata:
  name: pre-deploy
  namespace: app
  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