Docker 用の Artifact Registry への認証を構成する

このページでは、Artifact Registry Docker リポジトリに対して認証を行うように Docker を構成する方法について説明します。

Cloud Build または Google Cloud ランタイム環境（Google Kubernetes Engine、Cloud Run など）に対する認証を構成する必要はありませんが、必要な権限が構成されていることを確認する必要があります。

始める前に

  1. Google Cloud CLI をインストールし、次のコマンドを実行して初期化します。

    gcloud init
  2. （省略可）gcloud CLI コマンドのデフォルトを構成します。
  3. 認証に使用しているアカウントに Artifact Registry にアクセスするための権限があることを確認します。ユーザー アカウントではなく、サービス アカウントを使用することをおすすめします。
  4. Docker をまだインストールしていなければ、インストールします。Docker は Cloud Shell に含まれています。

  5. Docker がレジストリを操作するには特権アクセスが必要です。Linux や Windows では、Docker コマンドを実行するユーザーを Docker セキュリティ グループに追加します。Docker Desktop は、root ユーザーとして仮想マシンで実行されるため、この手順は MacOS では不要です。

    Linux

    Docker セキュリティ グループはdockerと呼ばれます。ユーザー名を追加するには、次のコマンドを実行します。

    sudo usermod -a -G docker ${USER}

    Windows

    Docker セキュリティ グループはdocker-usersと呼ばれます。管理者のコマンド プロンプトからユーザーを追加するには、次のコマンドを実行します。

    net localgroup docker-users DOMAIN\USERNAME /add

    ここで

    • DOMAIN は Windows ドメインです。
    • USERNAME は、ユーザー名です。

    ログアウトして再度ログインすると、グループ メンバーシップの変更が反映されます。仮想マシンを使用している場合、メンバーシップの変更を有効にするために、仮想マシンの再起動が必要になることがあります。

認証方法の選択

使用できる認証方法は、次のとおりです。

gcloud CLI 認証ヘルパー
Docker で使用するための Artifact Registry 認証情報を gcloud で直接構成します。これは最も簡単な認証方法ですが、スタンドアロンの認証ヘルパーよりも処理が遅い可能性があります。
スタンドアロン Docker 認証ヘルパー
このオプションは、主に Google Cloud CLI がない場合に Docker で使用する認証情報を構成するためのものです。これは gcloud 認証ヘルパーよりも明らかに速く、アプリケーションのデフォルト認証情報（ADC）を使用して環境内の認証情報を自動的に探索します。
アクセス トークン
サービス アカウント用に有効期間が短いアクセス トークンを生成してから、それをパスワード認証に使用します。トークンは 60 分間しか有効ではないため、サービス アカウント キーよりも安全なオプションです。
サービス アカウント キー
サービス アカウントの認証情報として使用できるユーザー管理の鍵ペア。認証情報は有効期間が長いため、使用できるすべての認証方式の中で最も安全性の低い認証方式です。

可能であれば、アクセス トークンまたは認証ヘルパーを使用して、コンテナ イメージへの不正アクセスのリスクを軽減します。サービス アカウント キーを使用する必要がある場合は、認証情報管理のおすすめの方法に従ってください。

Docker 構成ファイル内の認証設定

Docker では、認証設定が構成ファイル config.json に保存されます。

  • Linux: ~/.docker/config.json
  • Windows: %USERPROFILE%\.docker\config.json

ファイルには、さまざまな認証方法に対応する別々のセクションがあります。

credHelpers
認証に Docker 認証ヘルパーを使用する場合、Artifact Registry では、認証ヘルパー設定がファイルの credHelpers セクションに保存されます。
auths
Docker を使用し、パスワードとしてトークンやサービス アカウント キーでサインインする場合、Docker では、認証情報の Base64 でエンコードされたバージョンが、ファイルの auths セクションに保存されます。
credStore
認証情報ストアを構成して認証情報を管理する場合、認証情報ストアの設定は、ファイルの credStore セクションに記述されます。

Docker がレジストリに接続すると、まず、ホストに関連付けられている認証情報ヘルパーが確認されます。したがって、config.json の credHelpers セクションと auths セクションの両方に Artifact Registry の設定が含まれている場合、auths セクションの設定は無視されます。

gcloud CLI 認証ヘルパー

gcloud CLI 認証情報ヘルパーは、プロジェクト リソースに安全で短期間のアクセス権を付与します。Google Cloud CLI がインストールされている環境で Artifact Registry ホストに対して認証するように Docker を構成します。Cloud Shell には、Google Cloud CLI と Docker の現在のバージョンが含まれています。

gcloud CLI　認証ヘルパーは、設定が最も簡単な認証方法です。gcloud CLI セッションのアクティブ ユーザーまたはサービス アカウントの認証情報で Docker が構成されます。この認証ヘルパーは gcloud CLI に依存するため、スタンドアロン認証ヘルパーよりも明らかに処理が遅い可能性があります。サードパーティのツールを使用した自動ビルドや、多数のレジストリ ホストが構成された Docker クライアントの場合は、代わりにスタンドアロンの認証ヘルパーを使用してください。

