Python パッケージ リポジトリの Artifact Registry に対する認証を構成する

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

サードパーティのアプリケーションを使用してリポジトリに接続する場合は、Artifact Registry に対して認証する必要があります。

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

始める前に

  1. ターゲット リポジトリが存在しない場合は、新しい Python パッケージ リポジトリを作成します。
  2. Python 3 がインストールされていることを確認してください。インストール手順については、Google Cloud の Python の設定のチュートリアルをご覧ください。
  3. 使用しているユーザー アカウントまたはサービス アカウントに、リポジトリへのアクセスに必要な権限があることを確認します。

  4. Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init
  5. （省略可）gcloud CLI コマンドのデフォルトを構成します。

概要

Artifact Registry では、次の認証方法がサポートされています。

Python キーリング ライブラリ（推奨）
Artifact Registry には、Artifact Registry リポジトリに接続するための認証情報を保存するキーリング バックエンドが用意されています。
パスワード認証
キーリングを使用できず、パスワードによるベーシック認証をサポートする選択肢が必要な場合は、このオプションを使用します。

このドキュメントの手順では、pip がパッケージを検索する唯一のパッケージ インデックスとして pip を構成する方法について説明します。pip パッケージ内に複数のパッケージ インデックスを構成するのではなく、仮想リポジトリを使用して、Artifact Registry の限定公開パッケージや PyPI の公開パッケージ全体のパッケージを検索することをおすすめします。pip ツールはパッケージ インデックスを特定の順序で検索しないため、コンシューマがプライベート パッケージと同じ名前のパブリック パッケージを誤ってダウンロードまたはインストールする可能性があります。仮想リポジトリを使用すると、アップストリーム ソースの優先度を構成して、この依存関係の混乱のリスクを軽減できます。

キーリングを使用した認証

Python キーリング ライブラリには、キーリング バックエンドにアクセスする方法（すなわちオペレーティング システムとサードパーティの認証情報ストア）があるアプリケーションが用意されています。

Artifact Registry には、Artifact Registry リポジトリで認証を処理するための keyrings.google-artifactregistry-auth キーリング バックエンドが用意されています。

認証情報の検索順序

Artifact Registry キーリング バックエンドを使用する場合、認証情報は Python プロジェクトには保存されません。代わりに Artifact Registry では次の順序で認証情報を検索します。

  1. アプリケーションのデフォルト認証情報（ADC）。次の順序で認証情報を検索する戦略です。

    1. GOOGLE_APPLICATION_CREDENTIALS 環境変数で定義された認証情報。

    2. Compute Engine、Google Kubernetes Engine、Cloud Run、App Engine、Cloud Run 関数のデフォルト サービス アカウントによって指定される認証情報。

  2. コマンド gcloud auth application-default login からのユーザー認証情報など、Google Cloud CLI によって提供される認証情報。

GOOGLE_APPLICATION_CREDENTIALS 変数によって、アカウントの認証が明示的になるため、トラブルシューティングが容易になります。この変数を使用しない場合は、ADC が使用するアカウントに必要な権限があることを確認します。たとえば、Compute Engine VM、Google Kubernetes Engine ノード、Cloud Run リビジョン用のデフォルトのサービス アカウントには、リポジトリへの読み取り専用権限が付与されています。デフォルトのサービス アカウントを使用して、これらの環境からアップロードする場合は、権限を変更する必要があります。

キーリングの設定

