この文書は自動機械翻訳技術を使用して翻訳されています。 正確な翻訳を提供するように努めておりますが、翻訳された内容の完全性、正確性、信頼性については一切保証いたしません。 相違がある場合は、元の英語版 英語 が優先され、正式なテキストとなります。

プライベートレジストリの設定

Containerdはプライベートレジストリに接続し、kubeletが必要に応じてイメージをプルするためにそれらを使用するように構成できます。

起動時に、K3sは`/etc/rancher/k3s/registries.yaml`が存在するかどうかを確認します。存在する場合、このファイルに含まれるレジストリ設定がcontainerdの設定を生成する際に使用されます。

  • docker.ioのようなパブリックレジストリのミラーとしてプライベートレジストリを使用したい場合は、ミラーを使用する各ノードで`registries.yaml`を設定する必要があります。

  • プライベートレジストリが認証を必要とする場合、カスタムTLS証明書を使用する場合、またはTLSを使用しない場合は、レジストリからイメージをプルする各ノードで`registries.yaml`を設定する必要があります。

サーバーノードはデフォルトでスケジュール可能であることに注意してください。サーバーノードにテイントが設定されていない場合、これらのノードでワークロードを実行するのであれば、各サーバーにも`registries.yaml`ファイルを作成することを確認してください。

デフォルトエンドポイントのフォールバック

Containerdにはすべてのレジストリに対して暗黙の「デフォルトエンドポイント」があります。 デフォルトエンドポイントは、`registries.yaml`にそのレジストリの他のエンドポイントがリストされていても、常に最後の手段として試みられます。 デフォルトエンドポイントに対するプルにはリライトは適用されません。 例えば、`registry.example.com:5000/rancher/mirrored-pause:3.6`をプルする際、containerdは`https://registry.example.com:5000/v2`のデフォルトエンドポイントを使用します。

  • docker.io`のデフォルトエンドポイントはhttps://index.docker.io/v2`です。

  • 他のすべてのレジストリのデフォルトエンドポイントは`\https://<REGISTRY>/v2`であり、`<REGISTRY>`はレジストリのホスト名とオプションのポートです。

レジストリとして認識されるためには、イメージ名の最初のコンポーネントには少なくとも1つのピリオドまたはコロンが含まれている必要があります。 歴史的な理由から、名前にレジストリが指定されていないイメージは暗黙的に`docker.io`からのものであると識別されます。

バージョンゲート

`--disable-default-registry-endpoint`オプションは2024年1月のリリースから利用可能です：v1.26.13+k3s1、v1.27.10+k3s1、v1.28.6+k3s1、v1.29.1+k3s1

ノードは`--disable-default-registry-endpoint`オプションで開始できます。 これが設定されると、containerdはデフォルトのレジストリエンドポイントにフォールバックせず、構成されたミラーエンドポイントからのみプルし、分散レジストリが有効になっている場合はそれも使用します。

これは、クラスターが真のエアギャップ環境にあり、アップストリームレジストリが利用できない場合や、特定のノードのみがアップストリームレジストリからプルすることを望む場合に望ましいかもしれません。

デフォルトのレジストリエンドポイントを無効にすることは、`registries.yaml`を介して構成されたレジストリにのみ適用されます。 レジストリが`registries.yaml`のミラーエントリを介して明示的に構成されていない場合、デフォルトのフォールバック動作は引き続き使用されます。

レジストリ設定ファイル

ファイルは、各レジストリのサブキーを持つ2つのトップレベルキーで設定されています：

mirrors:
  <REGISTRY>:
    endpoint:
      - https://<REGISTRY>/v2
configs:
  <REGISTRY>:
    auth:
      username: <BASIC AUTH USERNAME>
      password: <BASIC AUTH PASSWORD>
      token: <BEARER TOKEN>
    tls:
      ca_file: <PATH TO SERVER CA>
      cert_file: <PATH TO CLIENT CERT>
      key_file: <PATH TO CLIENT KEY>
      insecure_skip_verify: <SKIP TLS CERT VERIFICATION BOOLEAN>

ミラー

ミラーセクションは、レジストリの名前とエンドポイントを定義します。例えば：

mirrors:
  registry.example.com:
    endpoint:
      - "https://registry.example.com:5000"

