mirror of
https://github.com/kubernetes-sigs/kustomize.git
synced 2026-06-10 16:42:51 +00:00
docs(api/kustomizaion-file): migrate field sections
This commit is contained in:
Jeong Jinwoo
@@ -0,0 +1,316 @@
|
||||
---
|
||||
title: "buildMetadata"
|
||||
linkTitle: "buildMetadata"
|
||||
type: docs
|
||||
weight: 2
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user