Artifact Registry キーリング バックエンドを使用する認証を設定するには:

  1. キーリング ライブラリをインストールします。

    pip install keyring

  2. Artifact Registry バックエンドをインストールします。

    pip install keyrings.google-artifactregistry-auth

  3. バックエンドを一覧表示してインストールを確認します。

    keyring --list-backends

    リストには以下を含める必要があります。

    • ChainerBackend(priority:10)
    • GooglePythonAuth(priority: 9)

  4. 次のコマンドを実行して、Python プロジェクトに追加するリポジトリ構成を出力します。

    gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

    次の値を置き換えます。

    • PROJECT は、プロジェクト ID です。このフラグを省略すると、現在のプロジェクトまたはデフォルトのプロジェクトが使用されます。
    • REPOSITORY はリポジトリの ID です。デフォルトの Artifact Registry リポジトリを構成した場合、このフラグがコマンドから省略されると使用されます。
    • LOCATION は、リポジトリのリージョンまたはマルチリージョンのロケーションです。

  5. .pypirc ファイルに次の設定を追加します。デフォルトの場所は次のとおりです。

    • Linux / macOS: $HOME/.pypirc
    • Windows: %USERPROFILE%\.pypirc
    [distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/

    次の値を置き換えます。

    • PYTHON-REPO-ID は、Twine などのツールで参照できるリポジトリの ID です。
    • PROJECT は、プロジェクト ID です。このフラグを省略すると、現在のプロジェクトまたはデフォルトのプロジェクトが使用されます。
    • REPOSITORY はリポジトリの ID です。デフォルトの Artifact Registry リポジトリを構成した場合、このフラグがコマンドから省略されると使用されます。
    • LOCATION は、リポジトリのリージョンまたはマルチリージョンのロケーションです。

  6. リポジトリを pip 構成ファイルに追加します。ファイルのロケーションは、ユーザーごとのファイルを更新するか、使用している仮想環境に特有のファイルを更新するかによって異なります。

    オペレーティング システム ユーザーに関連付けられているファイルの場合:

    • Unix: $HOME/.config/pip/pip.conf または $HOME/.pip/pip.conf
    • macOS: /Library/Application Support/pip/pip.conf または $HOME/.config/pip/pip.conf
    • Windows: %APPDATA%\pip\pip.ini または %USERPROFILE%\pip\pip.ini

    仮想環境の場合:

    • Unix と macOS: $VIRTUAL_ENV/pip.conf
    • Windows: %VIRTUAL_ENV%\pip.ini

    リポジトリのみを検索するように pip を構成するには、index-url 設定を使用し、extra-index-url 設定で構成された他のパッケージ インデックスがないことを確認します。

    [global]
index-url = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/

    リポジトリパスの末尾にある /simple/ 文字列は、リポジトリが Python Simple Repository API を実装していることを示しています。

これで、Python 環境が Artifact Registry で認証するように構成されました。

ユーザー認証情報を使用したキーリング認証

キーリングを設定したら、gcloud CLI でユーザー認証情報とともにキーリングを使用できます。Python Package Repository に接続する前に、Google Cloud CLI にサインインします。

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

gcloud auth login

サービス アカウントの認証情報を使用したキーリング認証

キーリングを設定したら、認証用のサービス アカウントを設定できます。

  1. サービス アカウントを作成するか、自動化に使用する既存のサービス アカウントを選択します。
  2. 適切な Artifact Registry のロールをサービス アカウントに付与して、リポジトリへのアクセスを許可します。

  3. 次のいずれかのオプションを使用して、サービス アカウントで認証します。

    • アプリケーションのデフォルト認証情報（推奨）

      サービス アカウント キー ファイルの場所を変数 GOOGLE_APPLICATION_CREDENTIALS に割り当てて、Artifact Registry の認証情報ヘルパーがリポジトリとの接続時にキーを取得できるようにします。

      export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE

    • gcloud CLI 認証情報

      リポジトリに接続する前に、サービス アカウントとしてログインします。Artifact Registry は gcloud CLI の認証情報の前に VM のサービス アカウントの認証情報を検出するため、Compute Engine VM からリポジトリに接続する場合は、このオプションは避けてください。

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

    KEY-FILE は、サービス アカウントのキーファイルのパスに置き換えます。

サービス アカウント キーによる認証

ユーザー名とパスワードによる認証が必要な場合は、この方法を使用します。

サービス アカウント キーは有効期間の長い認証情報です。次のガイドラインを使用して、リポジトリへのアクセスを制限してください。

  • リポジトリの操作には、専用のサービス アカウントの使用を検討してください。
  • サービス アカウントに必要な最小限の Artifact Registry のロールを付与します。たとえば、アーティファクトのみをダウンロードするサービス アカウントに Artifact Registry の読み取り権を割り当てます。
  • 組織内のグループが特定のリポジトリに対する異なるレベルのアクセス権を必要とする場合は、プロジェクト レベルではなくリポジトリ レベルでアクセス権を付与します。
  • 認証情報管理のおすすめの方法に従います。

以下により認証を構成します。

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

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

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

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

  3. 次のコマンドを実行して、Python プロジェクトに追加するリポジトリ構成を出力します。

    gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --json-key=KEY-FILE

    次の値を置き換えます。

    • PROJECT は、プロジェクト ID です。このフラグを省略すると、現在のプロジェクトまたはデフォルトのプロジェクトが使用されます。
    • REPOSITORY はリポジトリの ID です。デフォルトの Artifact Registry リポジトリを構成した場合、このフラグがコマンドから省略されると使用されます。
    • LOCATION は、リポジトリのリージョンまたはマルチリージョンのロケーションです。
    • KEY-FILE はサービス アカウントの JSON キーファイルのパスです。

  4. .pypirc ファイルに次の設定を追加します。デフォルトの場所は、ユーザーごとの pip 構成ファイルの場所です。

    • Linux / macOS: $HOME/.pypirc
    • Windows: %USERPROFILE%\.pypirc
    [distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/
username: _json_key_base64
password: KEY

    次の値を置き換えます。

    • PYTHON-REPO-ID は、Twine などのツールで参照できるリポジトリの ID です。
    • PROJECT は、プロジェクト ID です。このフラグを省略すると、現在のプロジェクトまたはデフォルトのプロジェクトが使用されます。
    • REPOSITORY はリポジトリの ID です。デフォルトの Artifact Registry リポジトリを構成した場合、このフラグがコマンドから省略されると使用されます。
    • LOCATION は、リポジトリのリージョンまたはマルチリージョンのロケーションです。
    • KEY は、サービス アカウント キーファイルにある base64 でエンコードされたキーです。

  5. リポジトリを pip 構成ファイルに追加します。pip 構成ファイルのロケーションは、ユーザーごとのファイルを更新するか、使用している仮想環境に特有のファイルを更新するかによって異なります。

    オペレーティング システム ユーザーに関連付けられているファイルの場合:

    • Unix: $HOME/.config/pip/pip.conf または $HOME/.pip/pip.conf
    • macOS: /Library/Application Support/pip/pip.conf または $HOME/.config/pip/pip.conf
    • Windows: %APPDATA%\pip\pip.ini または %USERPROFILE%\pip\pip.ini

    仮想環境の場合:

    • Unix と macOS: $VIRTUAL_ENV/pip.conf
    • Windows: %VIRTUAL_ENV%\pip.ini

    pip 構成ファイルに次の行を追加します。

    [global]
index-url = https://_json_key_base64:KEY@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
    • KEY は、サービス アカウント キーファイル内の秘密鍵です。
    • リポジトリパスの末尾にある /simple/ 文字列は、リポジトリが Python Simple Repository API を実装していることを示しています。

次のステップ