|
| 1 | +--- |
| 2 | +title: "buildMetadata" |
| 3 | +linkTitle: "buildMetadata" |
| 4 | +type: docs |
| 5 | +weight: 2 |
| 6 | +description: > |
| 7 | + Specify options for including information about the build in annotations or labels. |
| 8 | +--- |
| 9 | + |
| 10 | +The `buildMetadata` field is a list of strings. The strings can be one of three builtin |
| 11 | +options that add some metadata to each resource about how the resource was built. |
| 12 | + |
| 13 | +These options are: |
| 14 | + |
| 15 | +- `managedByLabel` |
| 16 | +- `originAnnotations` |
| 17 | +- `transformerAnnotations` |
| 18 | + |
| 19 | +It is possible to set one or all of these options in the kustomization file: |
| 20 | + |
| 21 | +```yaml |
| 22 | +buildMetadata: [managedByLabel, originAnnotations, transformerAnnotations] |
| 23 | +``` |
| 24 | +
|
| 25 | +### Managed By Label |
| 26 | +To mark the resource as having been managed by kustomize, you can specify the `managedByLabel` |
| 27 | +option in the `buildMetadata` field of the kustomization: |
| 28 | + |
| 29 | +```yaml |
| 30 | +buildMetadata: [managedByLabel] |
| 31 | +``` |
| 32 | + |
| 33 | +This will add the label `app.kubernetes.io/managed-by` to each resource with the version of kustomize |
| 34 | +that has built it. For example, given the following input: |
| 35 | + |
| 36 | +kustomization.yaml |
| 37 | +```yaml |
| 38 | +apiVersion: kustomize.config.k8s.io/v1beta1 |
| 39 | +kind: Kustomization |
| 40 | +resources: |
| 41 | +- service.yaml |
| 42 | +buildMetadata: [managedByLabel] |
| 43 | +``` |
| 44 | + |
| 45 | +service.yaml |
| 46 | +```yaml |
| 47 | +apiVersion: v1 |
| 48 | +kind: Service |
| 49 | +metadata: |
| 50 | + name: myService |
| 51 | +spec: |
| 52 | + ports: |
| 53 | + - port: 7002 |
| 54 | +``` |
| 55 | + |
| 56 | +`kustomize build` will produce a resource with an output like the following: |
| 57 | + |
| 58 | +```yaml |
| 59 | +apiVersion: v1 |
| 60 | +kind: Service |
| 61 | +metadata: |
| 62 | + labels: |
| 63 | + app.kubernetes.io/managed-by: kustomize-v4.4.1 |
| 64 | + name: myService |
| 65 | +spec: |
| 66 | + ports: |
| 67 | + - port: 7002 |
| 68 | +``` |
| 69 | + |
| 70 | + |
| 71 | +### Origin Annotation |
| 72 | +To annotate resources with information about their origin, you can specify the `originAnnotations`: |
| 73 | + |
| 74 | +```yaml |
| 75 | +buildMetadata: [originAnnotations] |
| 76 | +``` |
| 77 | + |
| 78 | +When this option is set, generated resources will receive an annotation with key `config.kubernetes.io/origin`, |
| 79 | +containing data about the generator that produced it. If the resource is from the `resources` field, this annotation |
| 80 | +contains data about the file it originated from. |
| 81 | + |
| 82 | +The possible fields of these annotations are: |
| 83 | + |
| 84 | +- `path`: The path to a resource file itself |
| 85 | +- `ref`: If from a remote file or generator, the ref of the repo URL. |
| 86 | +- `repo`: If from a remote file or generator, the repo source |
| 87 | +- `configuredIn`: If a generated resource, the path to the generator config. If a generator is invoked via a field |
| 88 | +in the kustomization file, this would point to the kustomization file itself. |
| 89 | +- `configuredBy`: If a generated resource, the ObjectReference of the generator config. |
| 90 | + |
| 91 | + |
| 92 | +All local file paths are relative to the top-level kustomization, i.e. the kustomization file in the directory upon |
| 93 | +which `kustomize build` was invoked. For example, if someone were to run `kustomize build foo`, all file paths |
| 94 | +in the annotation output would be relative to`foo/kustomization.yaml`. All remote file paths are relative to the root of the |
| 95 | +remote repository. Any fields that are not applicable would be omitted from the final output. |
| 96 | + |
| 97 | +Here is an example of what this would look like: |
| 98 | +```yaml |
| 99 | +config.kubernetes.io/origin: | |
| 100 | + path: path.yaml |
| 101 | + ref: v0.0.0 |
| 102 | + repo: http://github.com/examplerepo |
| 103 | + configuredIn: path/to/generatorconfig |
| 104 | + configuredBy: |
| 105 | + kind: Generator |
| 106 | + apiVersion: builtin |
| 107 | + name: foo |
| 108 | + namespace: default |
| 109 | +``` |
| 110 | + |
| 111 | +#### Examples |
| 112 | + |
| 113 | +##### Resource declared from `resources` |
| 114 | +A kustomization such as the following: |
| 115 | + |
| 116 | +```yaml |
| 117 | +resources: |
| 118 | +- deployment.yaml |
| 119 | +
|
| 120 | +buildMetadata: [originAnnotations] |
| 121 | +``` |
| 122 | + |
| 123 | +would produce a resource with an annotation like the following: |
| 124 | + |
| 125 | +```yaml |
| 126 | +config.kubernetes.io/origin: | |
| 127 | + path: deployment.yaml |
| 128 | +``` |
| 129 | + |
| 130 | +##### Local custom generator |
| 131 | +A kustomization such as the following: |
| 132 | + |
| 133 | +```yaml |
| 134 | +generators: |
| 135 | +- generator.yaml |
| 136 | +
|
| 137 | +buildMetadata: [originAnnotations] |
| 138 | +``` |
| 139 | + |
| 140 | +would produce a resource with an annotation like the following: |
| 141 | + |
| 142 | +```yaml |
| 143 | +config.kubernetes.io/origin: | |
| 144 | + configuredIn: generator.yaml |
| 145 | + configuredBy: |
| 146 | + kind: MyGenerator |
| 147 | + apiVersion: v1 |
| 148 | + name: generator |
| 149 | +``` |
| 150 | + |
| 151 | +##### Remote builtin generator |
| 152 | +We have a top-level kustomization such as the following: |
| 153 | + |
| 154 | +```yaml |
| 155 | +resources: |
| 156 | +- github.com/examplerepo/?ref=v1.0.6 |
| 157 | +
|
| 158 | +buildMetadata: [originAnnotations] |
| 159 | +``` |
| 160 | + |
| 161 | +which uses `github.com/examplerepo/?ref=v1.0.6` as a remote base. This remote base has the following kustomization |
| 162 | +defined in `github.com/examplerepo/kustomization.yaml`: |
| 163 | + |
| 164 | +```yaml |
| 165 | +configMapGenerator: |
| 166 | +- name: my-java-server-env-vars |
| 167 | + literals: |
| 168 | + - JAVA_HOME=/opt/java/jdk |
| 169 | + - JAVA_TOOL_OPTIONS=-agentlib:hprof |
| 170 | +``` |
| 171 | + |
| 172 | +Running `kustomize build` on the top-level kustomization would produce the following output: |
| 173 | + |
| 174 | +```yaml |
| 175 | +apiVersion: v1 |
| 176 | +data: |
| 177 | + JAVA_HOME: /opt/java/jdk |
| 178 | + JAVA_TOOL_OPTIONS: -agentlib:hprof |
| 179 | +kind: ConfigMap |
| 180 | +metadata: |
| 181 | + name: my-java-server-env-vars-44k658k8gk |
| 182 | + annotations: |
| 183 | + config.kubernetes.io/origin: | |
| 184 | + ref: v1.0.6 |
| 185 | + repo: github.com/examplerepo |
| 186 | + configuredIn: kustomization.yaml |
| 187 | + configuredBy: |
| 188 | + kind: ConfigMapGenerator |
| 189 | + apiVersion: builtin |
| 190 | +``` |
| 191 | + |
| 192 | +### Transformer Annotations [Alpha] |
| 193 | + |
| 194 | +To annotate resources with information about the transformers that have acted on them, you can add the |
| 195 | +`transformerAnnotations` option to the `buildMetadata` field of the kustomization: |
| 196 | + |
| 197 | +```yaml |
| 198 | +buildMetadata: [transformerAnnotations] |
| 199 | +``` |
| 200 | + |
| 201 | +When the `transformerAnnotations` option is set, kustomize will add annotations with information about what transformers |
| 202 | +have acted on each resource. Transformers can be invoked either through various fields in the kustomization file |
| 203 | +(e.g. the `replacements` field will invoke the ReplacementTransformer), or through the `transformers` field. |
| 204 | + |
| 205 | +The annotation key for transformer annotations will be `config.kubernetes.io/transformations`, which will contain a list of |
| 206 | +transformer data. The possible fields in each item in this list is identical to the possible fields in `config.kubernetes.io/origin`, |
| 207 | +except that the transformer annotation does not have a `path` field: |
| 208 | + |
| 209 | +The possible fields of these annotations are: |
| 210 | + |
| 211 | +- `path`: The path to a resource file itself |
| 212 | +- `ref`: If from a remote file or generator, the ref of the repo URL. |
| 213 | +- `repo`: If from a remote file or generator, the repo source |
| 214 | +- `configuredIn`: The path to the transformer config. If a transformer is invoked via a field |
| 215 | +in the kustomization file, this would point to the kustomization file itself. |
| 216 | +- `configuredBy`: The ObjectReference of the transformer config. |
| 217 | + |
| 218 | +All local file paths are relative to the top-level kustomization, i.e. the kustomization file in the directory upon |
| 219 | +which `kustomize build` was invoked. For example, if someone were to run `kustomize build foo`, all file paths |
| 220 | +in the annotation output would be relative to`foo/kustomization.yaml`. All remote file paths are relative to the root of the |
| 221 | +remote repository. Any fields that are not applicable would be omitted from the final output. |
| 222 | + |
| 223 | +Here is an example of what this would look like: |
| 224 | +```yaml |
| 225 | +config.kubernetes.io/transformations: | |
| 226 | + - ref: v0.0.0 |
| 227 | + repo: http://github.com/examplerepo |
| 228 | + configuredIn: path/to/transformerconfig |
| 229 | + configuredBy: |
| 230 | + kind: Transformer |
| 231 | + apiVersion: builtin |
| 232 | + name: foo |
| 233 | + namespace: default |
| 234 | +``` |
| 235 | + |
| 236 | + |
| 237 | +While this field is in alpha, it will receive the `alpha` prefix, so you will see the annotation key |
| 238 | +`alpha.config.kubernetes.io/transformations` instead. We are not guaranteeing that the annotation content will be stable during |
| 239 | +alpha, and reserve the right to make changes as we evolve the feature. |
| 240 | + |
| 241 | + |
| 242 | +#### Examples |
| 243 | + |
| 244 | +#### Local custom transformer |
| 245 | +A kustomization such as the following: |
| 246 | + |
| 247 | +```yaml |
| 248 | +transformers: |
| 249 | +- transformer.yaml |
| 250 | +
|
| 251 | +buildMetadata: [transformerAnnotations] |
| 252 | +
|
| 253 | +``` |
| 254 | + |
| 255 | +would produce a resource with an annotation like the following: |
| 256 | + |
| 257 | +```yaml |
| 258 | +config.kubernetes.io/transformations: | |
| 259 | +- configuredIn: transformer.yaml |
| 260 | + configuredBy: |
| 261 | + kind: MyTransformer |
| 262 | + apiVersion: v1 |
| 263 | + name: transformer |
| 264 | +``` |
| 265 | + |
| 266 | +##### Remote builtin transformer + local builtin transformer |
| 267 | +We have a top-level kustomization such as the following: |
| 268 | + |
| 269 | +```yaml |
| 270 | +resources: |
| 271 | +- github.com/examplerepo/?ref=v1.0.6 |
| 272 | +
|
| 273 | +buildMetadata: [transformerAnnotations] |
| 274 | +
|
| 275 | +namespace: my-ns |
| 276 | +``` |
| 277 | + |
| 278 | +which uses `github.com/examplerepo/?ref=v1.0.6` as a remote base. This remote base has the following kustomization |
| 279 | +defined in `github.com/examplerepo/kustomization.yaml`: |
| 280 | + |
| 281 | +```yaml |
| 282 | +resources: |
| 283 | +- deployment.yaml |
| 284 | +
|
| 285 | +namePrefix: pre- |
| 286 | +``` |
| 287 | + |
| 288 | +`deployment.yaml` contains the following: |
| 289 | + |
| 290 | +```yaml |
| 291 | +apiVersion: v1 |
| 292 | +kind: Deployment |
| 293 | +metadata: |
| 294 | + name: deploy |
| 295 | +``` |
| 296 | + |
| 297 | +Running `kustomize build` on the top-level kustomization would produce the following output: |
| 298 | + |
| 299 | +```yaml |
| 300 | +apiVersion: v1 |
| 301 | +kind: Deployment |
| 302 | +metadata: |
| 303 | + name: pre-deploy |
| 304 | + annotations: |
| 305 | + config.kubernetes.io/transformations: | |
| 306 | + - ref: v1.0.6 |
| 307 | + repo: github.com/examplerepo |
| 308 | + configuredIn: kustomization.yaml |
| 309 | + configuredBy: |
| 310 | + kind: PrefixSuffixTransformer |
| 311 | + apiVersion: builtin |
| 312 | + - configuredIn: kustomization.yaml |
| 313 | + configuredBy: |
| 314 | + kind: NamespaceTransformer |
| 315 | + apiVersion: builtin |
| 316 | +``` |
0 commit comments