仮想リポジトリを作成する

このページでは、Artifact Registry 仮想リポジトリを作成する方法について説明します。

仮想リポジトリは、1 つ以上のアップストリーム リポジトリから同じ形式でアーティファクトをダウンロード、インストール、デプロイするための単一のアクセス ポイントとして機能します。アップストリーム リポジトリは、Artifact Registry の標準リポジトリまたはリモート リポジトリになります。

その他のリポジトリ モードは以下のとおりです。

  • 標準: デフォルトのリポジトリ モード。標準リポジトリに非公開パッケージなどのアーティファクトを直接アップロードまたは公開します。ダウンロードは個々の標準リポジトリから直接行えますが、仮想リポジトリでリポジトリのグループにアクセスするとツールの構成が簡素化されます。
  • リモート(言語パッケージのリポジトリのみ): Maven Central や PyPI などの公開リポジトリ内のアーティファクトのプルスル― キャッシュ。 外部依存関係をより細かく制御できるようにパブリック リポジトリのプロキシとして機能します。

仮想リポジトリの仕組みの詳細については、仮想リポジトリの概要をご覧ください。

準備

Artifact Registry を有効にします。これには Artifact Registry API の有効化と、最新バージョンの Google Cloud CLI のインストールが含まれます。

必要なロール

リポジトリの管理に必要な権限を取得するには、次に挙げる IAM ロールの付与を、管理者に依頼してください。

  • 仮想リポジトリを作成し、個々のリポジトリにアクセス権を付与する: Google Cloud プロジェクトの Artifact Registry リポジトリ管理者roles/artifactregistry.repoAdmin
  • プロジェクト レベルでリポジトリへのアクセス権を付与する: Google Cloud プロジェクトのプロジェクト IAM 管理者roles/resourcemanager.projectIamAdmin
  • フォルダレベルでリポジトリへのアクセス権を付与する: そのフォルダのフォルダ管理者roles/resourcemanager.folderAdmin
  • 組織レベルでリポジトリへのアクセス権を付与する: Google Cloud 組織の組織管理者roles/resourcemanager.organizationAdmin

ロールの付与の詳細については、アクセスの管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

アップストリーム リポジトリが他のプロジェクトにある場合、アップストリーム リポジトリを含むプロジェクトの管理者は、それらのリポジトリへのアクセス権を管理する権限を持っている必要があります。

アップストリーム リポジトリを作成する

仮想リポジトリを設定する前に、仮想リポジトリで利用可能にするアップストリーム リポジトリを作成します。

  1. 仮想リポジトリを作成する予定の Google Cloud リージョンにアップストリーム リポジトリを作成します。

  2. 仮想リポジトリは、Artifact Registry サービス エージェントを使用して、アップストリーム リポジトリに対する認証を行います。サービス エージェントには、アップストリーム リポジトリへの読み取りアクセス権を付与する必要があります。

    Artifact Registry 読み取りロールは、プロジェクト レベルで Artifact Registry サービス エージェントに付与できるため、個々のアップストリーム リポジトリへのアクセス権を付与する必要はありません。

    アップストリーム リポジトリを持つ各プロジェクトで、次のコマンドを実行します。

    gcloud projects add-iam-policy-binding UPSTREAM_PROJECT_ID \
        --member serviceAccount:service-VIRTUAL-REPO-PROJECT_NUMBER@gcp-sa-artifactregistry.iam.gserviceaccount.com \
        --role roles/artifactregistry.reader
    

    Where

    • UPSTREAM_PROJECT_ID は、アップストリーム リポジトリを持つ Google Cloud プロジェクトの ID です。
    • VIRTUAL_REPO_PROJECT_NUMBER は、仮想リポジトリの Google Cloud プロジェクトのプロジェクト番号です。

    さらに範囲を限定したロールをサービス エージェントに付与する場合は、権限 artifactregistry.repositories.readViaVirtualRepository をカスタムロールに追加して、そのロールをサービス エージェントに付与します。

    権限の付与の詳細については、アクセス制御のドキュメントをご覧ください。

仮想リポジトリを作成する

