mirror of https://github.com/k3s-io/k3s
78 lines
2.7 KiB
Markdown
78 lines
2.7 KiB
Markdown
# Downward API
|
|
|
|
It is sometimes useful for a container to have information about itself, but we
|
|
want to be careful not to over-couple containers to Kubernetes. The downward
|
|
API allows containers to consume information about themselves or the system and
|
|
expose that information how they want it, without necessarily coupling to the
|
|
kubernetes client or REST API.
|
|
|
|
An example of this is a "legacy" app that is already written assuming
|
|
that a particular environment variable will hold a unique identifier. While it
|
|
is often possible to "wrap" such applications, this is tedious and error prone,
|
|
and violates the goal of low coupling. Instead, the user should be able to use
|
|
the Pod's name, for example, and inject it into this well-known variable.
|
|
|
|
## Capabilities
|
|
|
|
The following information is available to a `Pod` through the the downward API:
|
|
|
|
* The pod's name
|
|
* The pod's namespace
|
|
|
|
More information will be exposed through this same API over time.
|
|
|
|
## Exposing pod information into a container
|
|
|
|
Containers consume information from the downward API using environment
|
|
variables. In the future, containers will also be able to consume the downward
|
|
API via a volume plugin.
|
|
|
|
### Environment variables
|
|
|
|
Most environment variables in the Kubernetes API use the `value` field to carry
|
|
simple values. However, the alternate `valueFrom` field allows you to specify
|
|
a `fieldRef` to select fields from the pod's definition. The `fieldRef` field
|
|
is a structure that has an `apiVersion` field and a `fieldPath` field. The
|
|
`fieldPath` field is an expression designating a field of the pod. The
|
|
`apiVersion` field is the version of the API schema that the `fieldPath` is
|
|
written in terms of. If the `apiVersion` field is not specified it is
|
|
defaulted to the API version of the enclosing object.
|
|
|
|
The `fieldRef` is evaluated and the resulting value is used as the value for
|
|
the environment variable. This allows users to publish their pod's name in any
|
|
environment variable they want.
|
|
|
|
## Example
|
|
|
|
This is an example of a pod that consumes its name and namespace via the
|
|
downward API:
|
|
|
|
```yaml
|
|
apiVersion: v1
|
|
kind: Pod
|
|
metadata:
|
|
name: dapi-test-pod
|
|
spec:
|
|
containers:
|
|
- name: test-container
|
|
image: gcr.io/google_containers/busybox
|
|
command: [ "/bin/sh", "-c", "env" ]
|
|
env:
|
|
- name: MY_POD_NAME
|
|
valueFrom:
|
|
fieldRef:
|
|
fieldPath: metadata.name
|
|
- name: MY_POD_NAMESPACE
|
|
valueFrom:
|
|
fieldRef:
|
|
fieldPath: metadata.namespace
|
|
restartPolicy: Never
|
|
```
|
|
|
|
Some more thorough examples:
|
|
* [environment variables](../examples/environment-guide/)
|
|
* [downward API](../examples/downward-api/)
|
|
|
|
|
|
[]()
|