Artifact Registry を認証するには、次の手順を行います。

  1. Docker コマンドを実行するユーザーとして gcloud CLI にログインします。

    • ユーザー認証情報により認証を構成するには、次のコマンドを実行します。

      gcloud auth login

    • サービス アカウントの認証情報で認証を構成するには、次のコマンドを実行します。

      gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE

      ここで

      • ACCOUNT は、Artifact Registry で USERNAME@PROJECT-ID.iam.gserviceaccount.com の形式で使用するサービス アカウントです。既存のアカウントを使用する場合は、Google Cloud Console のサービス アカウントページに、またはコマンド gcloud iam service-accounts list で、サービス アカウントのリストを表示できます。
      • KEY-FILE はサービス アカウント鍵ファイルです。鍵の作成については、Identity and Access Management（IAM）のドキュメントをご覧ください。

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

    gcloud auth configure-docker HOSTNAME-LIST

    HOSTNAME-LIST は、認証ヘルパー構成に追加するリポジトリ ホスト名のカンマ区切りのリストです。

    たとえば、リージョン us-central1 と asia-northeast1 を追加する場合には、次のコマンドを実行します。

    gcloud auth configure-docker us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev

    指定したホスト名が認証ヘルパー構成に追加されます。その他のホスト名は、後でコマンドを再度実行して構成に追加できます。

    サポートされているリポジトリのロケーションの一覧を表示するには、次のコマンドを実行します。

    gcloud artifacts locations list

  3. このコマンドは、現在の Docker 構成の credHelpers セクションと、指定したホスト名を追加した後に更新された構成を表示します。

    構成変更を承認するには、「y」と入力します。

    認証情報はユーザーのホーム ディレクトリに保存されます。

    • Linux: $HOME/.docker/config.json
    • Windows: %USERPROFILE%/.docker/config.json

  4. Docker が使用する認証ヘルパーはシステム PATH 内に存在する必要があります。gcloud コマンドがシステム PATH にあることを確認します。

スタンドアロン認証情報ヘルパー

スタンドアロンの Docker 認証情報ヘルパーは、gcloud CLI が利用できないシステムで Artifact Registry で認証されるように Docker を構成します。これは gcloud 認証ヘルパーよりも明らかに速く、アプリケーションのデフォルト認証情報（ADC）を使用して環境内の認証情報を自動的に探索します。イメージの push と pull 以外の操作（イメージのタグ付けや一覧表示など）の場合。サードパーティのツールを使用した自動ビルドや、多数のレジストリ ホストが構成された Docker クライアントの場合は、この認証方法の使用をおすすめします。

スタンドアロンの Docker 認証ヘルパーでは、Artifact Registry の認証情報を取得し、Docker 構成ファイルに書き込みます。この方法で、Docker のコマンドライン ツール docker を使用して、Artifact Registry を直接操作できます。

Docker 認証ヘルパーを使用するには:

  1. Docker コマンドを実行するユーザーとしてマシンにログインします。

  2. GitHub からスタンドアロン Docker 認証ヘルパーをダウンロードします。

    必要に応じて、curl コマンドライン ユーティリティを使用できます。例:

    VERSION=2.1.22
OS=linux  # or "darwin" for OSX, "windows" for Windows.
ARCH=amd64  # or "386" for 32-bit OSs

curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
| tar xz docker-credential-gcr \
&& chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/

  3. Artifact Registry を操作するときに Artifact Registry 認証情報を使用するように Docker を構成します（これが必要になるのは一度だけです）。

    docker-credential-gcr configure-docker --registries=HOSTNAME-LIST

    HOSTNAME-LIST は、認証ヘルパー構成に追加するリポジトリ ホスト名のカンマ区切りのリストです。

    たとえば、リージョン us-central1 と asia-northeast1 を追加する場合には、次のコマンドを実行します。

    docker-credential-gcr configure-docker --registries=us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev

    指定したホスト名が認証ヘルパー構成に追加されます。その他のホスト名は、後でコマンドを再度実行して構成に追加できます。

    サポートされているリポジトリのロケーションの一覧を表示するには、次のコマンドを実行します。

    gcloud artifacts locations list

    詳細については、GitHub のスタンドアロン Docker 認証情報ヘルパー ドキュメントをご覧ください。

    認証情報はユーザーのホーム ディレクトリに保存されます。

    • Linux: $HOME/.docker/config.json
    • Windows: %USERPROFILE%/.docker/config.json

  4. Docker が使用する認証ヘルパーはシステム PATH 内に存在する必要があります。docker-credential-gcr コマンドがシステム PATH にあることを確認します。

  5. 認証情ヘルパーが認証情報を正常に取得できることを確認するには、次のコマンドを実行します。

    echo "https://HOSTNAME" | docker-credential-gcr get

    HOSTNAME は、構成に追加したホスト名に置き換えます。例:

    echo "https://us-central1-docker.pkg.dev" | docker-credential-gcr get

    コマンドが正常に実行されると、返された JSON 出力の Secret フィールドにトークンが含まれます。例:

    {"ServerURL":"https://us-central1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}

Docker が Artifact Registry で認証するように構成されました。イメージの push と pull を行う場合は、権限が正しく構成されていることを確認してください。

アクセス トークン

有効時間の短い OAuth アクセス トークンを生成して、Artifact Registry で認証できます。トークンは 60 分間有効であるため、リクエストしてから 1 時間以内に Artifact Registry との接続に使用してください。

アクセス トークンをサービス アカウントの認証情報で使用するには:

  1. アプリケーションに代わって動作するサービス アカウントを作成するか、自動化に使用する既存のサービス アカウントを選択します。

  2. 適切な Artifact Registry のロールをサービス アカウントに付与して、リポジトリへのアクセスを許可します。

  3. サービス アカウント用のアクセス トークンを生成して認証します。

    • サービス アカウントの権限を借用して、サービス アカウントとして認証するには、サービス アカウント トークン作成者のロール（roles/iam.serviceAccountTokenCreator）に対する権限が必要です。

      次のコマンドを実行します。ACCOUNT は、サービス アカウントのメールアドレスと、リポジトリの LOCATION リージョンまたはマルチリージョンのロケーションに置き換えます。

      Linux

      gcloud auth print-access-token \
    --impersonate-service-account ACCOUNT | docker login \
    -u oauth2accesstoken \
    --password-stdin https://LOCATION-docker.pkg.dev

      Windows

      gcloud auth print-access-token --impersonate-service-account ACCOUNT |
    docker login -u oauth2accesstoken --password-stdin https://LOCATION-docker.pkg.dev

これで Docker が Artifact Registry で認証されるようになりました。

サービス アカウント キー

サービス アカウントの有効な秘密鍵にアクセスできるユーザーは、サービス アカウントを介してリソースにアクセスできます。サービス アカウントに対するキーのアクセスのライフサイクル、つまりサービス アカウントがアクセスできるデータは、ダウンロードしたユーザーのライフサイクルとは無関係です。

次のガイドラインを使用して、リポジトリへのアクセスを制限してください。

  • リポジトリの操作のみ使用される専用のサービス アカウントを作成します。
  • サービス アカウントに必要なアクセスに特定の Artifact Registry ロールを付与します。たとえば、アーティファクトのみをダウンロードするサービス アカウントには、Artifact Registry 読み取りのロールのみが必要です。
  • プロジェクト レベルではなく、各リポジトリで専用のサービス アカウントの権限を構成します。その後、リポジトリのコンテキストに基づいてアクセス権を指定できます。たとえば、開発ビルド用のサービス アカウントには、本番環境リポジトリに対する Artifact Registry 読み取りのロールと、ステージング リポジトリに対する Artifact Registry 書き込みのロールがある場合があります。
  • 認証情報管理のおすすめの方法に従います。

Artifact Registry リポジトリでのみ使用する新しいサービス アカウントとサービス アカウント鍵を作成する手順は、次のとおりです。

  1. アプリケーションに代わって動作するサービス アカウントを作成するか、自動化に使用する既存のサービス アカウントを選択します。

    Artifact Registry で認証を設定するには、サービス アカウントのキーファイルの場所が必要です。既存のアカウントの場合は、[サービス アカウント] ページで鍵を表示し、新しい鍵を作成できます。

    [サービス アカウント] ページに移動

  2. 必要に応じて、キーファイルの内容をすべて base64 でエンコードできます。

    Linux

    base64 FILE-NAME > NEW-FILE-NAME

    macOS

    base64 -i FILE-NAME -o NEW-FILE-NAME

    ウィンドウ

    Base64.exe -e FILE-NAME > NEW-FILE-NAME

    ここで、FILE-NAME は元のキーファイルの名前、NEW-FILE-NAME は base64 でエンコードされたキーファイルです。

  3. サービス アカウントの権限が正しく構成されていることを確認します。Compute Engine サービス アカウントを使用している場合は、権限とアクセススコープの両方を正しく構成する必要があります。

  4. サービス アカウント鍵を使用して、Docker との統合を構成します。

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

    Linux / macOS

    cat KEY-FILE | docker login -u KEY-TYPE --password-stdin \
https://LOCATION-docker.pkg.dev

    Windows

    Get-Content KEY-FILE |
docker login -u KEY-TYPE --password-stdin https://LOCATION-docker.pkg.dev

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

    • KEY-TYPE は次のいずれかです。
      • ファイルの作成時に提供された JSON 形式のサービス アカウント鍵を使用している場合は、_json_key。
      • _json_key_base64 を使用する場合、ファイルの内容のすべてを base64 でエンコードします。
    • KEY-FILE は、JSON 形式のサービス アカウント鍵ファイルの名前です。
    • LOCATION は、イメージが保存されているリポジトリのリージョンまたはマルチリージョンのロケーションです。

これで Docker が Artifact Registry で認証されるようになりました。