OS パッケージに関する問題のトラブルシューティング

Artifact Registry で OS パッケージを管理する際に問題が発生した場合に役立つトラブルシューティング手順について説明します。

OS パッケージの Artifact Registry リモート リポジトリに関する問題を解決する方法については、リモート リポジトリのトラブルシューティングをご覧ください。

認証と権限に関する問題

パッケージのインストールなどの操作でリポジトリに接続することはできません。パッケージ マネージャーの出力に 401 または 403 エラーが含まれています。これは、認証または権限に関する問題を示しています。

Apt エラーの例:

Err:1 ar+https://us-central1-apt.pkg.dev/projects/my-project my-package Release
  Error downloading: code 401

E: Failed to fetch https://us-central1-apt.pkg.dev/projects/my-project/dists/quickstart-apt-repo/main/binary-amd64/Packages  403  Forbidden [IP: 74.125.20.82 443]
E: Some index files failed to download. They have been ignored, or old ones used instead.

Yum エラーの例:

/repodata/repomd.xml: [Errno 14] HTTPS Error 403 - Forbidden

これらのエラーの原因として、次のようなことが考えられます。VM が次の要件を満たしていることを確認します。

  1. VM にサービス アカウントが関連付けられていることを確認します。

    Compute Engine VM

    1. [VM インスタンス] ページに移動します。

    2. VM のリストで、VM の名前をクリックします。

      [詳細] タブの [API と ID の管理] に、サービス アカウントとアクセス スコープが表示されます。

    デフォルトでは、Compute Engine VM は Compute Engine のデフォルトのサービス アカウントを使用し、特定のアクセス スコープがあります。デフォルトのサービス アカウントのメールアドレスの形式は PROJECT_NUMBER-compute@developer.gserviceaccount.com です。

    サービス アカウントを変更するか、またはサービス アカウントを VM に接続するには、インスタンスのサービス アカウントとアクセス スコープを変更するをご覧ください。

    その他の VM

    その他の VM の場合は、VM の代理として動作するサービス アカウントが必要です。

    1. サービス アカウントがない場合は、サービス アカウントを作成します。

    2. サービス アカウントの作成時に Artifact Registry 読み取り（roles.artifactregistry.reader）ロールを付与すると、別の手順で権限を構成する必要がなくなります。

  2. VM サービス アカウントに、リポジトリに対する読み取り権限と cloud-platform API アクセス スコープがあることを確認します。

    Compute Engine VM

    Artifact Registry は、VM サービス アカウントの認証情報を自動的に取得します。必要な構成は、デフォルトのサービス アカウントとユーザー管理のサービス アカウントのどちらを使用しているかによって異なります。

    デフォルトのサービス アカウント

    VM がデフォルトのサービス アカウントを使用している場合、このサービス アカウントにはデフォルトで編集者ロールが付与されます。このロールには、同じプロジェクトのリポジトリに対する読み取り権限が含まれています。リポジトリが VM とは異なるプロジェクトにある場合は、VM サービス アカウントに Artifact Registry 読み取りロールを付与します。

    また、デフォルトのサービス アカウントには、必要なすべての API アクセス スコープがありません。

    cloud-platform アクセス スコープを設定するには、

    1. VM インスタンスを停止します。INSTANCE は、VM インスタンス名に置き換えます。

      gcloud compute instances stop INSTANCE

    2. アクセス スコープを設定します。

      gcloud compute instances set-service-account INSTANCE \
    --scopes=cloud-platform

    3. VM インスタンスを再起動します。

      gcloud compute instances start INSTANCE
    ユーザー管理のサービス アカウント
    VM がユーザー管理のサービス アカウントを使用する場合は、VM サービス アカウントに Artifact Registry 読み取りロールを付与します。ユーザー管理サービス アカウントには cloud-platform アクセス スコープがあります。

    その他の VM

    VM サービス アカウントに Artifact Registry 読み取りロールを付与します。デフォルトでは、ユーザー管理サービス アカウントには cloud-platform アクセス スコープがあります。

  3. リポジトリにアクセスできるように VM を準備する手順を実施したことを確認します。Apt または Yum の準備手順をご覧ください。

  4. Apt または Yum がリポジトリにアクセスできるよう正しく構成されていることを確認します。

    Compute Engine VM から Apt リポジトリに接続する場合は、リポジトリ URL に ar+ 接頭辞が含まれていることを確認してください。

認証情報ヘルパーに関する問題

VM が Apt 認証情報ヘルパーを見つけられない場合、次のエラー メッセージが表示されます。

E: Unable to locate package apt-transport-artifact-registry

