Downward API EnvVar and VolFiles contain differing information, could use more examples

[gamefiend]

Is this a request for help? (If yes, you should use our troubleshooting guide and community support channels, see http://kubernetes.io/docs/troubleshooting/.): No

What keywords did you search in Kubernetes issues before filing this one? (If you have found any duplicates, you should instead reply there.): downward api

---

Is this a BUG REPORT or FEATURE REQUEST? (choose one): FEATURE REQUEST (sort of?)

Kubernetes version (use kubectl version):
Client Version: version.Info{Major:"1", Minor:"5", GitVersion:"v1.5.3", GitCommit:"029c3a408176b55c30846f0faedf56aae5992e9b", GitTreeState:"clean", BuildDate:"2017-02-22T10:12:27Z", GoVersion:"go1.8", Compiler:"gc", Platform:"darwin/amd64"}

Server Version: version.Info{Major:"1", Minor:"5", GitVersion:"v1.5.3", GitCommit:"029c3a408176b55c30846f0faedf56aae5992e9b", GitTreeState:"clean", BuildDate:"1970-01-01T00:00:00Z", GoVersion:"go1.7.3", Compiler:"gc", Platform:"linux/amd64"}

What happened:

The documentation on the DownwardAPI explains how to retrieve information, but does not state that most data is exclusive for each method of exposing data.

Node Name I have only been able to pull using envvars. To try 'spec.nodeName' as VolFile creates this error:

spec.volumes[0].downwardAPI.fieldRef.fieldPath: Unsupported value: "spec.nodeName": supported values: metadata.annotations, metadata.labels, metadata.name, metadata.namespace

From my testing, the following appears true:

Either method can get:

• metadata.name
• metadata.namespace
• limits.cpu
• limits.memory
• requests.cpu
• requests.memory

DAPI VolFiles can retrieve:

• metadata.annotations
• metadata.labels

EnvVars can get:

• spec.nodeName
• spec.serviceAccountName
• status.podIP

The documentation currently doesn't describe this, and it seems like it should. It took me some time and digging to determine these differences, which I hadn't expected.

The documentation as it stands makes it seem the two methods are mostly interchangeable in terms of data. Even the text provided on "Exposing Pod Information to Containers Using a DownwardAPIVolFile" includes the information at the end, only mentioning what is exclusive to the DAPI VolFile and not what's exclusive to EnvVar:

The following information is available to Containers through environment variables and DownwardAPIVolumeFiles:
The node’s name
The Pod’s name
The Pod’s namespace
The Pod’s IP address
The Pod’s service account name
A Container’s CPU limit
A container’s CPU request
A Container’s memory limit
A Container’s memory request
In addition, the following information is available through DownwardAPIVolumeFiles.
The Pod’s labels
The Pod’s annotations

The corresponding doc emphasizing the EnvVar approach, "Exposing Pod Information to Containers Through Environment Variables"

While it would be great to have both methods return the same data, this issue exists because I'm volunteering to flesh out the documentation (hopefully saving people some time digging) and to get confirmation that:

• It's OK to make the changes to the documentation
• My understanding of the dapi is correct; is there a way to reference some of this data that I am missing?

Again, whether the data should exist or not in certain places is not my issue; right now I simply want to document how it currently is to clear up confusion (and maybe the confusion is mine!)

[gamefiend]

Will close the issue as the main work is completed.

[gamefiend]

Reopening this as I closed it in error. Will release PR with suggested fixes for this soon.

[xiangpengzhao]

/sig api-machinery

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

Prevent issues from auto-closing with an /lifecycle frozen comment.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or @fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten
/remove-lifecycle stale

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

[apatil]

I repro this on 1.8.1.

[zyf0330]

I use downwardAPI like this

- name: MY_NODE_ACCESSIP
          valueFrom:
            fieldRef:
              fieldPath: metadata.labels['accessIP']

And in container I get $MY_NODE_ACCESSIP with null value.
I have set label accessIP in node.

[washingtoneg]

For those who wonder here in the future: the downwardAPI doesn't expose node labels, it makes pod labels available. Check out #40610 in which the maintainers consider exposing node labels via downwardAPI to see if/when that functionality will be available in the future.

[stojan-jovic]

Some strange behavior regarding exposing labels through the ENV variables (reproduced with CronJob) - if I do the following:

- name: TEST_VAR
  valueFrom:
    fieldRef:
      fieldPath: metadata.labels['job-name']

When I describe my Pod (with kubectl) I would expect to see:

Environment:
  ...
  TEST_VAR:               test-cronjob-1544705040 (v1:metadata.labels['job-name'])
  ...

But, what I really get is:

Environment:
  ...
  TEST_VAR:                (v1:metadata.labels['job-name'])
  ...

So, it seems like it's not working, but when I read TEST_VAR inside my container, everything is fne, i.e. I'm getting test-cronjob-1544705040?!

It's kind a bug, I think. Be aware of this behavior, because I spent hour or two to figure out that it's actually working (even it seems that's not working).

My cluster info:

Client Version: version.Info{Major:"1", Minor:"10", GitVersion:"v1.10.1", GitCommit:"d4ab47518836c750f9949b9e0d387f20fb92260b", GitTreeState:"clean", BuildDate: "2018-04-12T14:26:04Z", GoVersion:"go1.9.3", Compiler:"gc", Platform:"linux/amd64"}
Server Version: version.Info{Major:"1", Minor:"10", GitVersion:"v1.10.7", GitCommit:"0c38c362511b20a098d7cd855f1314dad92c2780", GitTreeState:"clean", BuildDate: "2018-08-20T09:56:31Z", GoVersion:"go1.9.3", Compiler:"gc", Platform:"linux/amd64"}