リポジトリを作成する際は、次の設定を構成する必要があります。この設定は、リポジトリの作成後に変更できません。

  • アーティファクトの形式。
  • リポジトリ モード(選択した形式で複数のモードが使用可能な場合)。
  • リポジトリのロケーション
  • Google が管理する鍵または顧客管理の暗号鍵による暗号化。Artifact Registry は、デフォルトで Google が管理する暗号鍵を使用します。

Artifact Registry では組織のポリシーの制約が適用され、CMEK でリソースを暗号化するか、CMEK の保護に使用できる Cloud KMS 鍵を制限する必要があります。

Google Cloud コンソールを使用して仮想リポジトリを作成する

  1. Google Cloud コンソールで [リポジトリ] ページを開きます。

    [リポジトリ] ページを開く

  2. [リポジトリを作成] をクリックします。

  3. リポジトリ名を指定します。プロジェクト内のリポジトリの場所ごとに、リポジトリ名は一意であることが必要です。

  4. リポジトリの形式を選択します。

  5. [リポジトリ モード] で、[仮想] を選択します。

  6. [仮想リポジトリのアップストリーム] で、[アップストリームを追加] をクリックしてアップストリーム リポジトリを追加します。

    • アップストリーム リポジトリは、標準リポジトリ、リモート リポジトリ、または仮想リポジトリになります。
    • アップストリーム リポジトリは、仮想リポジトリと同じロケーションに存在する必要がありますが、異なる Google Cloud プロジェクトに配置できます。
    • アップストリーム リポジトリは、仮想リポジトリと同じアーティファクト形式でなければなりません。

    アップストリーム リポジトリごとに優先度とポリシー名を指定します。優先度の高い値は、低い値よりも優先されます。優先度と優先度の間に空きを作ることで、既存の値の中間の優先度を持つアップストリーム リポジトリを柔軟に追加できるようにします。

  7. [ロケーション タイプ] でリポジトリのロケーションを選択します。

    1. ロケーション タイプには、[リージョン] または [マルチリージョン] を選択します。ロケーションのリストは、選択した内容に応じて変わります。

    2. [リージョン] リストまたは [マルチリージョン] リストでロケーションを選択します。

    ロケーション タイプとサポートされているロケーションについては、リポジトリのロケーションをご覧ください。

  8. リポジトリの説明を追加します。説明は、リポジトリの目的とリポジトリに含まれるアーティファクトの種類の識別に役立ちます。

    リポジトリの説明は暗号化されないため、機密データは含めないでください。

  9. ラベルを使用してリポジトリを整理する場合は、[ラベルを追加] をクリックしてラベルの Key-Value ペアを入力します。リポジトリを作成した後にラベルを追加、編集、削除できます。

  10. [暗号化] セクションで、リポジトリの暗号化方式を選択します。

    • Google が管理する鍵 - Google が管理する暗号鍵を使用してリポジトリのコンテンツを暗号化します。
    • 顧客管理の暗号鍵 - Cloud Key Management Service で管理する鍵を使用してリポジトリのコンテンツを暗号化します。鍵の設定手順については、リポジトリの CMEK の設定をご覧ください。
  11. [作成] をクリックします。

Artifact Registry でリポジトリが作成され、リポジトリのリストに追加されます。

リポジトリを作成した後は:

gcloud CLI を使用して仮想リポジトリを作成する

