第22章 Downward API

22.1. 概要

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

22.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 バージョンにデフォルト設定されます。

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

22.3.1. 環境変数の使用

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

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

  • Pod の名前
  • Pod の namespace

    1. 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
    2. pod.yaml ファイルから Pod を作成します。

      $ oc create -f pod.yaml
    3. コンテナーのログで MY_POD_NAME および MY_POD_NAMESPACE の値を確認します。

      $ oc logs -p dapi-env-test-pod

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

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

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

例22.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
展開するフィールドのセレクターです。

例:

  1. 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
  2. volume-pod.yaml ファイルから Pod を作成します。

    $ oc create -f volume-pod.yaml
  3. コンテナーのログを確認し、設定されたフィールドの有無を確認します。

    $ 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

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

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

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

22.4.1. 環境変数の使用

  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 およびメモリーの割り当て可能な値に設定されます。

  2. pod.yaml ファイルから Pod を作成します。

    $ oc create -f pod.yaml

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

  1. 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 およびメモリーの割り当て可能な値に設定されます。

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

    $ oc create -f volume-pod.yaml

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

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

22.5.1. 環境変数の使用

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

    apiVersion: v1
    kind: Secret
    metadata:
      name: mysecret
    data:
      password: cGFzc3dvcmQ=
      username: ZGV2ZWxvcGVy
    type: kubernetes.io/basic-auth
  2. secret.yaml ファイルから Secret を作成します。

    oc create -f secret.yaml
  3. 上記の 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
  4. pod.yaml ファイルから Pod を作成します。

    $ oc create -f pod.yaml
  5. コンテナーのログで MY_SECRET_USERNAME の値を確認します。

    $ oc logs -p dapi-env-test-pod

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

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

22.6.1. 環境変数の使用

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

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: myconfigmap
    data:
      mykey: myvalue
  2. configmap.yaml ファイルから ConfigMap を作成します。

    oc create -f configmap.yaml
  3. 上記の 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
  4. pod.yaml ファイルから Pod を作成します。

    $ oc create -f pod.yaml
  5. コンテナーのログで MY_CONFIGMAP_VALUE の値を確認します。

    $ oc logs -p dapi-env-test-pod

22.7. 環境変数の参照

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

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

  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
  2. pod.yaml ファイルから Pod を作成します。

    $ oc create -f pod.yaml
  3. コンテナーのログで MY_ENV_VAR_REF_ENV 値を確認します。

    $ oc logs -p dapi-env-test-pod

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

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

  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_NEW_ENV
              value: $$(SOME_OTHER_ENV)
      restartPolicy: Never
  2. pod.yaml ファイルから Pod を作成します。

    $ oc create -f pod.yaml
  3. コンテナーのログで MY_NEW_ENV 値を確認します。

    $ oc logs -p dapi-env-test-pod