ダウンロード ルールを使用してアーティファクトのダウンロードを制限する

このページでは、ダウンロード ルールを作成して管理することで、Artifact Registry リポジトリからのアーティファクトのダウンロードを制限する方法について説明します。

ダウンロード ルールを使用すると、リポジトリとパッケージからのアーティファクトのダウンロードを許可または拒否できます。特定のタグまたはバージョンにルールを適用するように条件を設定することもできます。

ダウンロード ルールの仕組みの詳細については、アクセスを制御してアーティファクトを保護する概要のアーティファクトのダウンロードを制限するをご覧ください。

始める前に

  1. まだ作成していない場合は、Docker 形式の標準リポジトリを作成します。
  2. (省略可)Google Cloud CLI コマンドのデフォルトを構成します。

必要なロール

ダウンロード ルールの作成と管理に必要な権限を取得するには、リポジトリに対する次の IAM ロールの付与を管理者に依頼してください。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

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

ダウンロード ルールを作成する

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

  • RULE_NAME: ルールの名前。名前はリポジトリ内で一意で、最大 256 文字で、英数字、パーセント エンコード文字、または [-._~:@+^] のリスト内の文字で構成する必要があります。
  • ACTION: このルールに一致するダウンロードに適用されるアクション。ALLOW(ルールで一致するダウンロードを許可)と DENY(ルールで一致するダウンロードをブロック)のいずれかを選択します。
  • PACKAGE:(省略可)パッケージの名前。指定した場合、ルールはリポジトリ全体ではなく、指定したパッケージにのみ適用されます。
  • CONDITION: (省略可)一致ルールを定義する CEL 式。指定した場合、指定した条件に一致するダウンロードにのみルールが適用されます。例: pkg.version.id < '3.0'
  • PROJECT: Google Cloud プロジェクト ID。プロジェクト ID にコロン(:)が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
  • LOCATION: リポジトリのリージョンまたはマルチリージョンのロケーション
  • REPOSITORY: リポジトリ ID。

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

Linux、macOS、Cloud Shell

gcloud artifacts rules create RULE_NAME \
    --action=ACTION \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY \
    --package=PACKAGE \
    --condition="CONDITION"

Windows(PowerShell)

gcloud artifacts rules create RULE_NAME `
    --action=ACTION `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY `
    --package=PACKAGE `
    --condition="CONDITION"

Windows(cmd.exe)

gcloud artifacts rules create RULE_NAME ^
    --action=ACTION ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY ^
    --package=PACKAGE ^
    --condition="CONDITION"
新しいルールが作成され、次の出力が生成されます。
Created rule [RULE_NAME].
詳細については、gcloud artifacts rules create コマンドをご覧ください。

API

リクエストのデータを使用する前に、次のように置き換えます。

  • RULE_NAME: ルールの名前。名前はリポジトリ内で一意で、最大 256 文字で、英数字、パーセント エンコード文字、または [-._~:@+^] のリスト内の文字で構成する必要があります。
  • ACTION: このルールに一致するダウンロードに適用されるアクション。ALLOW(ルールで一致するダウンロードを許可)と DENY(ルールで一致するダウンロードをブロック)のいずれかを選択します。
  • PACKAGE:(省略可)パッケージの名前。指定した場合、ルールはリポジトリ全体ではなく、指定したパッケージにのみ適用されます。
  • CONDITION: (省略可)一致ルールを定義する CEL 式。指定した場合、指定した条件に一致するダウンロードにのみルールが適用されます。例: pkg.version.id < '3.0'
  • PROJECT: Google Cloud プロジェクト ID。プロジェクト ID にコロン(:)が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
  • LOCATION: リポジトリのリージョンまたはマルチリージョンのロケーション
  • REPOSITORY: リポジトリ ID。

HTTP メソッドと URL:

POST https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules?ruleID=RULE_NAME

リクエストの本文(JSON):

