kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-05-17 18:25:26 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

Add buildMetadata task and ref (#5511)

Browse Source 
* 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
2024-01-26 15:12:39 -08:00
committed by GitHub
parent 69826668a7
commit 26165a86b7
3 changed files with 368 additions and 305 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
site/content/en/docs/Reference/API/Kustomization File/bases.md
View File

@@ -4,8 +4,9 @@ linkTitle: "bases"
type: docs
weight: 2
description: >
Add resources from a kustomization dir.
Add resources from a kustomization directory.
---
`apiVersion: kustomize.config.k8s.io/v1beta1`
{{% pageinfo color="warning" %}}
The `bases` field was deprecated in v2.1.0. This field will never be removed from the
@@ -18,7 +19,14 @@ kustomize CLI, and removal itself will happen in a future major version bump.
You can run `kustomize edit fix` to automatically convert `bases` to `resources`.
{{% /pageinfo %}}
Move entries into the [resources](/docs/reference/api/kustomization-file/resources)
field. This allows bases - which are still a
[central concept](/docs/concepts/bases) - to be
ordered relative to other input resources.
### bases
A base is a kustomization referred to by some other kustomization. Move entries into the [resources] field.
---
* **bases** ([]string)
List of relative paths to kustomization specifications.
[resources]: /docs/reference/api/kustomization-file/resources

315
site/content/en/docs/Reference/API/Kustomization File/buildMetadata.md
View File

@@ -2,315 +2,30 @@
title: "buildMetadata"
linkTitle: "buildMetadata"
type: docs
weight: 2
weight: 3
description: >
Specify options for including information about the build in annotations or labels.
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.
`apiVersion: kustomize.config.k8s.io/v1beta1`
These options are:
See the [Tasks section] for examples of how to use the `buildMetadata` field.
- `managedByLabel`
- `originAnnotations`
- `transformerAnnotations`
### buildMetadata
BuildMetadata specifies options for adding kustomize build information to resource labels or annotations.
It is possible to set one or all of these options in the kustomization file:
---
```yaml
buildMetadata: [managedByLabel, originAnnotations, transformerAnnotations]
```
* **buildMetadata** ([]string)
### 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:
List of strings used to toggle different build options. The strings can be one of three builtin
options that add metadata to each resource about how the resource was built. It is possible to set one or all of these options in the kustomization file.
```yaml
buildMetadata: [managedByLabel]
```
These options are:
- `managedByLabel`
- `originAnnotations`
- `transformerAnnotations`
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
```
[Tasks section]: /docs/tasks/build_metadata/

340
site/content/en/docs/Tasks/build_metadata.md Normal file
View 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/