GKE ノードで containerd 構成をカスタマイズする

このページでは、Google Kubernetes Engine（GKE）ノードの containerd コンテナ ランタイムの構成をカスタマイズする方法について説明します。このドキュメントをお読みになる前に、コンテナ ランタイムの概要とカスタマイズする理由を理解している必要があります。

GKE での containerd 構成について

Container-Optimized OS などのオペレーティング システムを実行する GKE ノードでは、containerd ランタイムで一連のオプションを手動で構成できます。ランタイムをカスタマイズすると、限定公開イメージ レジストリへのアクセスなどの特別な要件を構成できます。これらのオプションを設定するには、ランタイム構成ファイルと呼ばれる YAML ファイルを作成し、クラスタを作成または更新するときにこのファイルを GKE に渡します。

この方法で containerd をカスタマイズすると、セキュリティ リスクとなる特権 DaemonSet のデプロイを回避できます。GKE にランタイム構成ファイルを指定すると、GKE はノードを再作成し、すべてのノードで containerd config.toml ファイルを構成で更新します。この構成は、ノードの終了、アップグレード、再作成後も保持されます。

ランタイム構成ファイルを使用する場合は、containerd でのみオプションを構成できます。GKE では、ノードシステム構成ファイルと呼ばれる別のファイルを使用して、特定の kubelet オプションと低レベルの Linux カーネル オプションを構成することもサポートされています。詳細については、ノードシステム構成のカスタマイズをご覧ください。

制限事項

ランタイム構成ファイルを使用して Windows ノードイメージの containerd 設定を変更することはできません。

利用可能な containerd 構成オプション

以降のセクションでは、ランタイム構成ファイルを使用して構成できるオプションについて説明します。

privateRegistryAccessConfig

Secret Manager に保存したプライベート認証情報を使用して、プライベート イメージ レジストリにアクセスします。

このオプションは、Container-Optimized OS ノードイメージの場合は GKE バージョン 1.27.3-gke.1700 以降、Ubuntu ノードイメージの場合はバージョン 1.33 以降で使用できます。

手順については、プライベート CA 証明書を使用して限定公開レジストリにアクセスするをご覧ください。

privateRegistryAccessConfig:
  enabled: true
  certificateAuthorityDomainConfig:
  - gcpSecretManagerCertificateConfig:
    secretURI: "SECRET_LOCATION"
  fqdns:
  - "FQDN1"
  - "FQDN2"

この構成には次のフィールドがあります。

  • enabled: プライベート レジストリ構成を有効にするブール値。enabled: false に設定した場合、privateRegistryAccessConfig アイテム内の他のフィールドをすべて削除します。
  • certificateAuthorityDomainConfig: 証明書と FQDN の定義が最大 5 つ含まれます。
  • gcpSecretManagerCertificateConfig: Secret Manager に保存されている証明書と FQDN の配列が含まれます。
  • secretURI: Secret Manager 内の証明書の場所。privateRegistryAccessConfig は、secretURI でのみグローバル Secret をサポートします。
  • fqdns: プライベート レジストリの完全修飾ドメイン名のリスト。IPv4 アドレスを使用することもできますが、FQDN を使用することをおすすめします。

registryHosts

機能、カスタム ヘッダー、証明書など、containerd レジストリの詳細設定を構成します。これは containerd の hosts.toml に対応します。

このオプションは、GKE バージョン 1.34.1-gke.2980000 以降で使用できます。

registryHosts:
- server: "REGISTRY_SERVER_FQDN"
  hosts:
  - host: "MIRROR_FQDN"
    capabilities:
    - "HOST_CAPABILITY_PULL"
    - "HOST_CAPABILITY_RESOLVE"
    - "HOST_CAPABILITY_PUSH"
    overridePath: false
    dialTimeout: "30s"
    header:
    - key: "HEADER_KEY"
      value:
      - "HEADER_VALUE_1"
      - "HEADER_VALUE_2"
    ca:
    - gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CA_SECRET/versions/VERSION"
    client:
    - cert:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_CERT_SECRET/versions/VERSION"
      key:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_KEY_SECRET/versions/VERSION"

この構成には次のフィールドがあります。

  • server: レジストリ サーバーのホスト名（例: example.com）。これは、ノードの構成ファイルの名前付けに使用されます。完全修飾ドメイン名または IPv4 アドレスにする必要があります。
  • hosts: server のホスト固有の構成のリスト。
  • host: レジストリ ミラーのホスト名（例: mirror.example.com）。完全修飾ドメイン名または IPv4 アドレスにする必要があります。
  • capabilities: ホストが実行できるオペレーションを指定する機能のリスト。次の値がサポートされています。
    • HOST_CAPABILITY_PULL: ダイジェストでマニフェストと blob を取得する機能を表します。
    • HOST_CAPABILITY_RESOLVE: 名前でマニフェストを取得する機能を表します。
    • HOST_CAPABILITY_PUSH: blob とマニフェストを push する機能を表します。
    指定しない場合、すべての機能が有効になります。
  • overridePath: ブール値。true の場合、ホストの API ルート エンドポイントは、API 仕様ではなく URL パスで定義されていることを示します。これは、/v2 接頭辞がない非準拠の OCI レジストリで使用できます。デフォルトは false です。
  • dialTimeout: 接続試行の完了までに許容される最大期間を指定する期間文字列（例: "30s"）。最大許容値は "180s" です。設定されていない場合、containerd はデフォルトの "30s" を設定します。値は、秒単位の 10 進数に s 接尾辞を付けて指定してください。
  • header: レジストリ ホストに送信するカスタム HTTP ヘッダーのリスト。
    • key: ヘッダーキー。
    • value: ヘッダー値のリスト。
  • ca: レジストリ ホストの認証局（CA）の証明書構成のリスト。証明書の Secret を作成して必要な権限を構成するには、CA の公開鍵を Secret Manager に保存するの手順をご覧ください。
    • gcpSecretManagerSecretUri: CA 証明書を含む Secret Manager の Secret の URI。グローバル Secret とリージョン Secret の両方がサポートされます。形式は、Secret のタイプに応じて次のようになります。
      • グローバル Secret の形式: projects/PROJECT_ID_OR_NUMBER/secrets/SECRET_NAME/versions/VERSION。
      • リージョン Secret の形式: projects/PROJECT_ID_OR_NUMBER/locations/REGION/secrets/SECRET_NAME/versions/VERSION。
  • client: レジストリ ホストへの認証用のクライアント証明書と鍵ペアのリスト。証明書の Secret を作成して必要な権限を構成するには、CA の公開鍵を Secret Manager に保存するの手順をご覧ください。
    • cert: クライアント証明書の構成。
      • gcpSecretManagerSecretUri: クライアント証明書を含む Secret Manager の Secret の URI。グローバル Secret とリージョン Secret の両方がサポートされます。
    • key: クライアントの秘密鍵の構成。
      • gcpSecretManagerSecretUri: クライアント鍵を含む Secret Manager の Secret の URI。グローバル Secret とリージョン Secret の両方がサポートされます。

