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

このページでは、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
    }]
    

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

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

  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. [仮想リポジトリのアップストリーム] リストで、必要な変更を行います。リスト内のリポジトリの追加と削除や、優先度の変更ができます。

  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 は、リポジトリの説明です。