Expand documentation of annotations used in manifests and KRM functio…

…ns 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]: #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>

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.

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.