New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Revise downward API documentation #32400

Merged

k8s-ci-robot merged 1 commit into kubernetes:main from sftim:20220321_document_downward_api_concept

Jun 17, 2022

Contributor

sftim commented Mar 21, 2022 •

edited

Loading

add a glossary entry
add a concept page (helps with Document downward API as concept #14579)
revise other documentation in light of above changes

Before	After
not applicable	Downward API concept
Expose Pod Information to Containers Through Environment Variables	Expose Pod Information to Containers Through Environment Variables task
Expose Pod Information to Containers Through Files	Expose Pod Information to Containers Through Files task
`downwardAPI` volumes	`downwardAPI` volumes

/label refactor
/kind cleanup

k8s-ci-robot added kind/cleanup refactor cncf-cla: yes size/L labels

k8s-ci-robot requested review from bradtopol and thockin

March 21, 2022 22:33

k8s-ci-robot added language/en sig/docs labels

netlify bot commented Mar 21, 2022 •

edited

Loading

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`7f3604a`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-main-staging/deploys/628f7212b89481000787f577
😎 Deploy Preview	https://deploy-preview-32400--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

tengqm reviewed

View reviewed changes

content/en/docs/concepts/workloads/pods/downward-api.md

+              title: Downward API
+              content_type: concept
+              description: >
+                There are two ways to expose Pod and container fields to a running container:

Contributor

tengqm Mar 22, 2022

In this context, I'd write the first 'container' as 'Container'.
A Container has fields, but a container doesn't.

Contributor Author

sftim Mar 23, 2022

In the API, Container with a capital C doesn't appear. We do see that in the Golang implementation, but not in the API (where it's actually containers).

Contributor

tengqm Mar 23, 2022

They are API definitions, though not first class API resources.

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#container-v1-core
https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#Container

Contributor Author

sftim Mar 23, 2022

I'm going to look for a way to word this so that people don't start trying to kubectl get container and expect it to work, but also that readers end up clear on the two kinds of thing they can reference using the downward API.

content/en/docs/concepts/workloads/pods/downward-api.md Outdated


		### Fallback information for resource limits

		{{< note >}}

Contributor

tengqm Mar 22, 2022

I don't think it is a good practice to render a whole subsection into a note.

content/en/docs/reference/glossary/downward-api.md Outdated

+              The Kubernetes downward API allows containers to consume information about themselves
+              or their context in a Kubernetes cluster. Applications in containers can have
+              access to that information, without the application needing to act as a client of
+              the Kubernetes HTTP API.

Contributor

tengqm Mar 22, 2022

Suggested change

      
            the Kubernetes HTTP API.
          
            the Kubernetes API.