仮想リポジトリを作成するには、ポリシー ファイルでアップストリーム リポジトリを定義し、ポリシー ファイルを使用してリポジトリを作成します。

  1. 次の設定を使用して JSON 形式でアップストリーム ポリシー ファイルを作成します。

    [{
    "id" : "POLICY_ID",
    "repository" : "UPSTREAM_REPOSITORY_RESOURCE_NAME",
    "priority" : PRIORITY
    }, {...}]
    
    • POLICY_ID はポリシーの名前です。ポリシーの各アップストリーム リポジトリには、一意のポリシー ID が必要です。
    • UPSTREAM_REPO_RESOURCE_NAME はアップストリーム リポジトリの名前です。形式は次のとおりです。

      projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY
      
      • アップストリーム リポジトリは、標準リポジトリ、リモート リポジトリ、または仮想リポジトリになります。
      • アップストリーム リポジトリは、仮想リポジトリと同じロケーションに存在する必要がありますが、異なる Google Cloud プロジェクトに配置できます。
      • アップストリーム リポジトリは、仮想リポジトリと同じアーティファクト形式でなければなりません。
    • PRIORITY は、アップストリーム リポジトリの優先度を示す整数です。優先度の高い値は、低い値よりも優先されます。

    次の例では、4 つのアップストリーム リポジトリを含む policies.json という名前のポリシー ファイルを示します。upstream1priority の値が最も高いため、Artifact Registry が最初に検索します。upstream-testpriority 値が最も低いため、Artifact Registry が最後に検索します。upstream2upstream3 の優先度は同じです。Artifact Registry が同じ優先度を持つリポジトリでリクエストされたパッケージを検出した場合、パッケージはどちらのリポジトリからでも提供できます。

    [{
    "id" : "upstream1",
    "repository" : "projects/myproject/locations/us-west1/repositories/python-repo1",
    "priority" : 100
    }, {
    "id" : "upstream2",
    "repository" : "projects/myproject/locations/us-west1/repositories/python-repo2",
    "priority" : 80
    }, {
    "id" : "upstream3",
    "repository" : "projects/myproject/locations/us-west1/repositories/python-repo2",
    "priority" : 80
    }, {
    "id" : "upstream-test",
    "repository" : "projects/myproject/locations/us-west1/repositories/python-test-repo",
    "priority" : 20
    }]
    

    この例では、優先度の間に空きもあります。こうした空きにより、既存の値の中間の優先度を持つアップストリーム リポジトリを柔軟に追加できます。たとえば、優先度 70upstream-3 リポジトリを追加して、Artifact Registry で upstream-test より前に検索されるようにできます。

    アップストリーム ポリシー ファイルを後で再利用してアップストリーム リポジトリ設定を変更し、変更の履歴を追跡できるように、アップストリーム ポリシー ファイルはソース管理システムに保存することを検討してください。

  2. アップストリーム ポリシー ファイルがあるディレクトリで、次のコマンドを実行して仮想リポジトリを作成します。

    gcloud artifacts repositories create VIRTUAL-REPOSITORY-NAME \
        --project=PROJECT_ID \
        --repository-format=FORMAT \
        --mode=virtual-repository \
        --location=LOCATION \
        --description="DESCRIPTION" \
        --upstream-policy-file=UPSTREAM_POLICY_FILE
    

    以下を置き換えます。

    • VIRTUAL-REPOSITORY-NAME は仮想リポジトリの名前です。
    • PROJECT_ID は、仮想リポジトリを作成するプロジェクトの ID です。このフラグを省略すると、現在のプロジェクトまたはデフォルトのプロジェクトが使用されます。
    • FORMAT は、リポジトリの形式です。指定できる値は次のとおりです。
      • apt(限定公開プレビュー)
      • docker
      • maven
      • npm
      • python
      • yum(限定公開プレビュー)
    • LOCATION は、リポジトリのリージョンまたはマルチリージョンのロケーションです。デフォルトを設定すると、このフラグを省略できます。サポートされているロケーションの一覧を表示するには、次のコマンドを実行します。

      gcloud artifacts locations list
      
    • DESCRIPTION は、リポジトリの省略可能な説明です。リポジトリの説明は暗号化されないため、機密データは含めないでください。

    • UPSTREAM_POLICY_FILE は、アップストリーム ポリシー ファイルへのパスです。

    たとえば、次のコマンドは、リージョン us-west1 の Python パッケージに virtual-repo という仮想リポジトリを作成し、policies.json を設定します。

    gcloud artifacts repositories create virtual-repo \
    --repository-format=python \
    --mode=virtual-repository \
    --location=us-west1 \
    --description="Python virtual repository" \
    --upstream-policy-file=policies.json
    

Artifact Registry が仮想リポジトリを作成します。

Terraform を使用して仮想リポジトリを作成する

google_artifact_registry_repository リソースを使用してリポジトリを作成します。terraform-provider-google バージョン 5.0.0 以降が必要です。

Google Cloud で Terraform を初めて使用する場合は、HashiCorp ウェブサイトの Google Cloud スタートガイド ページをご覧ください。