各ミラーには名前とエンドポイントのセットが必要です。レジストリからイメージをプルする際、containerdはこれらのエンドポイントURLとデフォルトのエンドポイントを試み、最初に動作するものを使用します。

リダイレクト

プライベートレジストリが別のレジストリのミラーとして使用される場合、例えばhttps://docs.docker.com/registry/recipes/mirror/[プルスルーキャッシュ]を構成する際、イメージのプルはリストされたエンドポイントに透過的にリダイレクトされます。元のレジストリ名は、`ns`クエリパラメータを介してミラーエンドポイントに渡されます。

例えば、`docker.io`のためにミラーが設定されている場合：

mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"

その場合、`docker.io/rancher/mirrored-pause:3.6`をプルすると、透過的にイメージが`registry.example.com:5000/rancher/mirrored-pause:3.6`としてプルされます。

リライト

各ミラーには、ミラーからプルされる際にイメージの名前を一致させて変換するために正規表現を使用するリライトのセットを持つことができます。 これは、プライベートレジストリの組織/プロジェクト構造がミラーしているレジストリと異なる場合に便利です。 リライトはイメージ名のみを一致させて変換し、タグは一致させません。

例えば、次の設定は、イメージ`docker.io/rancher/mirrored-pause:3.6`を`registry.example.com:5000/mirrorproject/rancher-images/mirrored-pause:3.6`として透過的にプルします：

mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"
    rewrite:
      "^rancher/(.*)": "mirrorproject/rancher-images/$1"
バージョンゲート

2024年1月のリリース（v1.26.13+k3s1、v1.27.10+k3s1、v1.28.6+k3s1、v1.29.1+k3s1）以降、デフォルトエンドポイントにはリライトが適用されなくなりました。 これらのリリース以前は、デフォルトエンドポイントにもリライトが適用されており、ミラーエンドポイントからイメージをプルできない場合、K3sがアップストリームレジストリからプルするのを防いでいました。また、イメージがアップストリームの修正された名前の下で利用できない場合も同様です。

レジストリから直接プルする際にリライトを適用したい場合（異なるアップストリームレジストリのミラーとして使用されていない場合）、デフォルトエンドポイントと一致しないミラーエンドポイントを提供する必要があります。 デフォルトエンドポイントと一致する`registries.yaml`のミラーエンドポイントは無視されます。フォールバックが無効になっていない場合、デフォルトエンドポイントは常に最後にリライトなしで試行されます。

例えば、https://registry.example.com/`にレジストリがあり、明示的に`registry.example.com/rancher/mirrored-pause:3.6`をプルする際に書き換えを適用したい場合、ポートがリストされたミラーエンドポイントを追加できます。 ミラーエンドポイントがデフォルトエンドポイント - `"https://registry.example.com:443/v2" != "https://registry.example.com/v2" - と一致しないため、そのエンドポイントはミラーとして受け入れられ、書き換えが適用されます。これは、実質的にデフォルトと同じであるにもかかわらずです。

mirrors:
 registry.example.com
   endpoint:
     - "https://registry.example.com:443"
   rewrite:
     "^rancher/(.*)": "mirrorproject/rancher-images/$1"

ミラーと書き換えを使用する際、イメージは元の名前の下に保存されることに注意してください。 例えば、`crictl image ls`はノード上で`docker.io/rancher/mirrored-pause:3.6`が利用可能であることを示します。たとえイメージが異なる名前のミラーからプルされた場合でも同様です。

設定

`configs`セクションは、各ミラーのTLSおよび認証情報の設定を定義します。各ミラーに対して、`auth`および/または`tls`を定義できます。

`tls`部分は次のように構成されています：

ディレクティブ 説明

cert_file

レジストリとの認証に使用されるクライアント証明書のパス

key_file

レジストリとの認証に使用されるクライアントキーのパス

ca_file

レジストリのサーバー証明書ファイルを検証するために使用されるCA証明書のパスを定義します。

insecure_skip_verify

レジストリのTLS検証をスキップするかどうかを定義するブール値

`auth`部分は、ユーザー名/パスワードまたは認証トークンのいずれかで構成されています：

ディレクティブ 説明

username

プライベートレジストリの基本認証のユーザー名

password

