From f4e6816338c73a8c6dfec0d59ff7b75203be2a0b Mon Sep 17 00:00:00 2001 From: Frank Farzan Date: Tue, 13 Jul 2021 11:58:00 -0700 Subject: [PATCH] Expand documentation of annotations used in manifests and KRM functions API (#3995) * 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]: https://github.com/kubernetes-sigs/kustomize/blob/7e8ba62e9fd9c9b9635598008b933f30f988452f/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 * Update cmd/config/docs/api-conventions/functions-spec.md Co-authored-by: Katrina Verey * Update cmd/config/docs/api-conventions/manifest-annotations.md Co-authored-by: Katrina Verey * Remove kusotmization as example Co-authored-by: Katrina Verey --- .../docs/api-conventions/functions-spec.md | 32 ++++++++++--------- .../api-conventions/manifest-annotations.md | 11 +++++++ 2 files changed, 28 insertions(+), 15 deletions(-) create mode 100644 cmd/config/docs/api-conventions/manifest-annotations.md diff --git a/cmd/config/docs/api-conventions/functions-spec.md b/cmd/config/docs/api-conventions/functions-spec.md index 5fc62d2dd..6f14f004a 100644 --- a/cmd/config/docs/api-conventions/functions-spec.md +++ b/cmd/config/docs/api-conventions/functions-spec.md @@ -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 functions. -### Annotations +### Internal Annotations -The orchestrator annotates resources in the wire format with annotation prefix -`config.kubernetes.io`. These annotations are not persisted when the -orchestrator writes the resources to the filesystem. The orchestrator sets this -annotation when reading files from the local filesystem and removes the -annotation when writing the output of functions back to the filesystem. +For orchestration purposes, the orchestrator will use a set of annotations, +referred to as _internal annotations_, on resources in `Resources.items`. These +annotations are not persisted to resource manifests on the filesystem: The +orchestrator sets this annotation when reading files from the local 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 -explicitly listed below. +Annotation prefix `internal.config.kubernetes.io` is reserved for use for +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 path is relative to a fix location on the filesystem. Different orchestrator implementations can choose different fixed points. -A function SHOULD NOT modify this annotation. +A function SHOULD NOT modify these annotations. Example: ```yaml metadata: 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 are separated by three dashes (`---`), and the index represents the position of the Resource starting from zero. When this annotation is not specified, it implies a value of `0`. -A function SHOULD NOT modify this annotation. +A function SHOULD NOT modify these annotations. Example: ```yaml metadata: annotations: - config.kubernetes.io/path: "relative/file/path.yaml" - config.kubernetes.io/index: 2 + internal.config.kubernetes.io/path: "relative/file/path.yaml" + internal.config.kubernetes.io/index: 2 ``` This represents the third resource in the file. diff --git a/cmd/config/docs/api-conventions/manifest-annotations.md b/cmd/config/docs/api-conventions/manifest-annotations.md new file mode 100644 index 000000000..ee88c6714 --- /dev/null +++ b/cmd/config/docs/api-conventions/manifest-annotations.md @@ -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.