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

Containerdはプライベートレジストリに接続し、kubeletが必要とするイメージをプルするために使用するように設定できます。

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

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

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

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

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

Containerdにはすべてのレジストリに対して暗黙の「デフォルトエンドポイント」があります。 デフォルトエンドポイントは、registries.yamlにそのレジストリの他のエンドポイントがリストされている場合でも、最後の手段として常に試されます。 Rewrites are not applied to pulls against the default endpoint. 例えば、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とデフォルトエンドポイントを試し、最初に動作するものを使用します。

リダイレクト

プライベートレジストリが他のレジストリのミラーとして使用される場合、例えばプルスルーキャッシュを設定する場合、 イメージプルはリストされたエンドポイントに透過的にリダイレクトされます。元のレジストリ名は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としてイメージがプルされます。

リライト

Each mirror can have a set of rewrites, which use regular expressions to match and transform the name of an image when it is pulled from a mirror. これは、プライベートレジストリの組織/プロジェクト構造がミラーリングしているレジストリと異なる場合に便利です。 Rewrites match and transform only the image name, NOT the tag.

例えば、次の設定は、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"
Version Gate

Rewrites are no longer applied to the Default Endpoint as of the January 2024 releases: v1.26.13+k3s1, v1.27.10+k3s1, v1.28.6+k3s1, v1.29.1+k3s1. Prior to these releases, rewrites were also applied to the default endpoint, which would prevent K3s from pulling from the upstream registry if the image could not be pulled from a mirror endpoint, and the image was not available under the modified name in the upstream.

If you want to apply rewrites when pulling directly from a registry - when it is not being used as a mirror for a different upstream registry - you must provide a mirror endpoint that does not match the default endpoint. Mirror endpoints in registries.yaml that match the default endpoint are ignored; the default endpoint is always tried last with no rewrites, if fallback has not been disabled.

For example, if you have a registry at https://registry.example.com/, and want to apply rewrites when explicitly pulling registry.example.com/rancher/mirrored-pause:3.6, you can add a mirror endpoint with the port listed. Because the mirror endpoint does not match the default endpoint - "https://registry.example.com:443/v2" != "https://registry.example.com/v2" - the endpoint is accepted as a mirror and rewrites are applied, despite it being effectively the same as the default.

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

Note that when using mirrors and rewrites, images will still be stored under the original name. For example, crictl image ls will show docker.io/rancher/mirrored-pause:3.6 as available on the node, even if the image was pulled from a mirror with a different name.

設定

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セクションで"*"ワイルドカードエントリを使用して、すべてのレジストリに対するデフォルト設定を提供できます。 デフォルト設定は、そのレジストリに特定のエントリがない場合にのみ使用されます。アスタリスクは必ず引用符で囲む必要があります。

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

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 # これはレジストリのユーザー名です
      password: xxxxxx # これはレジストリのパスワードです
    tls:
      cert_file: # レジストリで使用される証明書ファイルのパス
      key_file:  # レジストリで使用されるキーのパス
      ca_file:   # レジストリで使用されるCAファイルのパス
mirrors:
  docker.io:
    endpoint:
      - "https://registry.example.com:5000"
configs:
  "registry.example.com:5000":
    tls:
      cert_file: # レジストリで使用される証明書ファイルのパス
      key_file:  # レジストリで使用されるキーのパス
      ca_file:   # レジストリで使用されるCAファイルのパス

TLSを使用しない場合

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

  • 認証あり

  • 認証なし

mirrors:
  docker.io:
    endpoint:
      - "http://registry.example.com:5000"
configs:
  "registry.example.com:5000":
    auth:
      username: xxxxxx # これはレジストリのユーザー名です
      password: xxxxxx # これはレジストリのパスワードです
mirrors:
  docker.io:
    endpoint:
      - "http://registry.example.com:5000"

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

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

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

Kubernetesがイメージのプルに問題を抱えている場合、kubeletによって表示されるエラーは、デフォルトエンドポイントに対して行われたプル試行から返された最終エラーのみを反映することがあり、設定されたエンドポイントが使用されていないように見えることがあります。

ノードの/var/lib/rancher/k3s/agent/containerd/containerd.logにあるcontainerdログを確認して、失敗の根本原因に関する詳細情報を確認してください。Note that you must look at the logs on the node where the pod is scheduled. You can check which node your pod is scheduled to by issuing kubectl get pod -o wide -n NAMESPACE POD and checking the NODE column.

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

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

  1. 作業しているリリースのGitHubからk3s-images.txtファイルを取得します。

  2. k3s-images.txtファイルにリストされている各K3sイメージをdocker.ioからプルします。
    例：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