プライベートレジストリの基本認証のユーザーパスワード

auth

プライベートレジストリの基本認証の認証トークン

以下は、異なるモードでプライベートレジストリを使用する基本的な例です：

ワイルドカードサポート

バージョンゲート

ワイルドカードサポートは、2024年3月のリリース（v1.26.15+k3s1、v1.27.12+k3s1、v1.28.8+k3s1、v1.29.3+k3s1）から利用可能です。

`mirrors`および`configs`セクションで、すべてのレジストリに対するデフォルト設定を提供するために、`"*"`ワイルドカードエントリを使用できます。 デフォルト設定は、そのレジストリに対する特定のエントリがない場合にのみ使用されます。アスタリスクは必ず引用符で囲む必要があります。

以下の例では、すべてのレジストリに対してローカルレジストリミラーが使用されます。TLS検証は、`docker.io`を除くすべてのレジストリに対して無効になります。

mirrors:
  "*":
    endpoint:
      - "https://registry.example.com:5000"
configs:
  "docker.io":
  "*":
    tls:
      insecure_skip_verify: true

TLSを使用する場合

以下は、TLSを使用する際に各ノードで`/etc/rancher/k3s/registries.yaml`を構成する方法を示す例です。

  • 認証を使用する場合

  • 認証を使用しない場合

mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"
configs:
  "registry.example.com:5000":
    auth:
      username: xxxxxx # this is the registry username
      password: xxxxxx # this is the registry password
    tls:
      cert_file: # path to the cert file used in the registry
      key_file:  # path to the key file used in the registry
      ca_file:   # path to the ca file used in the registry
mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"
configs:
  "registry.example.com:5000":
    tls:
      cert_file: # path to the cert file used in the registry
      key_file:  # path to the key file used in the registry
      ca_file:   # path to the ca file used in the registry

TLSなし

以下は、TLSを_使用しない_場合に各ノードで`/etc/rancher/k3s/registries.yaml`を構成する方法を示す例です。

  • 認証を使用する場合

  • 認証を使用しない場合

mirrors:
  docker.io:
    endpoint:
      - "http://registry.example.com:5000"
configs:
  "registry.example.com:5000":
    auth:
      username: xxxxxx # this is the registry username
      password: xxxxxx # this is the registry password
mirrors:
  docker.io:
    endpoint:
      - "http://registry.example.com:5000"

TLS通信がない場合、エンドポイントに`http://`を指定する必要があります。そうしないと、デフォルトでhttpsになります。

レジストリの変更を有効にするには、各ノードでK3sを再起動する必要があります。

イメージプルのトラブルシューティング

Kubernetesがイメージをプルする際に問題が発生した場合、kubeletに表示されるエラーは、デフォルトエンドポイントに対して実施されたプル試行で最後に返されたエラーのみを反映する可能性があり、そのため、設定されたエンドポイントが使用されていないように見えることがあります。

エラーの根本原因に関する詳細情報は、ノードの`/var/lib/rancher/k3s/agent/containerd/containerd.log`にあるcontainerdログを確認してください。ノードにスケジュールされたポッドのログを確認する必要があることに注意してください。ポッドがスケジュールされているノードを確認するには、`kubectl get pod -o wide -n NAMESPACE POD`を発行してNODE列を確認してください。

プライベートレジストリへのイメージの追加

画像をプライベートレジストリにミラーリングするには、画像をプルおよびプッシュできるDockerまたは他のサードパーティツールを持つホストが必要です。
以下の手順は、dockerdとdocker CLIツールを持ち、docker.ioとプライベートレジストリの両方にアクセスできるホストがあることを前提としています。

  1. 作業しているリリースのためにGitHubから`k3s-images.txt`ファイルを取得してください。

  2. docker.ioからk3s-images.txtファイルにリストされている各K3s画像をプルしてください。
    例: docker pull docker.io/rancher/mirrored-pause:3.6

  3. 画像をプライベートレジストリに再タグ付けしてください。
    例: docker tag docker.io/rancher/mirrored-pause:3.6 registry.example.com:5000/rancher/mirrored-pause:3.6

  4. 画像をプライベートレジストリにプッシュしてください。
    例: docker push registry.example.com:5000/rancher/mirrored-pause:3.6