writableCgroups

ワークロードが子プロセスのリソースを管理できるように、/sys/fs/cgroup ファイル システムを読み取り / 書き込みモードでマウントします。

このオプションは、GKE バージョン 1.34.1-gke.2541000 以降で使用できます。

詳細については、コンテナの書き込み可能な cgroup を構成するをご覧ください。

writableCgroups:
  enabled: true

新しいクラスタに containerd 構成を適用する

このセクションでは、新しい GKE クラスタの作成時に containerd 構成ファイルを適用する方法について説明します。

次のコマンドを実行して、Autopilot クラスタを作成します。

gcloud container clusters create-auto CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

次のように置き換えます。

  • CLUSTER_NAME: 新しいクラスタの名前。
  • LOCATION: 新しいクラスタの Compute Engine のロケーション。
  • PATH_TO_CONFIG_FILE: 作成した構成ファイルのパス（~/containerd-configuration.yaml など）。

新しい Standard クラスタで containerd 構成を有効にするには、同じオプションを指定して gcloud container clusters create コマンドを実行します。

新しいノードプールに containerd 構成を適用する

次のコマンドを使用して、新しい GKE ノードプールに containerd 構成を適用できます。

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

次のように置き換えます。

  • NODE_POOL_NAME: 新しいノードプールの名前。
  • CLUSTER_NAME: 既存のクラスタの名前。
  • LOCATION: 新しいノードプールの Compute Engine のロケーション。
  • PATH_TO_CONFIG_FILE: 作成した構成ファイルのパス（~/containerd-configuration.yaml など）。

既存のクラスタに containerd 構成を適用する

このセクションでは、既存のクラスタとノードに containerd 構成を適用する方法について説明します。

アクセス スコープを確認する

この機能を使用するには、既存のクラスタに cloud-platform アクセス スコープが必要です。このセクションでは、アクセス スコープを確認し、新規または変更された限定公開レジストリ構成ファイルを使用して既存のクラスタを更新する方法について説明します。

新しいクラスタのデフォルトのアクセス スコープの詳細については、GKE のアクセス スコープをご覧ください。

Autopilot のアクセス スコープを確認する

次のコマンドを実行します。

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=nodeConfig \
    --format='csv[delimiter="\\n",no-heading](oauthScopes)'

クラスタに https://www.googleapis.com/auth/cloud-platform アクセス スコープがない場合は、このアクセス スコープを持つ新しいクラスタを作成します。

Standard アクセス スコープを確認する

Standard クラスタのアクセス スコープを確認するには、ノードプールを確認します。

gcloud container node-pools describe NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --format='value[delimiter="\\n"](config.oauthScopes)'

NODE_POOL_NAME は、ノードプールの名前に置き換えます。

クラスタに https://www.googleapis.com/auth/cloud-platform アクセス スコープがない場合は、cloud-platform アクセス スコープで新しいノードプールを作成し、既存のノードプールを削除します。

構成ファイルを使用するようにクラスタを更新する

次のコマンドを実行します。

gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Standard クラスタでノードを再作成する

Standard クラスタで自動アップグレードを使用しない場合は、ノードプールを手動で再作成して新しい構成を適用する必要があります。ノードの手動再作成をトリガーするには、クラスタがすでに使用している GKE バージョンにクラスタをアップグレードします。

gcloud container clusters upgrade CLUSTER_NAME \
    --location=LOCATION \
    --cluster-version=VERSION

VERSION は、クラスタがすでに使用している GKE パッチ バージョンに置き換えます。

containerd 構成オプションを無効にする

privateRegistryAccessConfig を無効にする

  1. 次の例に示すように、構成ファイルを更新して、privateRegistryAccessConfig に enabled: false を指定し、アイテム内の他のフィールドを削除します。

    privateRegistryAccessConfig:
  enabled: false
  2. 更新された構成ファイルをクラスタに適用します。手順については、既存のクラスタに containerd 構成を適用するをご覧ください。

registryHosts を無効にする

  1. 次の例に示すように、構成ファイルを更新して、registryHosts アイテムに空の配列を指定します。

    registryHosts: []
  2. 更新された構成ファイルをクラスタに適用します。手順については、既存のクラスタに containerd 構成を適用するをご覧ください。