第23章 Downward API

23.1. 概要

Downward API は、OpenShift Container Platform に結合せずにコンテナーが API オブジェクトについての情報を使用できるメカニズムです。この情報には、Pod の名前、namespace およびリソース値が含まれます。コンテナーは、環境変数またはボリュームプラグインを使用して Downward API から情報を使用できます。

23.2. フィールドの選択

Pod 内のフィールドは、FieldRef API タイプを使用して選択されます。FieldRef には 2 つのフィールドが含まれます。

フィールド	説明
`fieldPath`	Pod に関連して選択するフィールドのパスです。
`apiVersion`	`fieldPath` セレクターの解釈に使用する API バージョンです。

現時点で v1 API の有効なセレクターには以下が含まれます。

セレクター	説明
`metadata.name`	Pod の名前です。これは環境変数およびボリュームでサポートされています。
`metadata.namespace`	Pod の namespace です。これは環境変数およびボリュームでサポートされています。
`metadata.labels`	Pod のラベルです。これはボリュームでのみサポートされ、環境変数ではサポートされていません。
`metadata.annotations`	Pod のアノテーションです。これはボリュームでのみサポートされ、環境変数ではサポートされていません。
`status.podIP`	Pod の IP です。これは環境変数でのみサポートされ、ボリュームではサポートされていません。

apiVersion フィールドです。指定されていない場合は、対象の Pod テンプレートの API バージョンにデフォルト設定されます。

23.3. Downward API を使用したコンテナー値の使用

23.3.1. 環境変数の使用

Downward API を使用するための 1 つのメカニズムとして、コンテナーの環境変数を使用することができます。EnvVar タイプの valueFrom フィールド (タイプは EnvVarSource)は、変数の値が value フィールドで指定されるリテラル値ではなく、FieldRef ソースからの値になるように指定するために使用されます。今後は追加のソースがサポートされる可能性があります。現時点では、ソースの fieldRef フィールドは Downward API からフィールドを選択するために使用されます。

この方法で使用できるのは Pod の定数属性のみです。変数の値の変更についてプロセスに通知する方法でプロセスを起動すると、環境変数を更新できなくなるためです。環境変数を使用してサポートされるフィールドには、以下が含まれます。

Pod の名前

Pod の namespace

pod.yaml ファイルを作成します。

apiVersion: v1
kind: Pod
metadata:
  name: dapi-env-test-pod
spec:
  containers:
    - name: env-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

pod.yaml ファイルから Pod を作成します。
```
$ oc create -f pod.yaml
```
コンテナーのログで MY_POD_NAME および MY_POD_NAMESPACE の値を確認します。
```
$ oc logs -p dapi-env-test-pod
```

23.3.2. ボリュームプラグインの使用

Downward API を使用するもう 1 つのメカニズムとしてボリュームプラグインを使用することができます。Downward API ボリュームプラグインは、ファイルに展開される設定済みのフィールドを使ってボリュームを作成します。VolumeSource API オブジェクトの metadata フィールドはこのボリュームを設定するために使用されます。プラグインは以下のフィールドをサポートします。

Pod の名前
Pod の namespace
Pod のアノテーション
Pod のラベル

例23.1 Downward API ボリュームプラグイン設定

spec:
  volumes:
    - name: podinfo
      downwardAPI:: 1
        items: 2
          -name: "labels" 3
           fieldRef:
              fieldPath: metadata.labels 4

1: ボリュームソースの metadata フィールドは Downward API ボリュームを設定します。
2: items フィールドはボリュームに展開するフィールドの一覧を保持します。
3: フィールドを展開するファイルの名前です。
4: 展開するフィールドのセレクターです。

以下に例を示します。

volume-pod.yaml ファイルを作成します。

kind: Pod
apiVersion: v1
metadata:
  labels:
    zone: us-east-coast
    cluster: downward-api-test-cluster1
    rack: rack-123
  name: dapi-volume-test-pod
  annotations:
    annotation1: "345"
    annotation2: "456"
