Docker に対する認証の設定

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

始める前に

  1. Artifact Registry API が有効で、Cloud SDK がインストールされていることを確認します。手順については、サービスの有効化と無効化をご覧ください。
  2. ターゲット リポジトリが存在しない場合は、新しいリポジトリを作成します
  3. (省略可)gcloud コマンドのデフォルトを構成します
  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 はユーザー名です。

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

認証方法の選択

ほとんどの場合、Artifact Registry の認証にはサービス アカウントの使用をおすすめします。

サービス アカウントは特定ユーザーへの関連付けは行われず、Google Cloud アプリケーションはアプリケーションのデフォルト認証情報戦略を使用して認証情報を自動的に取得します。

通常、Cloud Build や Cloud Run など、Artifact Registry と統合されるアプリケーションのサービス アカウントには、同じプロジェクトのリポジトリにアクセスする権限がデフォルトで構成されます。このようなアプリケーションでは、Docker 認証を構成する必要はありません。

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

gcloud 認証ヘルパー(推奨)
Docker で使用するための Artifact Registry 認証情報を gcloud で直接構成します。可能であればこの方法を使用して、プロジェクト リソースへの安全で短期間のアクセス権を付与します。このオプションでは、Docker バージョン 18.03 以降のみがサポートされます。
スタンドアロン Docker 認証ヘルパー
このオプションは、主に Cloud SDK がない場合に Docker で使用する認証情報を構成するためのものです。このオプションでは、Docker バージョン 18.03 以降のみがサポートされます。
アクセス トークン
アプリケーションのデフォルトの認証情報は、サービス アカウントが Google Cloud リソースへのアクセスに使用する短期間のアクセス トークンを提供します。これは、gcloud ツールを認証ヘルパーとして使用する場合に最も安全な方法です。
JSON キーファイル

サービス アカウントの認証情報として使用できるユーザー管理の鍵ペア。認証情報は有効期間が長いため、使用できるすべての認証方式の中で最も安全性の低い認証方式です。

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

gcloud 認証ヘルパーを使用するのが理想的ではなく、他のオプションの使用によるセキュリティへの影響を理解している場合は、別の認証オプションのみを使用してください。

さらに、Artifact Registry への接続に使用するユーザー アカウントまたはサービス アカウントに付与されている権限についても検討してください。たとえば、Compute Engine のデフォルトのサービス アカウントには、親プロジェクトの Editor 基本ロールが付与されます。デフォルトのサービス アカウントを使用してリポジトリを操作する代わりに、リポジトリでの使用に必要な特定の権限があるサービス アカウントを作成することをご検討ください。

gcloud 認証ヘルパー(推奨)

可能であれば、この方法を使用することを強くおすすめします。この方法では、プロジェクト リソースに安全で短期間のアクセス権が付与されます。

gcloud ツールを使用して、Cloud Shell または Cloud SDK がインストールされている任意の環境で認証を構成します。Cloud Shell には、Docker の最新バージョンが含まれています。

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

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

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

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

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

      ここで

      • ACCOUNTUSERNAME@PROJECT-ID.iam.gserviceaccount.com 形式のサービス アカウント名です。 既存のサービス アカウントは、Cloud Console の [サービス アカウント]ページまたは gcloud iam service-accounts list コマンドを使用して表示できます。
      • KEY-FILE はサービス アカウント鍵ファイルです。鍵の作成については、Identity and Access Management(IAM)のドキュメントをご覧ください。
  2. 次のコマンドを実行します。

    gcloud auth configure-docker HOSTNAME-LIST
    

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

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

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

    指定されたリポジトリのロケーションが認証ヘルパー構成に追加されます。後でコマンドをもう一度実行して、他のロケーションを構成に追加できます。

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

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

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

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

スタンドアロンの Docker 認証情報ヘルパーは、Cloud SDK が利用できないシステムで Artifact Registry で認証されるよう Docker を構成します。

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

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

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

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

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

    VERSION=2.0.0
    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 --to-stdout ./docker-credential-gcr \
    > /usr/bin/docker-credential-gcr && chmod +x /usr/bin/docker-credential-gcr
    
  3. Artifact Registry を操作するときに Artifact Registry 認証情報を使用するように Docker を構成します(これが必要になるのは一度だけです)。

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

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

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

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

    指定されたリポジトリのロケーションが認証ヘルパー構成に追加されます。後でコマンドをもう一度実行して、他のロケーションを構成に追加できます。

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

    gcloud artifacts locations list
    

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

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

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

アクセス トークン

アクセス トークンは、Google Cloud リソースへのアクセスを提供する有効期間が短いトークンです。トークンは 60 分間有効であるため、リクエストしてから 1 時間以内に Artifact Registry リポジトリとの接続に使用してください。

Google Cloud は、アプリケーションのデフォルト認証情報を使用してアクセス トークンを取得します。

アクセス トークンを使用するには、次の手順を行います。

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

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

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

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

  3. Docker で Artifact Registry を認証するときに、認証情報としてアクセス トークンを取得します。

    Linux / macOS

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

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

    または、--password-stdin をサポートしていない古い Docker クライアントの場合は次のようになります。

    docker login -u oauth2accesstoken -p "$(gcloud auth print-access-token)" \
    https://LOCATION-docker.pkg.dev
    

    ここで

    • oauth2accesstoken は、アクセス トークンで認証するときに使用するユーザー名です。
    • gcloud auth print-access-token は、アクセス トークンを取得する gcloud コマンドです。アクセス トークンは認証用のパスワードです。
    • LOCATION は、イメージが格納されるリポジトリのリージョンまたはマルチリージョン ロケーションです。

    Windows

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

    gcloud auth print-access-token
    ya29.8QEQIfY_...
    
    docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
    https://LOCATION-docker.pkg.dev/<var>PROJECT-ID</var>/<var>REPOSITORY</var>
    

    ここで

    • oauth2accesstoken は、アクセス トークンで認証するときに使用するユーザー名です。
    • gcloud auth print-access-token は、アクセス トークンを取得する gcloud コマンドです。アクセス トークンは認証用のパスワードです。
    • LOCATION は、イメージが格納されるリポジトリのリージョンまたはマルチリージョン ロケーションです。

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

JSON キーファイル

サービス アカウント キーとは、サービス アカウントの認証情報として使用できる有効期間が長い鍵ペアのことです。秘密鍵のセキュリティと、キーのローテーションなどの他のキー管理操作は、ユーザーの責任になります。

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

リポジトリへのアクセスを制限するには、次のガイドラインに従います。

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

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

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

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

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

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

    Linux

    base64 FILE-NAME &gt; NEW-FILE-NAME
    

    macOS

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

    Windows

    Base64.exe -e FILE-NAME &gt; 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
    

    または、--password-stdin をサポートしていない古い Docker クライアントの場合は次のようになります。

    docker login -u KEY-TYPE -p "$(cat FILE-NAME.json)" \
    https://LOCATION-docker.pkg.dev
    

    ここで

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

    Windows

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

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

    または、--password-stdin をサポートしていない古い Docker クライアントの場合は次のようになります。

    set /p PASS=<KEY-FILE
    docker login -u KEY-TYPE -p "%PASS%" https://LOCATION-docker.pkg.dev
    

    ここで

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

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