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

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

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

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

始める前に

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

必要なロール

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

ルールの作成、更新、取得、一覧表示、削除: Artifact Registry リポジトリ管理者（roles/artifactregistry.repoAdmin）
ルールの取得と一覧表示: Artifact Registry 読み取り（roles/artifactregistry.reader）

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

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

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

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"
  }
}

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

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d @request.json \
     "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules?ruleID=RULE_NAME"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json" `
    -InFile request.json `
    -Uri "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules?ruleID=RULE_NAME" | Select-Object -Expand Content

新しいルールが作成され、次の出力が生成されます。

{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}

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

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

gcloud

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

PROJECT: Google Cloud プロジェクト ID。プロジェクト ID にコロン（:）が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
LOCATION: リポジトリのリージョンまたはマルチリージョンのロケーション。
REPOSITORY: リポジトリの名前。

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

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

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

PROJECT: Google Cloud プロジェクト ID。プロジェクト ID にコロン（:）が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
LOCATION: リポジトリのリージョンまたはマルチリージョンのロケーション。
REPOSITORY: リポジトリの名前。

HTTP メソッドと URL:

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

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

curl（Linux、macOS、または Cloud Shell）

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules"

PowerShell（Windows）

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules" | Select-Object -Expand Content

指定したプロジェクト、ロケーション、リポジトリのルールのリストが次のように表示されます。

{
  "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: ルールの名前。名前はリポジトリ内で一意である必要があります。
PROJECT: Google Cloud プロジェクト ID。プロジェクト ID にコロン（:）が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
LOCATION: リポジトリのリージョンまたはマルチリージョンのロケーション。
REPOSITORY: リポジトリの名前。

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

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

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

RULE_NAME: ルールの名前。名前はリポジトリ内で一意である必要があります。
PROJECT: Google Cloud プロジェクト ID。プロジェクト ID にコロン（:）が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
LOCATION: リポジトリのリージョンまたはマルチリージョンのロケーション。
REPOSITORY: リポジトリの名前。

HTTP メソッドと URL:

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

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

curl（Linux、macOS、または Cloud Shell）

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME"

PowerShell（Windows）

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME" | Select-Object -Expand Content

ルールの詳細は、次のように表示されます。

{
  "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: このルールに一致するダウンロードに適用されるアクション。ALLOW か DENY を選択してください。
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: このルールに一致するダウンロードに適用されるアクション。ALLOW か DENY を選択してください。
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"
  }
}

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

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d @request.json \
     "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json" `
    -InFile request.json `
    -Uri "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME" | Select-Object -Expand Content

更新されたルールの詳細は、次のように表示されます。

{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}

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

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

gcloud

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

RULE_NAME: ルールの名前。名前はリポジトリ内で一意である必要があります。
PROJECT: Google Cloud プロジェクト ID。プロジェクト ID にコロン（:）が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
LOCATION: リポジトリのリージョンまたはマルチリージョンのロケーション。
REPOSITORY: リポジトリの名前。

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

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

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

RULE_NAME: ルールの名前。名前はリポジトリ内で一意である必要があります。
PROJECT: Google Cloud プロジェクト ID。プロジェクト ID にコロン（:）が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
LOCATION: リポジトリのリージョンまたはマルチリージョンのロケーション。
REPOSITORY: リポジトリの名前。

HTTP メソッドと URL:

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

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

curl（Linux、macOS、または Cloud Shell）

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

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME"

PowerShell（Windows）

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME" | Select-Object -Expand Content

詳細については、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 する場合、クライアントはタグを指定しません。タグを使用する条件は空のタグと照合されるため、予期しない動作が発生する可能性があります。
マルチアーキテクチャコンテナイメージの場合、タグを使用する条件が期待どおりに機能しない可能性があるため、避けてください。

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

始める前に

必要なロール

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

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

API

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

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

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

API

curl（Linux、macOS、または Cloud Shell）

PowerShell（Windows）

ダウンロード ルールの情報を設定する

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

API

curl（Linux、macOS、または Cloud Shell）

PowerShell（Windows）

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

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

API

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

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

gcloud

Linux、macOS、Cloud Shell

Windows（PowerShell）

Windows（cmd.exe）

API

curl（Linux、macOS、または Cloud Shell）

PowerShell（Windows）

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

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

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

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

ダウンロードルールの情報を設定する

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

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