次の例では、プロバイダ、Terraform リソース名が my-repo の仮想リポジトリ、Terraform リソース名が my-repo-upstream のアップストリーム リポジトリを定義します。

Docker

provider "google" {
    project = "PROJECT-ID"
}
resource "google_artifact_registry_repository" "my-repo-upstream" {
  location      = "UPSTREAM_LOCATION"
  repository_id = "UPSTREAM_REPOSITORY_ID"
  description   = "UPSTREAM_REPOSITORY_DESCRIPTION"
  format        = "docker"
}

resource "google_artifact_registry_repository" "my-repo" {
  depends_on    = []
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "VIRTUAL_REPOSITORY_DESCRIPTION"
  format        = "docker"
  kms_key_name = "KEY"
  mode          = "VIRTUAL_REPOSITORY"
  virtual_repository_config {
    upstream_policies {
      id          = "UPSTREAM_REPOSITORY_ID"
      repository  = google_artifact_registry_repository.my-repo-upstream.id
      priority    = PRIORITY
    }
  }
}

ここで

  • PROJECT-ID は、Google Cloud プロジェクト ID です。
  • UPSTREAM_LOCATION は、アップストリーム リポジトリのロケーションです。仮想リポジトリとアップストリームは同じリージョンまたはマルチリージョンに存在する必要があります。
  • UPSTREAM_REPOSITORY_ID は、アップストリーム リポジトリの ID です。
  • UPSTREAM_REPOSITORY_DESCRIPTION は、アップストリーム リポジトリの省略可能な説明です。
  • LOCATION は仮想リポジトリのロケーションです。
  • REPOSITORY_ID は仮想リポジトリ ID です。
  • DESCRIPTION は仮想リポジトリの説明です(省略可能)。リポジトリの説明は暗号化されないため、機密データは含めないでください。
  • KEY は、Cloud Key Management Service 鍵の名前です(暗号化に顧客管理の暗号鍵(CMEK)を使用している場合)。デフォルト設定(Google が管理する暗号鍵)を使用する場合は、この引数を省略します。
  • PRIORITY は、省略可能な優先度値です。優先度が最も高いのは 1 です。優先度の高い値のエントリは pull 順序で優先されます。

Maven

バージョン ポリシーを指定しない場合は、Artifact Registry によってデフォルトでパッケージのスナップショットとリリース バージョンの両方を保存する Maven リポジトリが作成されます。

provider "google" {
    project = "PROJECT-ID"
}
resource "google_artifact_registry_repository" "my-repo-upstream" {
  location      = "UPSTREAM_LOCATION"
  repository_id = "UPSTREAM_REPOSITORY_ID"
  description   = "UPSTREAM_REPOSITORY_DESCRIPTION"
  format        = "maven"
}

resource "google_artifact_registry_repository" "my-repo" {
  depends_on    = []
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "VIRTUAL_REPOSITORY_DESCRIPTION"
  format        = "maven"
  kms_key_name = "KEY"
  mode          = "VIRTUAL_REPOSITORY"
  virtual_repository_config {
    upstream_policies {
      id          = "UPSTREAM_REPOSITORY_ID"
      repository  = google_artifact_registry_repository.my-repo-upstream.id
      priority    = PRIORITY
    }
  }
}

Where

  • PROJECT-ID は、Google Cloud プロジェクト ID です。
  • UPSTREAM_LOCATION は、アップストリーム リポジトリのロケーションです。仮想リポジトリとアップストリームは同じリージョンまたはマルチリージョンに存在する必要があります。
  • UPSTREAM_REPOSITORY_ID は、アップストリーム リポジトリの ID です。
  • UPSTREAM_REPOSITORY_DESCRIPTION は、アップストリーム リポジトリの省略可能な説明です。
  • LOCATION は仮想リポジトリのロケーションです。
  • REPOSITORY_ID は仮想リポジトリ ID です。
  • DESCRIPTION は仮想リポジトリの説明です(省略可能)。リポジトリの説明は暗号化されないため、機密データは含めないでください。
  • KEY は、Cloud Key Management Service 鍵の名前です(暗号化に顧客管理の暗号鍵(CMEK)を使用している場合)。デフォルト設定(Google が管理する暗号鍵)を使用する場合は、この引数を省略します。
  • PRIORITY は、省略可能な優先度値です。優先度が最も高いのは 1 です。優先度の高い値のエントリは pull 順序で優先されます。