このエラーは、Apt リポジトリ署名鍵が含まれていないイメージから作成された VM に apt-transport-artifact-registry パッケージをインストールしようとすると発生します。

この問題を解決するには、次の手順を行います。

  1. VM に署名鍵をインストールします。

    Debian VM

    次のコマンドを使用して、Apt リポジトリ署名鍵をインストールします。

    curl https://LOCATION-apt.pkg.dev/doc/repo-signing-key.gpg | sudo apt-key add -

    LOCATION は、リポジトリの場所に置き換えます。

    Ubuntu VM

    次のコマンドを使用して、Apt リポジトリ署名鍵をインストールします。

    curl https://LOCATION-apt.pkg.dev/doc/repo-signing-key.gpg | sudo apt-key add - && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -

    LOCATION は、リポジトリの場所に置き換えます。

  2. VM の準備手順をもう一度試します。

認証プラグインに関する問題

Yum 認証プラグインまたは DNF 認証プラグインに問題がある場合、次のエラー メッセージが表示されます。

Plugin "artifact-registry" can't be imported

このエラーは、いくつかの原因で発生します。このエラーを解決するには、プラグインを直接実行して依存関係を確認し、Python の問題がないかを確認するか、その他の根本的な問題を明らかにします。

プラグインを直接実行するには、次のいずれかのコマンドを使用します。

  • Yum プラグインの場合:

    python /usr/lib/yum-plugins/artifact-registry.py

  • DNF プラグインの場合:

    python3 /usr/lib/pythonVERSION-NUMBER/site-packages/dnf-plugins/artifact-registry.py

    VERSION-NUMBER は、Linux ディストリビューションのデフォルトの Python バージョンに置き換えます。たとえば、Enterprise Linux 8 には Python 3.6 が含まれています。

    インストールされたプラグイン パッケージ内のファイルを一覧表示して、Python ライブラリ ディレクトリの名前を確認できます。

    rpm -ql dnf-plugin-artifact-registry|grep artifact-registry.py

最近アップロードしたアーティファクトがない

Apt または Yum クライアントで、最近リポジトリにアップロードまたはインポートされたパッケージが見つからない場合は、Apt または Yum パッケージ インデックスの再生成プロセスがまだ完了していない可能性があります。

小規模なリポジトリの場合、Apt または Yum インデックス ファイルの再生成に数秒かかることがあります。大規模なリポジトリの場合、再インデックス化に数分以上かかることがあります。

パッケージがリポジトリに正常に追加されたことを確認するには、Google Cloud CLI を使用してパッケージ内のファイルを一覧表示します。次のコマンドを実行します。

gcloud artifacts files list \
    --package=PACKAGE \
    --project=PROJECT-ID \
    --repository=REPOSITORY \
    --location=LOCATION

たとえば、python3-gflags_1.5.1-5_all.deb という名前の python-gflags パッケージがリポジトリ us-central1-apt.pkg.dev\apt-project\apt-repo に正常にアップロードされたことを確認するには、次のコマンドを使用します。

gcloud artifacts files list \
    --package=python-gflags \
    --project=apt-project \
    --repository=apt-repo \
    --location=us-central1

パッケージが正常にアップロードされると、ファイル名に一意の識別子を持つファイルが出力に表示されます。次に例を示します。

FILE                                                                  CREATE_TIME          UPDATE_TIME          SIZE (MB)  OWNER
pool/python3-gflags_1.5.1-5_all_2414c7af6a64c99a5f488aad366d637a.deb  2023-01-12T20:39:53  2023-01-12T20:39:53  0.035      projects/apt-project/locations/us-central1/repositories/apt-repo/packages/python3-gflags/versions/1.5.1-5

アップロードまたはインポートした一部のパッケージで認証エラーが発生する

ファイルのインポートまたはアップロードに要する時間が認証トークンの有効期限を超えると、有効期限を超えたアップロードは失敗します。トークンは取得後 60 分で期限切れになります。トークンが期限切れの場合、インポート コマンドの出力に次のようなエラーが表示されます。

errors:
- error:
    code: 16
    message: The request does not have valid authentication credentials.
  gcsSource:
    uris:
    - gs://my-bucket/debs/python/python3-gflags_1.5.1-5_all.deb

この問題を解決するには:

  1. 特定のパッケージをアップロードまたはインポートして、一括インポートではなく、パッケージを個別に追加できるかどうか確認します。
  2. 複数のパッケージでエラーが発生した場合は、オペレーションでトークンの有効期限が切れないように、小さいバッチでインポートまたはアップロードします。