G-gen の佐々木です。当記事では、Artifact Registry で不要になったイメージを自動削除するクリーンアップポリシーについて、特定のイメージが削除されないように条件付きの保持ポリシーを組み合わせて使う方法を解説します。

クリーンアップポリシーとは

機能の概要

Artifact Registry のクリーンアップポリシーは、リポジトリ内のイメージを条件に基づいて自動的に削除する機能です。

開発を続けていると、不要なイメージが蓄積し、ストレージコストが増大してしまう場合があります。クリーンアップポリシーを設定することで、不要なイメージを自動的に削除することができます。

クリーンアップポリシーには以下の2種類があります。

種類	説明
削除ポリシー（Delete）	条件に一致したイメージを削除する
保持ポリシー（Keep）	条件に一致したイメージを削除から保護する

1つのリポジトリに対して、削除ポリシーと保持ポリシーを複数組み合わせて設定できます。保持ポリシーは削除ポリシーよりも優先されるため、「基本的には削除するが、特定の条件に一致するイメージは残す」という運用が可能です。

クリーンアップポリシーの詳細については、以下の記事で解説しています。

blog.g-gen.co.jp

参考 : クリーンアップポリシーの概要
参考 : クリーンアップポリシーを構成する

保持ポリシーを使用するケース

保持ポリシーを使用せずに削除ポリシーのみを適用していると、「本番環境で現在利用しているイメージが削除ポリシーによって削除されてしまう」といった問題が起こり得ます。

例えば Cloud Run jobs では、ジョブに設定されているコンテナイメージが削除されてしまうと、実行時にコンテナインスタンスが立ち上がらずにジョブが失敗してしまいます。

使用するコンテナイメージが削除され、Cloud Run jobs のジョブが失敗したケース

このケースでは、Cloud Logging で以下のようなエラーを確認できます。

Image '<Artifact Registryのコンテナイメージのパス>' not found.

保持ポリシーで設定可能な条件

保持ポリシーは、条件に一致するイメージを削除から保護するためのポリシーであり、以下のような条件を指定できます。

条件	説明
`tagState`	タグの状態（`tagged` / `untagged` / `any`）
`tagPrefixes`	タグのプレフィックス（例: `release`, `prod`）
`versionNamePrefixes`	バージョン名のプレフィックス
`packageNamePrefixes`	パッケージ名のプレフィックス
`olderThan`	指定した期間より古いイメージ
`newerThan`	指定した期間より新しいイメージ

また、mostRecentVersions を使うことで、直近の N 個のバージョンを保持するという指定も可能です。

参考 : クリーンアップポリシーの設定 - 条件付き保持ポリシーの作成

当記事のユースケース

当記事では、以下のようなユースケースを想定します。

release タグが付いたイメージは本番環境にデプロイされているため、常に保持したい
直近5バージョンは開発・デバッグのために残しておきたい
上記以外の古いイメージは自動的に削除したい

これを実現するために、以下の3つのポリシーを組み合わせます。

ポリシー名	設定内容
keep-tagged-release	`release` プレフィックスが付いたタグ付きイメージを保持
keep-minimum-versions	直近5バージョンを保持
delete-all	上記の保持ポリシーで保護されなかったイメージをすべて削除

ポリシーの定義ファイル（記事内では policy.json とする）は以下の通りです。

[
  {
    "name": "keep-tagged-release",
    "action": {"type": "Keep"},
    "condition": {
      "tagState": "tagged",
      "tagPrefixes": ["release"]
    }
  },
  {
    "name": "keep-minimum-versions",
    "action": {"type": "Keep"},
    "mostRecentVersions": {
      "keepCount": 5
    }
  },
  {
    "name": "delete-all",
    "action": {"type": "Delete"},
    "condition": {
      "tagState": "any"
    }
  }
]

このポリシーでは、2つの保持ポリシーによって「release プレフィックスのタグが付いたイメージ」と「直近5バージョン」が保護されます。

そして、保護していないイメージは削除ポリシーによって削除されます。保持ポリシーは削除ポリシーよりも優先されるため、保持対象のイメージが誤って削除されることはありません。

設定方法

保持対象イメージへのタグの付与

当記事では以下のスクリーンショットのように、v1.0.0 タグが付いたイメージを本番環境で運用中のイメージと想定し、以降のバージョンが増えることによってイメージが削除されないように、保持ポリシーの条件である release タグを付与します。

ドライラン

クリーンアップポリシーを適用する前に、まずドライランで削除対象のイメージを確認することを推奨します。ドライランでは実際の削除は行われず、削除対象となるイメージが Cloud Logging に記録されます。

# ドライランの設定でクリーンアップポリシーを適用する
$ gcloud artifacts repositories set-cleanup-policies <リポジトリ名> \
    --project=<プロジェクトID> \
    --location=asia-northeast1 \
    --policy=policy.json \
    --dry-run