spec:
  containers:
    - name: volume-test-container
      image: gcr.io/google_containers/busybox
      command: ["sh", "-c", "cat /tmp/etc/pod_labels /tmp/etc/pod_annotations"]
      volumeMounts:
        - name: podinfo
          mountPath: /tmp/etc
          readOnly: false
  volumes:
  - name: podinfo
    downwardAPI:
      defaultMode: 420
      items:
      - fieldRef:
          fieldPath: metadata.name
        path: pod_name
      - fieldRef:
          fieldPath: metadata.namespace
        path: pod_namespace
      - fieldRef:
          fieldPath: metadata.labels
        path: pod_labels
      - fieldRef:
          fieldPath: metadata.annotations
        path: pod_annotations
  restartPolicy: Never

volume-pod.yaml ファイルから Pod を作成します。
```
$ oc create -f volume-pod.yaml
```

コンテナーのログを確認し、設定されたフィールドの有無を確認します。

$ oc logs -p dapi-volume-test-pod
cluster=downward-api-test-cluster1
rack=rack-123
zone=us-east-coast
annotation1=345
annotation2=456
kubernetes.io/config.source=api

23.4. Downward API を使用したコンテナーリソースの使用

Pod の作成時に、Downward API を使用してコンピューティングリソースの要求および制限についての情報を挿入し、イメージおよびアプリケーションの作成者が特定の環境用のイメージを適切に作成できるようにします。

これは、環境変数およびボリュームプラグインのいずれの方法で実行できます。

23.4.1. 環境変数の使用

Pod 設定の作成時に、spec.container フィールド内の resources フィールドの内容に対応する環境変数を指定します。

....
spec:
  containers:
    - name: test-container
      image: gcr.io/google_containers/busybox:1.24
      command: [ "/bin/sh", "-c", "env" ]
      resources:
        requests:
          memory: "32Mi"
          cpu: "125m"
        limits:
          memory: "64Mi"
          cpu: "250m"
      env:
        - name: MY_CPU_REQUEST
          valueFrom:
            resourceFieldRef:
              resource: requests.cpu
        - name: MY_CPU_LIMIT
          valueFrom:
            resourceFieldRef:
              resource: limits.cpu
        - name: MY_MEM_REQUEST
          valueFrom:
            resourceFieldRef:
              resource: requests.memory
        - name: MY_MEM_LIMIT
          valueFrom:
            resourceFieldRef:
              resource: limits.memory
....

リソース制限がコンテナー設定に含まれていない場合、Downward API はデフォルトでノードの CPU およびメモリーの割り当て可能な値に設定されます。

pod.yaml ファイルから Pod を作成します。
```
$ oc create -f pod.yaml
```

23.4.2. ボリュームプラグインの使用

Pod 設定の作成時に、spec.volumes.downwardAPI.items フィールドを使用して spec.resources フィールドに対応する必要なリソースを記述します。

....
spec:
  containers:
    - name: client-container
      image: gcr.io/google_containers/busybox:1.24
      command: ["sh", "-c", "while true; do echo; if [[ -e /etc/cpu_limit ]]; then cat /etc/cpu_limit; fi; if [[ -e /etc/cpu_request ]]; then cat /etc/cpu_request; fi; if [[ -e /etc/mem_limit ]]; then cat /etc/mem_limit; fi; if [[ -e /etc/mem_request ]]; then cat /etc/mem_request; fi; sleep 5; done"]
      resources:
        requests:
          memory: "32Mi"
          cpu: "125m"
        limits:
          memory: "64Mi"
          cpu: "250m"
      volumeMounts:
        - name: podinfo
          mountPath: /etc
          readOnly: false
  volumes:
    - name: podinfo
      downwardAPI:
        items:
          - path: "cpu_limit"
            resourceFieldRef:
              containerName: client-container
              resource: limits.cpu
          - path: "cpu_request"
            resourceFieldRef:
              containerName: client-container
              resource: requests.cpu
          - path: "mem_limit"
            resourceFieldRef:
              containerName: client-container
              resource: limits.memory
          - path: "mem_request"
            resourceFieldRef:
              containerName: client-container
              resource: requests.memory
