mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-06-11 17:12:51 +00:00
Add buildMetadata task and ref (#5511)
* Add buildMetadata task and ref Move build metadata tasks, draft buildMetadata reference Clean up buildMetadata ref Add managed by label task Add local non-generated task Add local generated resource Add remote generator task Clean up tasks and ref Add local transformer annotation example Add local and remote transformer example * Address PR feedback and general cleanup
This commit is contained in:
Nick
340
site/content/en/docs/Tasks/build_metadata.md
Normal file
340
site/content/en/docs/Tasks/build_metadata.md
Normal file
@@ -0,0 +1,340 @@
|
||||
---
|
||||
title: "Build Metadata"
|
||||
linkTitle: "Build Metadata"
|
||||
weight: 5
|
||||
date: 2024-01-10
|
||||
description: >
|
||||
Adding build information to labels or annotations.
|
||||
---
|
||||
|
||||
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.
|
||||
```yaml
|
||||
# kustomization.yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
resources:
|
||||
- service.yaml
|
||||
buildMetadata:
|
||||
- managedByLabel
|
||||
```
|
||||
|
||||
2. Create a Service manifest.
|
||||
```yaml
|
||||
# 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.
|
||||
|
||||
```yaml
|
||||
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.
|
||||
```yaml
|
||||
# kustomization.yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
resources:
|
||||
- service.yaml
|
||||
buildMetadata:
|
||||
- originAnnotations
|
||||
```
|
||||
|
||||
2. Create a Service manifest.
|
||||
```yaml
|
||||
# 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.
|
||||
|
||||
```yaml
|
||||
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.
|
||||
```yaml
|
||||
# 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.
|
||||
|
||||
```yaml
|
||||
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.
|
||||
```yaml
|
||||
# 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.
|
||||
```yaml
|
||||
# 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.
|
||||
|
||||
```yaml
|
||||
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.
|
||||
```yaml
|
||||
# kustomization.yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
namespace: app
|
||||
resources:
|
||||
- service.yaml
|
||||
buildMetadata:
|
||||
- transformerAnnotations
|
||||
```
|
||||
|
||||
2. Create a Service manifest.
|
||||
```yaml
|
||||
# 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.
|
||||
|
||||
```yaml
|
||||
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.
|
||||
```yaml
|
||||
# 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.
|
||||
```yaml
|
||||
# kustomization.yaml
|
||||
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||
kind: Kustomization
|
||||
resources:
|
||||
- service.yaml
|
||||
namePrefix: pre-
|
||||
```
|
||||
|
||||
The `service.yaml` contains the following:
|
||||
```yaml
|
||||
# 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.
|
||||
|
||||
```yaml
|
||||
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
|
||||
```
|
||||
|
||||
[`buildMetadata`]: /docs/reference/api/kustomization-file/buildmetadata/
|
||||
Reference in New Issue
Block a user