proposal: Expose single annotations via downward API

Moved from kubernetes/kubernetes#36058

Ref kubernetes/kubernetes#31218

contributors/design-proposals/annotations-downward-api.md

@@ -0,0 +1,67 @@
+# Exposing annotations via environment downward API
+
+Author: Michal Rostecki \<michal@kinvolk.io\>
+
+## Introduction
+
+Annotations of the pod can be taken through the Kubernetes API, but currently
+there is no way to pass them to the application inside the container. This means
+that annotations can be used by the core Kubernetes services and the user outside
+of the Kubernetes cluster.
+
+Of course using Kubernetes API from the application running inside the container
+managed by Kubernetes is technically possible, but that's an idea which denies
+the principles of microservices architecture.
+
+The purpose of the proposal is to allow to pass the annotation as the environment
+variable to the container.
+
+### Use-case
+
+The primary usecase for this proposal are StatefulSets. There is an idea to expose
+StatefulSet index to the applications running inside the pods managed by StatefulSet.
+Since StatefulSet creates pods as the API objects, passing this index as an
+annotation seems to be a valid way to do this. However, to finally pass this
+information to the containerized application, we need to pass this annotation.
+That's why the downward API for annotations is needed here.
+
+## API
+
+The exact `fieldPath` to the annotation will have the following syntax:
+
+```
+metadata.annotations['annotationKey']
+```
+
+Which means that:
+- the *annotationKey* will be specified inside brackets (`[`, `]`) and single quotation
+  marks (`'`)
+- if the *annotationKey* contains `[`, `]` or `'` characters inside, they will need to
+  be escaped (like `\[`, `\]`, `\'`) and having these characters unescaped should result
+  in validation error
+
+Examples:
+- `metadata.annotations['spec.pod.beta.kubernetes.io/statefulset-index']`
+- `metadata.annotations['foo.bar/example-annotation']`
+- `metadata.annotations['foo.bar/more\'complicated\]example\[with\'characters"to-escape']`
+
+So, assuming that we would want to pass the `pod.beta.kubernetes.io/statefulset-index`
+annotation as a `STATEFULSET_INDEX` variable, the environment variable definition
+will look like:
+
+```
+env:
+  - name: STATEFULSET_INDEX
+    valueFrom:
+      fieldRef:
+        fieldPath: metadata.annotations['spec.pod.beta.kubernetes.io/statefulset-index']
+```
+
+## Implementation
+
+In general, this environment downward API part will be implemented in the same
+place as the other metadata - as a label conversion function.
+
+<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
+[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/proposals/annotations-downward-api.md?pixel)]()
+<!-- END MUNGE: GENERATED_ANALYTICS -->