ドライランが実行されると、Cloud Logging にどのイメージが削除対象となったかが記録されます。

Cloud Logging で以下のような条件でフィルタリングし、ドライランのログを確認します。

protoPayload.serviceName="artifactregistry.googleapis.com"
protoPayload.methodName="google.devtools.artifactregistry.v1.ArtifactRegistry.BatchDeleteVersions"

ドライラン結果として以下のようなログが出力されているので、意図しないイメージが削除対象になっていないか確認します。削除対象のイメージは protoPayload.request.names にリスト形式で記録されています。

{
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "status": {},
    "authenticationInfo": {
      "principalEmail": "service-xxxxxxxxxxxx@gcp-sa-artifactregistry.iam.gserviceaccount.com"
    },
    "requestMetadata": {
      "callerIp": "private",
      "callerSuppliedUserAgent": "stubby_client",
      "requestAttributes": {
        "time": "2026-03-25T13:29:47.993615022Z",
        "auth": {}
      },
      "destinationAttributes": {}
    },
    "serviceName": "artifactregistry.googleapis.com",
    "methodName": "google.devtools.artifactregistry.v1.ArtifactRegistry.BatchDeleteVersions",
    "authorizationInfo": [
      {
        "resource": "projects/<プロジェクトID>/locations/asia-northeast1/repositories/<リポジトリ名>/packages/-",
        "permission": "artifactregistry.versions.delete",
        "granted": true,
        "resourceAttributes": {},
        "permissionType": "DATA_WRITE"
      }
    ],
    "resourceName": "projects/<プロジェクトID>/locations/asia-northeast1/repositories/<リポジトリ名>/packages/-",
    "request": {
      "@type": "type.googleapis.com/google.devtools.artifactregistry.v1.BatchDeleteVersionsRequest",
      "parent": "projects/<プロジェクトID>/locations/asia-northeast1/repositories/<リポジトリ名>/packages/-",
      "names": [
        "projects/<プロジェクトID>/locations/asia-northeast1/repositories/<リポジトリ名>/packages/<イメージ名>/versions/sha256:92e1bbc6c7a85472768f3bbe191bb11a2d00531b0c542093025dfc6d41885894",
        "projects/<プロジェクトID>/locations/asia-northeast1/repositories/<リポジトリ名>/packages/<イメージ名>/versions/sha256:e4f1245e24b0c9947b31f6565e2b573583b32e570dcba40e4cb9e2596ea39251",
        "projects/<プロジェクトID>/locations/asia-northeast1/repositories/<リポジトリ名>/packages/<イメージ名>/versions/sha256:064ee8f6db44777f1164ab037c85c54780ec6912bea647484e88601da10ca115",
        "projects/<プロジェクトID>/locations/asia-northeast1/repositories/<リポジトリ名>/packages/<イメージ名>/versions/sha256:54c09f62de97bccd6cf12f7f964aea22469cac1d7b2a378a656f8ae599fc5183",
        "projects/<プロジェクトID>/locations/asia-northeast1/repositories/<リポジトリ名>/packages/<イメージ名>/versions/sha256:a4f9c3250d99a2ef8d1174e7e932231b613c4777ee52b4f7ae6789f6e4422171"
      ],
      "validateOnly": true
    }
  },
  "insertId": "18prm54d2w06",
  "resource": {
    "type": "audited_resource",
    "labels": {
      "service": "artifactregistry.googleapis.com",
      "project_id": "<プロジェクトID>",
      "method": "google.devtools.artifactregistry.v1.ArtifactRegistry.BatchDeleteVersions"
    }
  },
  "timestamp": "2026-03-25T13:29:47.981759939Z",
  "severity": "INFO",
  "logName": "projects/<プロジェクトID>/logs/cloudaudit.googleapis.com%2Fdata_access",
  "operation": {
    "id": "projects/<プロジェクトID>/locations/asia-northeast1/operations/2bd61d82-efbc-41a1-b0e8-5606076b4c45",
    "producer": "artifactregistry.googleapis.com",
    "first": true
  },
  "receiveTimestamp": "2026-03-25T13:29:48.932576392Z"
}

対象イメージの sha256: の後ろの英数字12桁が Artifact Registry にあるイメージ名と一致するようになっています。

release タグの付いているイメージを除いて古い順からイメージが削除され、新しい順に5つのイメージと release タグの付いたイメージが残されることがわかります。

ポリシーの適用

ドライランの結果に問題がなければ、--no-dry-run フラグを指定してポリシーを適用します。

# クリーンアップポリシーを適用する
$ gcloud artifacts repositories set-cleanup-policies <リポジトリ名> \
    --project=<プロジェクトID> \
    --location=asia-northeast1 \
    --policy=policy.json \
    --no-dry-run