content/en/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information.md

    
              A `DownwardAPIVolumeFile` can expose Pod fields and Container fields.

              [`downwardAPI` volume](/docs/concepts/storage/volumes/#downwardapi),

              to expose information about itself to containers running in the Pod.

              A `downwardAPI` volume can expose Pod fields and container fields.

Contributor

tengqm Mar 22, 2022

Suggested change

      
            A `downwardAPI` volume can expose Pod fields and container fields.
          
            A `downwardAPI` volume can expose Pod fields and Container fields.

content/en/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information.md


		## {{% heading "prerequisites" %}}
		In Kubernetes, there are two ways to expose Pod and container fields to a running container:

Contributor

tengqm Mar 22, 2022

Suggested change

      
            In Kubernetes, there are two ways to expose Pod and container fields to a running container:
          
            In Kubernetes, there are two ways to expose Pod and Container fields to a running container:

content/en/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information.md

               The first element specifies that the value of the Pod's
               `metadata.labels` field should be stored in a file named `labels`.
               The second element specifies that the value of the Pod's `annotations`
               field should be stored in a file named `annotations`.
               {{< note >}}
               The fields in this example are Pod fields. They are not
-              fields of the Container in the Pod.
+              fields of the container in the Pod.

Contributor

tengqm Mar 22, 2022

Suggested change

      
            fields of the container in the Pod.
          
            fields of the Container in the Pod.

content/en/docs/concepts/workloads/pods/downward-api.md Outdated Show resolved Hide resolved

content/en/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information.md Outdated

-              or API server.
+              * Read the [`spec`](/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec)
+                API definition for Pod.
+                In Kubernetes, you use a `spec` to define the desired state of an object.

Contributor

tengqm Mar 22, 2022

This line is useless, IMO.

content/en/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information.md Outdated

+              * Read the [`spec`](/docs/reference/kubernetes-api/workload-resources/pod-v1/#PodSpec)
+                API definition for Pod.
+                In Kubernetes, you use a `spec` to define the desired state of an object.
+              * Read some [examples](/docs/concepts/workloads/pods/downward-api/#data-examples) of fields that you

Contributor

tengqm Mar 22, 2022

No. They are not examples. The list contains all the fields that can be exposed.

content/en/docs/tasks/inject-data-application/environment-variable-expose-pod-information.md Outdated

               67108864
               ```
+              ## Motivation for the Downward API

Contributor

tengqm Mar 22, 2022

I don't think this section belongs here, at the end of a task.

sftim force-pushed the 20220321_document_downward_api_concept branch from d8779d9 to 62fd82d Compare

March 23, 2022 18:02

sftim marked this pull request as draft

March 23, 2022 18:02

k8s-ci-robot added the do-not-merge/work-in-progress label

sftim force-pushed the 20220321_document_downward_api_concept branch 3 times, most recently from 113d17f to 85b6d85 Compare

March 25, 2022 00:52

sftim marked this pull request as ready for review

March 25, 2022 00:53

k8s-ci-robot removed the do-not-merge/work-in-progress label

k8s-ci-robot requested a review from saad-ali

March 25, 2022 00:54

Contributor Author

sftim commented Mar 25, 2022

How's this? I added text to explicitly explain that a Pod must include one Container.

k8s-ci-robot requested a review from zacharysarah

March 25, 2022 00:54

sftim force-pushed the 20220321_document_downward_api_concept branch from 85b6d85 to 154ac66 Compare

April 10, 2022 22:56

Contributor Author

sftim commented Apr 20, 2022

@tengqm if you have time, please take another look here.

Contributor

tengqm commented Apr 20, 2022

/lgtm

k8s-ci-robot assigned tengqm

k8s-ci-robot added the lgtm label

Contributor

k8s-ci-robot commented Apr 20, 2022

LGTM label has been added.

Git tree hash: f2fb40db71465fb5ec16d461bf7ab90c517d6cf3

k8s-ci-robot added the needs-rebase label


          Revise downward API documentation

7f3604a

- add a glossary entry
- add a concept page
- revise other documentation in light of above changes

sftim force-pushed the 20220321_document_downward_api_concept branch from 154ac66 to 7f3604a Compare

May 26, 2022 12:26

k8s-ci-robot removed the lgtm label

k8s-ci-robot requested a review from tengqm

May 26, 2022 12:26

k8s-ci-robot removed the needs-rebase label

Contributor Author

sftim commented May 26, 2022

Hi folks, this is ready for another review (I rebased).

zacharysarah approved these changes

View reviewed changes

Contributor

zacharysarah left a comment

@sftim Nonblocking nits, otherwise LGTM

content/en/docs/concepts/workloads/pods/downward-api.md

Comment on lines +122 to +123

		(based on the [node allocatable](/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable)
		calculation).

Contributor

zacharysarah Jun 17, 2022

No parentheses needed

Suggested change

      
            (based on the [node allocatable](/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable)
          
            calculation).
          
            based on the [node allocatable](/docs/tasks/administer-cluster/reserve-compute-resources/#node-allocatable)
          
            calculation.

content/en/docs/concepts/workloads/pods/downward-api.md

+              An example is an existing application that assumes a particular well-known
+              environment variable holds a unique identifier. One possibility is to wrap the
+              application, but that is tedious and error prone, and it violates the goal of low

Contributor

zacharysarah Jun 17, 2022

Normally I am treasurer for life of the I Hate Hyphens club, but for the sake of easier localization--

Suggested change

      
            application, but that is tedious and error prone, and it violates the goal of low
          
            application, but that is tedious and error-prone, and it violates the goal of low

Contributor

k8s-ci-robot commented Jun 17, 2022

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: zacharysarah

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~content/en/OWNERS~~ [zacharysarah]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot added the approved label

Contributor

zacharysarah commented Jun 17, 2022

/lgtm

k8s-ci-robot assigned zacharysarah

k8s-ci-robot added the lgtm label

Contributor

k8s-ci-robot commented Jun 17, 2022

LGTM label has been added.

Git tree hash: e712e1299000b2685d87d695b396a9b1ff4b38cd

k8s-ci-robot merged commit 3a0d817 into kubernetes:main

sftim deleted the 20220321_document_downward_api_concept branch

June 20, 2022 11:59

sftim mentioned this pull request

Downward API concept has poor hyphenation, harming localization #34421

Closed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

zacharysarah zacharysarah approved these changes

bradtopol Awaiting requested review from bradtopol

thockin Awaiting requested review from thockin

saad-ali Awaiting requested review from saad-ali

tengqm Awaiting requested review from tengqm

Labels

approved cncf-cla: yes kind/cleanup language/en lgtm refactor sig/docs size/L