-
Notifications
You must be signed in to change notification settings - Fork 2.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #5313 from bugoverdose/docs/api
Add API section to Reference Section
- Loading branch information
Showing
26 changed files
with
3,787 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
24 changes: 24 additions & 0 deletions
24
site/content/en/docs/Reference/API/Kustomization File/bases.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| --- | ||
| title: "bases" | ||
| linkTitle: "bases" | ||
| type: docs | ||
| weight: 1 | ||
| description: > | ||
| Add resources from a kustomization dir. | ||
| --- | ||
|
|
||
| {{% pageinfo color="warning" %}} | ||
| The `bases` field was deprecated in v2.1.0. This field will never be removed from the | ||
| kustomize.config.k8s.io/v1beta1 Kustomization API, but it will not be included | ||
| in the kustomize.config.k8s.io/v1 Kustomization API. When Kustomization v1 is available, | ||
| we will announce the deprecation of the v1beta1 version. There will be at least | ||
| two releases between deprecation and removal of Kustomization v1beta1 support from the | ||
| 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. |
316 changes: 316 additions & 0 deletions
316
site/content/en/docs/Reference/API/Kustomization File/buildMetadata.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| ``` |
Oops, something went wrong.