....

リソース制限がコンテナー設定に含まれていない場合、Downward API はデフォルトでノードの CPU およびメモリーの割り当て可能な値に設定されます。

volume-pod.yaml ファイルから Pod を作成します。
```
$ oc create -f volume-pod.yaml
```

23.5. Downward API を使用したシークレットの使用

Pod の作成時に、Downward API を使用してシークレットを挿入し、イメージおよびアプリケーションの作成者が特定の環境用のイメージを作成できるようにできます。

23.5.1. 環境変数の使用

secret.yaml ファイルを作成します。

apiVersion: v1
kind: Secret
metadata:
  name: mysecret
data:
  password: cGFzc3dvcmQ=
  username: ZGV2ZWxvcGVy
type: kubernetes.io/basic-auth

secret.yaml ファイルから Secret を作成します。
```
oc create -f secret.yaml
```

上記の Secret から username フィールドを参照する pod.yaml ファイルを作成します。

apiVersion: v1
kind: Pod
metadata:
  name: dapi-env-test-pod
spec:
  containers:
    - name: env-test-container
      image: gcr.io/google_containers/busybox
      command: [ "/bin/sh", "-c", "env" ]
      env:
        - name: MY_SECRET_USERNAME
          valueFrom:
            secretKeyRef:
              name: mysecret
              key: username
  restartPolicy: Never

pod.yaml ファイルから Pod を作成します。
```
$ oc create -f pod.yaml
```
コンテナーのログで MY_SECRET_USERNAME の値を確認します。
```
$ oc logs -p dapi-env-test-pod
```

23.6. Downward API を使用した ConfigMap の使用

Pod の作成時に、Downward API を使用して ConfigMap 値を挿入し、イメージおよびアプリケーションの作成者が特定の環境用のイメージを作成することができます。

23.6.1. 環境変数の使用

configmap.yaml ファイルを作成します。

apiVersion: v1
kind: ConfigMap
metadata:
  name: myconfigmap
data:
  mykey: myvalue

configmap.yaml ファイルから ConfigMap を作成します。
```
oc create -f configmap.yaml
```

上記の ConfigMap を参照する pod.yaml ファイルを作成します。

apiVersion: v1
kind: Pod
metadata:
  name: dapi-env-test-pod
spec:
  containers:
    - name: env-test-container
      image: gcr.io/google_containers/busybox
      command: [ "/bin/sh", "-c", "env" ]
      env:
        - name: MY_CONFIGMAP_VALUE
          valueFrom:
            configMapKeyRef:
              name: myconfigmap
              key: mykey
  restartPolicy: Never

pod.yaml ファイルから Pod を作成します。
```
$ oc create -f pod.yaml
```
コンテナーのログで MY_CONFIGMAP_VALUE の値を確認します。
```
$ oc logs -p dapi-env-test-pod
```

23.7. 環境変数の参照

Pod の作成時に、$() 構文を使用して事前に定義された環境変数の値を参照できます。環境変数の参照が解決されない場合、値は提供された文字列のままになります。

23.7.1. 環境変数の参照の使用

既存の environment variable を参照する pod.yaml ファイルを作成します。

apiVersion: v1
kind: Pod
metadata:
  name: dapi-env-test-pod
spec:
  containers:
    - name: env-test-container
      image: gcr.io/google_containers/busybox
      command: [ "/bin/sh", "-c", "env" ]
      env:
        - name: MY_EXISTING_ENV
          value: my_value
        - name: MY_ENV_VAR_REF_ENV
          value: $(MY_EXISTING_ENV)
  restartPolicy: Never

pod.yaml ファイルから Pod を作成します。
```
$ oc create -f pod.yaml
```
コンテナーのログで MY_ENV_VAR_REF_ENV 値を確認します。
```
$ oc logs -p dapi-env-test-pod
```

23.7.2. 環境変数の参照のエスケープ

Pod の作成時に、二重ドル記号を使用して環境変数の参照をエスケープできます。次に値は指定された値の単一ドル記号のバージョンに設定されます。