kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-06-11 17:12:51 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

Expand documentation of annotations used in manifests and KRM functions API (#3995)

Browse Source 
* Expand documentation of annotations used in manifests and KRM function wire format.

- Reserve `internal.config.kubernetes.io` for control annotations
- Document `local-config` annotation in a seperate document (It's
  orthogonal to KRM functions).
- There is a internal annotation that uses `config.k8s.io` instead of
  `config.kubernetes.io` used by other annotations. See [1] and [2]. We
  should avoid using two seperate annotation prefixes and audit the
  codebase for any other annotation. Given the `id` control annotation is used
  for comment preservation (no existing function should be modifying
  it), I suggest moving this over to use
  `fn-ctrl.config.kubernets.io/id`.

[1]: 7e8ba62e9f/kyaml/fn/runtime/runtimeutil/runtimeutil.go (L195)
[2]: https://github.com/kubernetes-sigs/kustomize/pull/2465

* Move path/index annotation to use internal prefix

* Clarify MUST NOT vs SHOULD NOT for internal annotations

* Update cmd/config/docs/api-conventions/functions-spec.md

Co-authored-by: Katrina Verey <kn.verey@gmail.com>

* Update cmd/config/docs/api-conventions/functions-spec.md

Co-authored-by: Katrina Verey <kn.verey@gmail.com>

* Update cmd/config/docs/api-conventions/manifest-annotations.md

Co-authored-by: Katrina Verey <kn.verey@gmail.com>

* Remove kusotmization as example

Co-authored-by: Katrina Verey <kn.verey@gmail.com>
This commit is contained in:
Frank Farzan
2021-07-13 11:58:00 -07:00
committed by GitHub
parent 4a13725678
commit f4e6816338
2 changed files with 28 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
cmd/config/docs/api-conventions/functions-spec.md
View File

@@ -327,49 +327,51 @@ A function SHOULD preserve comments when input serialization format is YAML.
This allows for human authoring of configuration to coexist with changes made by This allows for human authoring of configuration to coexist with changes made by
functions. functions.
### Annotations ### Internal Annotations
The orchestrator annotates resources in the wire format with annotation prefix For orchestration purposes, the orchestrator will use a set of annotations,
`config.kubernetes.io`. These annotations are not persisted when the referred to as _internal annotations_, on resources in `Resources.items`. These
orchestrator writes the resources to the filesystem. The orchestrator sets this annotations are not persisted to resource manifests on the filesystem: The
annotation when reading files from the local filesystem and removes the orchestrator sets this annotation when reading files from the local filesystem
annotation when writing the output of functions back to the filesystem. and removes the annotation when writing the output of functions back to the
filesystem.
In general, a function MUST NOT modify these annotations except the ones Annotation prefix `internal.config.kubernetes.io` is reserved for use for
explicitly listed below. internal annotations. In general, a function MUST NOT modify these annotations with
the exception of the specific annotations listed below. This enables orchestrators to add additional internal annotations, without requiring changes to existing functions.
#### `config.kubernetes.io/path` #### `internal.config.kubernetes.io/path`
Records the slash-delimited, OS-agnostic, relative file path to a resource. The Records the slash-delimited, OS-agnostic, relative file path to a resource. The
path is relative to a fix location on the filesystem. Different orchestrator path is relative to a fix location on the filesystem. Different orchestrator
implementations can choose different fixed points. implementations can choose different fixed points.
A function SHOULD NOT modify this annotation. A function SHOULD NOT modify these annotations.
Example: Example:
```yaml ```yaml
metadata: metadata:
annotations: annotations:
config.kubernetes.io/path: "relative/file/path.yaml" internal.config.kubernetes.io/path: "relative/file/path.yaml"
``` ```
#### `config.kubernetes.io/index` #### `internal.config.kubernetes.io/index`
Records the index of a Resource in file. In a multi-object YAML file, resources Records the index of a Resource in file. In a multi-object YAML file, resources
are separated by three dashes (`---`), and the index represents the position of are separated by three dashes (`---`), and the index represents the position of
the Resource starting from zero. When this annotation is not specified, it the Resource starting from zero. When this annotation is not specified, it
implies a value of `0`. implies a value of `0`.
A function SHOULD NOT modify this annotation. A function SHOULD NOT modify these annotations.
Example: Example:
```yaml ```yaml
metadata: metadata:
annotations: annotations:
config.kubernetes.io/path: "relative/file/path.yaml" internal.config.kubernetes.io/path: "relative/file/path.yaml"
config.kubernetes.io/index: 2 internal.config.kubernetes.io/index: 2
``` ```
This represents the third resource in the file. This represents the third resource in the file.

11
cmd/config/docs/api-conventions/manifest-annotations.md Normal file
View File

@@ -0,0 +1,11 @@
# Manifest Annotations
This document lists the annotations that can be declared in resource manifests.
### `config.kubernetes.io/local-config`
A value of `"true"` for this annotation declares that the resource is only consumed by
client-side tooling and should not be applied to the API server.
A value of `"false"` can be used to declare that a resource should be applied to
the API server even when it is assumed to be local.