{
  "action":"ACTION",
  "packageId":"PACKAGE",
  "condition":
  {
    "expression":"CONDITION"
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

新しいルールが作成され、次の出力が生成されます。
{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}
詳細については、REST リファレンスをご覧ください。

ダウンロード ルールを一覧表示する

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

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

Linux、macOS、Cloud Shell

gcloud artifacts rules list \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY

Windows(PowerShell)

gcloud artifacts rules list `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY

Windows(cmd.exe)

gcloud artifacts rules list ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY
指定したプロジェクト、ロケーション、リポジトリのルールのリストが次のように表示されます。
RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'
詳細については、gcloud artifacts rules list コマンドをご覧ください。

API

リクエストのデータを使用する前に、次のように置き換えます。

HTTP メソッドと URL:

GET https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules

リクエストを送信するには、次のいずれかのオプションを展開します。

指定したプロジェクト、ロケーション、リポジトリのルールのリストが次のように表示されます。
{
  "rules": [
    {
      "name": "projects/my-project/locations/us-central1/repositories/my-repo/rules/my-rule",
      "action": "DENY",
      "operation": "DOWNLOAD",
      "condition": {
        "expression": "pkg.version.id \u003c '3.0'"
      },
      "packageId": "example.com/foo"
    }
  ]
}
詳細については、REST リファレンスをご覧ください。

ダウンロード ルールの説明を取得する

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

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

Linux、macOS、Cloud Shell

gcloud artifacts rules describe RULE_NAME \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY

Windows(PowerShell)

gcloud artifacts rules describe RULE_NAME `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY

Windows(cmd.exe)

gcloud artifacts rules describe RULE_NAME ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY
ルールの詳細は、次のように表示されます。
RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'
詳細については、gcloud artifacts rules describe コマンドをご覧ください。

API

リクエストのデータを使用する前に、次のように置き換えます。

HTTP メソッドと URL:

GET https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME

リクエストを送信するには、次のいずれかのオプションを展開します。

Rule の詳細は、次のように表示されます。
{
  "rules": [
    {
      "name": "projects/my-project/locations/us-central1/repositories/my-repo/rules/my-rule",
      "action": "DENY",
      "operation": "DOWNLOAD",
      "condition": {
        "expression": "pkg.version.id \u003c '3.0'"
      },
      "packageId": "example.com/foo"
    }
  ]
}
詳細については、REST リファレンスをご覧ください。

ダウンロード ルールを更新する

gcloud

更新しない変数は削除します。

後述のコマンドデータを使用する前に、次のように置き換えます。

  • RULE_NAME: ルールの名前。名前はリポジトリ内で一意である必要があります。
  • ACTION: このルールに一致するダウンロードに適用されるアクション。ALLOWDENY の範囲内で選択してください。
  • PACKAGE: パッケージの名前。指定しない場合、ルールはリポジトリ全体に適用されます。
  • CONDITION: 一致ルールを定義する CEL 式。指定した場合、指定した条件に一致するダウンロードにのみルールが適用されます。例: pkg.version.id < '3.0'
  • PROJECT: Google Cloud プロジェクト ID。プロジェクト ID にコロン(:)が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
  • LOCATION: リポジトリのリージョンまたはマルチリージョンのロケーション
  • REPOSITORY: リポジトリの名前。

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

Linux、macOS、Cloud Shell

gcloud artifacts rules update RULE_NAME \
    --action=ACTION \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY \
    --package=PACKAGE \
    --condition="CONDITION"

Windows(PowerShell)

gcloud artifacts rules update RULE_NAME `
    --action=ACTION `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY `
    --package=PACKAGE `
    --condition="CONDITION"

Windows(cmd.exe)

gcloud artifacts rules update RULE_NAME ^
    --action=ACTION ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY ^
    --package=PACKAGE ^
    --condition="CONDITION"
更新されたルールの詳細は、次のように表示されます。
Updated rule [RULE_NAME].
action: ACTION
condition:
  expression: CONDITION
name: projects/PROJECT/locationsLOCATION/repositories/REPOSITORY/rules/RULE_NAME
operation: DOWNLOAD
詳細については、gcloud artifacts rules update コマンドをご覧ください。

API

更新しない変数を削除します。

リクエストのデータを使用する前に、次のように置き換えます。

  • RULE_NAME: ルールの名前。名前はリポジトリ内で一意である必要があります。
  • ACTION: このルールに一致するダウンロードに適用されるアクション。ALLOWDENY の範囲内で選択してください。
  • PACKAGE: パッケージの名前。指定しない場合、ルールはリポジトリ全体に適用されます。
  • CONDITION: 一致ルールを定義する CEL 式。指定した場合、指定した条件に一致するダウンロードにのみルールが適用されます。例: pkg.version.id < '3.0'
  • PROJECT: Google Cloud プロジェクト ID。プロジェクト ID にコロン(:)が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
  • LOCATION: リポジトリのリージョンまたはマルチリージョンのロケーション
  • REPOSITORY: リポジトリの名前。

HTTP メソッドと URL:

PATCH https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME

リクエストの本文(JSON):

{
  "action":"ACTION",
  "packageId":"PACKAGE",
  "condition":
  {
    "expression":"CONDITION"
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

更新されたルールの詳細は、次のように表示されます。
{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}
詳細については、REST リファレンスをご覧ください。

ダウンロード ルールを削除する

gcloud

後述のコマンドデータを使用する前に、次のように置き換えます。

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

Linux、macOS、Cloud Shell

gcloud artifacts rules describe RULE_NAME \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY

Windows(PowerShell)

gcloud artifacts rules describe RULE_NAME `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY

Windows(cmd.exe)

gcloud artifacts rules describe RULE_NAME ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY
ルールが削除され、次の出力が表示されます。
You are about to delete rule [RULE_NAME]

Do you want to continue (Y/n)?  Y

Deleted rule [RULE_NAME].
詳細については、gcloud artifacts rules delete コマンドをご覧ください。

API

リクエストのデータを使用する前に、次のように置き換えます。

HTTP メソッドと URL:

DELETE https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME

リクエストを送信するには、次のいずれかのオプションを展開します。

詳細については、REST リファレンスをご覧ください。

CEL を使用して条件を定義する

ダウンロード ルールの条件は、式の評価用のオープンソース言語である Common Expression Language(CEL)で定義できます。Artifact Registry には、次の属性を含む pkg オブジェクトが用意されています。

  • pkg.id: アーティファクトのパッケージ名を表す文字列。リポジトリ レベルで設定されたルールで使用できます。
  • pkg.version.id: アーティファクトのバージョンを表す文字列。
  • pkg.version.tag: アーティファクトのタグを表す文字列。Docker リポジトリでのみ使用します。

CEL では、論理演算子と組み込み関数を使用できます。ダウンロード ルールで役立つ CEL 式の例を次に示します。

  • リポジトリ レベルで設定するルールに便利です。

      pkg.id == 'myPackage'  #Artifact package matches 'myPackage'
      pkg.id.startsWith('my') #Artifact package must start with 'my'
    
  • パッケージに設定されたルールに役立ちます。

      pkg.version.id != '1.0.0' #Artifact version is not '1.0.0'
      pkg.version.id > '1.0.1' || pkg.version.id < '0.0.1' #Artifact version is greater than '1.0.1' or less than '0.0.1'
      pkg.version.id.startsWith('1.0.') #Artifact version must start with '1.0.'
      pkg.version.id in ['1.0.0', '1.2.0'] #Artifact version must be a member of the list ['1.0.0', '1.2.0']
      pkg.version.tag == 'tag1' #Artifact tag must be 'tag1'
      pkg.version.tag.startsWith('tag') #Artifact tag must start with 'tag'
      pkg.version.tag in ['tag1', 'tag2'] #Artifact tag must be a member of the list ['tag1', 'tag2']
    

Docker リポジトリにタグベースの条件(pkg.version.tag == 'latest' など)を含むルールを追加する場合は、次の点に注意してください。

  • ダイジェストで pull する場合、クライアントはタグを指定しません。タグを使用する条件は空のタグと照合されるため、予期しない動作が発生する可能性があります。
  • マルチアーキテクチャ コンテナ イメージの場合、タグを使用する条件が期待どおりに機能しない可能性があるため、使用しないでください。