Feature Request: Support Downward API

[dgerd]

In what area(s)?

/area API

/area autoscale
/area build
/area monitoring
/area networking
/area test-and-release

Describe the feature

There are many use-cases for knowing information about a particular revision from within the user container. In Knative today we supply a subset of information through automatically injected environment variables such as K_REVISION, K_SERVICE, and K_CONFIGURATION. However, there are two problems with this:

1. This information is incomplete. Other useful information such as the ServiceAccountName and Kubernetes namespace are not present which can be useful for constructing requests to relevant services within the same cluster.
2. The prefixed environment variables does not easily allow for local development and portability to run on non-Knative platforms. The meaning of a revision or a namespace may change in my local environment, but having a concept provided to my container may be important. For example, in my log output I may want to provide a prefix as to the version I am running to help with debugging. In a Knative I may want to use the Revision name for this purpose, but doing local development I may want the git hash for this purpose as I do not have a Revision name. It would be nice to be able to take this in as "VERSION" in my application rather than "K_REVISION" everywhere I run this container.

Kubernetes gets around this problem by providing the downward API. The downward API is typically available through files (via projected volume mount) or through environment variables (via fieldRef). The problem with the downward API for Knative is that:

1. The downward API does not know about Knative so concepts like Service, Revision, and Configuration are not exposed through it
2. Some (but not all) of the fields exposed through the Downward API are outside of the Knative API and it leaks implementation details (which may change). For example, Knative does not expose the Pod object through the API. The naming of Pods and lifecycle of Pods are implementation details of Knative. However, the downward API exposes the Pod name through metadata.name. Applications that use this field would be relying on a detail that may not be portable through all versions or implementations of Knative, and may inadvertently break.

Some fields that are likely valuable:

• metadata.name - While the Pod name is (1) likely not what a user wants and (2) outside the Knative API, having a unique way to address a running instance of the application is valuable.
• metadata.namespace - Useful for calling the Knative or Kubernetes API for discovery, creation, or modification of resources.
• metadata.labels - However, getting the Revision label is likely the right thing to do here as that is where the user would be requesting this from.
• metadata.annotations - However, getting the Revision annotations is likely the right thing to do here as that is where the user would be requesting this from.
• resourceFieldRef - This is also made available through cgroup mounts today.
• spec.serviceAccountName - Useful for making calls with the service account assigned to you.

There are many ways which we could proceed here and it is not clear which way will cover the most use-cases without breaking the serverless abstraction. This issue is created to gather use-cases and discuss proposals.

Some things we could do here:

1. Expand K_* environment variable space to be larger and include more
2. Override meaning of fieldRef from Kubernetes Pod Spec. Provide additional acceptable values, block non-supported values, and translate this in our controller when creating a deployment.
3. Create a new fieldRef-like shape in our API that supports only the fields we want. This would live above the PodSpec as to not override existing behavior.

[dgerd]

Related to: #3090

[vtereso]

Just to reinforce the need for some of these likely valuable fields, Knative eventing creates webhooks, which are namespace scoped so this variable needs to be injected in some manner.

[mattmoor]

We should also discuss how this pertains to projected volumes: #4079

[dgerd]

labels and annotations can change and will get updated on a volume mounted.

[dgerd]

Discussed in the API WG this week. Some of my take aways:

1. Going to cross out option 1 of expanding the always set env vars to include more Knative values as well as Kubernetes values. It seems less preferable to the other two options.
2. We should prefer to not override semantics of existing K8s keys in the field.
3. We have no good volume mount solution today for Knative-specific keys. A flex volume type of thing may be possible, but requires installation across cluster.

I will flush out a bit further what Introducing a new field or introducing a knative namespace into the existing key space looks like.