スナップショットとリリース バージョンを別々のリポジトリに保存するには、maven_config ブロックを使用してリポジトリのバージョン ポリシーを指定します。このブロックは、次の設定をサポートしています。

  • version_policy は、バージョン ポリシーに次のいずれかの値を設定します。
    • VERSION_POLICY_UNSPECIFIED: スナップショットとリリース パッケージを保存します。これはデフォルトの設定です。
    • RELEASE: リリース パッケージのみを保存します。
    • SNAPSHOT: スナップショット パッケージのみを保存します。
  • allow_snapshot_overwrites は、SNAPSHOT バージョン ポリシーで、リポジトリ内の既存のバージョンを上書きする一意でないスナップショットを受け入れるようにリポジトリを構成します。

次の例では、リリース バージョン ポリシーを持つ Maven リポジトリを定義しています。

provider "google" {
project = "my-project"
}

resource "google_artifact_registry_repository" "my-repo" {
provider = google-beta

location = "us-central1"
repository_id = "my-repo"
description = "Maven repository"
format = "MAVEN"
maven_config {
  version_policy = "RELEASE"
}
}

npm

provider "google" {
    project = "PROJECT-ID"
}
resource "google_artifact_registry_repository" "my-repo-upstream" {
  location      = "UPSTREAM_LOCATION"
  repository_id = "UPSTREAM_REPOSITORY_ID"
  description   = "UPSTREAM_REPOSITORY_DESCRIPTION"
  format        = "npm"
}

resource "google_artifact_registry_repository" "my-repo" {
  depends_on    = []
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "VIRTUAL_REPOSITORY_DESCRIPTION"
  format        = "npm"
  kms_key_name = "KEY"
  mode          = "VIRTUAL_REPOSITORY"
  virtual_repository_config {
    upstream_policies {
      id          = "UPSTREAM_REPOSITORY_ID"
      repository  = google_artifact_registry_repository.my-repo-upstream.id
      priority    = PRIORITY
    }
  }
}

ここで

  • PROJECT-ID は、Google Cloud プロジェクト ID です。
  • UPSTREAM_LOCATION は、アップストリーム リポジトリのロケーションです。仮想リポジトリとアップストリームは同じリージョンまたはマルチリージョンに存在する必要があります。
  • UPSTREAM_REPOSITORY_ID は、アップストリーム リポジトリの ID です。
  • UPSTREAM_REPOSITORY_DESCRIPTION は、アップストリーム リポジトリの省略可能な説明です。
  • LOCATION は仮想リポジトリのロケーションです。
  • REPOSITORY_ID は仮想リポジトリ ID です。
  • DESCRIPTION は仮想リポジトリの説明です(省略可能)。リポジトリの説明は暗号化されないため、機密データは含めないでください。
  • KEY は、Cloud Key Management Service 鍵の名前です(暗号化に顧客管理の暗号鍵(CMEK)を使用している場合)。デフォルト設定(Google が管理する暗号鍵)を使用する場合は、この引数を省略します。
  • PRIORITY は、省略可能な優先度値です。優先度が最も高いのは 1 です。優先度の高い値のエントリは pull 順序で優先されます。

Python

provider "google" {
    project = "PROJECT-ID"
}
resource "google_artifact_registry_repository" "my-repo-upstream" {
  location      = "UPSTREAM_LOCATION"
  repository_id = "UPSTREAM_REPOSITORY_ID"
  description   = "UPSTREAM_REPOSITORY_DESCRIPTION"
  format        = "python"
}

resource "google_artifact_registry_repository" "my-repo" {
  depends_on    = []
  location      = "LOCATION"
  repository_id = "REPOSITORY_ID"
  description   = "VIRTUAL_REPOSITORY_DESCRIPTION"
  format        = "python"
  kms_key_name = "KEY"
  mode          = "VIRTUAL_REPOSITORY"
  virtual_repository_config {
    upstream_policies {
      id          = "UPSTREAM_REPOSITORY_ID"
      repository  = google_artifact_registry_repository.my-repo-upstream.id
      priority    = PRIORITY
    }
  }
}

