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 とは異なるプロジェクトにある場合、Artifact Registry 読み取りのロールを VM サービス アカウントに付与します。

    また、デフォルトのサービス アカウントには、必要な 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 でユーザーが管理するサービス アカウントを使用する場合は、Artifact Registry 読み取りのロールを VM サービス アカウントに付与します。ユーザー管理のサービス アカウントには、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. 複数のパッケージが失敗した場合は、インポートやアップロードを小さなバッチ単位で行い、オペレーションがトークンの有効期限を超えないようにします。