Downward API

Kubernetesに過度に密結合することなく、コンテナが自分自身についての情報を持つことは有用な場合があります。 downward API を用いることで、コンテナはKubernetesのクライアントやAPIサーバーを利用せずに、自分自身やクラスターに関する情報を取得することができます。

例として、特定の既知の環境変数に一意な識別子が格納されていることを前提とする既存のアプリケーションがあるとします。 一つの可能性は、アプリケーションをラップすることですが、これは煩雑でエラーが起こりやすく、疎結合という目標に反します。 より良い選択肢は、Pod名を識別子として使用し、Pod名をその既知の環境変数に注入することです。

Kubernetesでは、実行中のコンテナにPodおよびコンテナフィールドを公開する方法が2つあります:

• 環境変数として
• downwardAPIボリューム内のファイルとして

これらPodおよびコンテナフィールドを公開する2つの方法を総称して、downward API と呼びます。

利用可能なフィールド

Kubernetes APIフィールドのうち、downward APIを通じて利用可能なものは一部のみです。 このセクションでは、利用可能なフィールドを列挙します。

利用可能なPodレベルのフィールドからの情報は、fieldRefを使用して渡すことができます。 APIレベルでは、Podのspecは常に少なくとも1つのContainerを定義します。 利用可能なコンテナレベルのフィールドからの情報は、resourceFieldRefを使用して渡すことができます。

fieldRefを通じて利用可能な情報

一部のPodレベルフィールドについては、環境変数として、またはdownwardAPIボリュームを使用して、コンテナに提供することができます。 どちらのメカニズムでも利用可能なフィールドは以下の通りです:

metadata.name

Podの名前

metadata.namespace

Podのネームスペース

metadata.uid

Podの一意ID

metadata.annotations['<KEY>']

<KEY>という名前のPodのアノテーションの値(例: metadata.annotations['myannotation'])

metadata.labels['<KEY>']

<KEY>という名前のPodのラベルのテキスト値(例: metadata.labels['mylabel'])

以下の情報は環境変数を通じて利用可能ですが、downwardAPIボリュームのfieldRefとしては利用できません:

spec.serviceAccountName

Podのサービスアカウントの名前

spec.nodeName

Podが実行されているノードの名前

status.hostIP

Podが割り当てられているノードのプライマリIPアドレス

status.hostIPs

status.hostIPのデュアルスタック版のIPアドレスで、最初のIPアドレスは常にstatus.hostIPと同じです

status.podIP

PodのプライマリIPアドレス(通常、IPv4アドレス)

status.podIPs

status.podIPのデュアルスタック版のIPアドレスで、最初のIPアドレスは常にstatus.podIPと同じです

以下の情報はdownwardAPIボリュームのfieldRefを通じて利用可能ですが、環境変数としては利用できません:

metadata.labels

Podのすべてのラベルで、label-key="escaped-label-value"形式でフォーマットされ、1行に1つのラベルが記載されます

metadata.annotations

Podのすべてのアノテーションで、annotation-key="escaped-annotation-value"形式でフォーマットされ、1行に1つのアノテーションが記載されます

resourceFieldRefを通じて利用可能な情報

これらのコンテナレベルフィールドを使用すると、CPUやメモリなどのリソースの要求と制限に関する情報を提供することができます。

        <div class="feature-state-notice feature-stable" title="フィーチャーゲート: InPlacePodVerticalScaling">
          <span class="feature-state-name">FEATURE STATE:</span>
          <span class="feature-state-details">
           <span class="feature-state-stage">GA</span> since Kubernetes v1.35
           </span>
        </div>
        
        
        <div class="feature-stable">
          
          <details>
          <summary>More information about this feature</summary>
          <p>This is a stable feature in Kubernetes, and has been since version v1.35. It was first available in the v1.27 release. You can no longer disable or opt out of this feature or behavior (it is locked); if you explicitly set a value for the associated feature gate <tt>InPlacePodVerticalScaling</tt>, Kubernetes ignores it but does not report any error.</p></p>
          </details>

          
          </div>

resource: limits.cpu

コンテナのCPU制限

resource: requests.cpu

コンテナのCPU要求

resource: limits.memory

コンテナのメモリ制限

resource: requests.memory

コンテナのメモリ要求

resource: limits.hugepages-*

コンテナのhugepages制限

resource: requests.hugepages-*

コンテナのhugepages要求

resource: limits.ephemeral-storage

コンテナの一時ストレージ制限

resource: requests.ephemeral-storage

コンテナの一時ストレージ要求

リソース制限のフォールバック情報

コンテナにCPUとメモリの制限が指定されておらず、downward APIを使用してその情報を公開しようとする場合、kubeletはノード割り当て可能量の計算に基づいて、CPUとメモリの最大割り当て可能値をデフォルトで公開します。

次の項目

downwardAPIボリュームについて詳しく読むことができます。

downward APIを使用してコンテナレベルまたはPodレベルの情報を公開することを試してみることができます:

• 環境変数として
• downwardAPIボリューム内のファイルとして