ここで

  • PROJECT-ID は、Google Cloud プロジェクト ID です。
  • UPSTREAM_LOCATION は、アップストリーム リポジトリのロケーションです。仮想リポジトリとアップストリームは同じリージョンまたはマルチリージョンに存在する必要があります。
  • UPSTREAM_REPOSITORY_ID は、アップストリーム リポジトリの ID です。
  • UPSTREAM_REPOSITORY_DESCRIPTION は、アップストリーム リポジトリの省略可能な説明です。
  • LOCATION は仮想リポジトリのロケーションです。
  • REPOSITORY_ID は仮想リポジトリ ID です。
  • DESCRIPTION は仮想リポジトリの説明です(省略可能)。リポジトリの説明は暗号化されないため、機密データは含めないでください。
  • KEY は、Cloud Key Management Service 鍵の名前です(暗号化に顧客管理の暗号鍵(CMEK)を使用している場合)。デフォルト設定(Google が管理する暗号鍵)を使用する場合は、この引数を省略します。
  • PRIORITY は、省略可能な優先度値です。優先度が最も高いのは 1 です。優先度の高い値のエントリは pull 順序で優先されます。

Artifact Registry がリポジトリを作成します。次のコマンドを実行してリポジトリの説明を表示します。

gcloud artifacts repositories describe REPOSITORY \
    --location=LOCATION

リポジトリを作成した後は:

アップストリーム リポジトリを更新する

アップストリーム リポジトリのリストを変更することや、アップストリーム リポジトリの優先度を調整することができます。

コンソール

  1. Google Cloud コンソールで [リポジトリ] ページを開きます。

    [リポジトリ] ページを開く

  2. リポジトリ リストで仮想リポジトリを選択し、[リポジトリを編集] をクリックします。

  3. [Virtual Repository Upstream] リストで、必要な変更を行います。 リスト内のリポジトリの追加と削除や、優先度の変更ができます。

  4. [保存] をクリックします。

gcloud

  1. 変更を加えてアップストリーム ポリシー ファイルを編集します。たとえば、アップストリーム リポジトリの追加や優先度設定の調整などが考えられます。

    すべてのアップストリーム リポジトリを削除する場合は、ポリシー ファイルに空のリポジトリのセットが含まれている必要があります。

    []
    
  2. 次のコマンドを実行して変更を仮想リポジトリに適用します。

    gcloud artifacts repositories update REPOSITORY \
        --upstream-policy-file=UPSTREAM_POLICY_FILE
    

    UPSTREAM_POLICY_FILE は、アップストリーム ポリシー ファイルへのパスに置き換えます。

    このコマンドの詳細については、リファレンス ドキュメントのgcloud artifacts リポジトリの更新をご覧ください。

リポジトリの説明を編集する

リポジトリの説明は、Google Cloud コンソールか gcloud CLI から変更できます。

Console

  1. Google Cloud コンソールで [リポジトリ] ページを開きます。

    [リポジトリ] ページを開く

  2. リポジトリ リストでリポジトリを選択し、[リポジトリを編集] をクリックします。

  3. リポジトリの説明を編集し、[保存] をクリックします。

gcloud

リポジトリの説明を更新するには次のコマンドを実行します。

gcloud artifacts repositories update REPOSITORY \
    --project=PROJECT \
    --location=LOCATION \
    --description="DESCRIPTION"

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

  • REPOSITORY: リポジトリの名前 デフォルト リポジトリを構成した場合は、このフラグを省略してデフォルトを使用できます。
  • PROJECT: Google Cloud プロジェクト ID。 このフラグを省略すると、現在のプロジェクトまたはデフォルトのプロジェクトが使用されます。
  • LOCATION: リージョンまたはマルチリージョンの ロケーション。このフラグを使用して、特定のロケーションのリポジトリを表示します。デフォルト ロケーションを構成している場合は、このフラグを省略してデフォルトを使用できます。
  • DESCRIPTION: リポジトリの説明。