# ECRのライフサイクルポリシーでsidecarのイメージの削除を回避する

## サマリ

- ECRのライフサイクルポリシーで全イメージを対象にした件数のルールを設定すると、更新しないsidecar（アプリと並行して動作する補助のコンテナ）のイメージも削除されうる。
  - sidecarの例はCloudflare Tunnelのcloudflared、ログ転送のFluent Bitなどである。
  - 削除されたイメージを参照する新規のECSのタスクは、`CannotPullContainerError`で停止する。
  - 同じsidecarを参照する全サービスが影響の対象になる。
- 件数のルールは保持の件数の超過分をプッシュの日時の昇順に削除し、タスク定義からの参照を考慮しない。
  - アプリのイメージをコミットごとに同じリポジトリへプッシュすると、1回だけプッシュしたsidecarのイメージがリポジトリで最古になる。
  - 最古のsidecarのイメージは、超過分の先頭として削除される。
- 件数のルールの対象を`tagPatternList`でアプリのビルドのタグに限定すると、sidecarのイメージは削除の対象外になる。
  - 1つのルールに複数のパターンを指定すると、全パターンに一致するイメージだけが対象になる。
  - パターンは1ルールあたり1つとし、ビルドの種類ごとにルールを作成する。

## 前提となるライフサイクルポリシーの評価

### 件数のルールと削除の順序

[ECRのライフサイクルポリシー](https://docs.aws.amazon.com/AmazonECR/latest/userguide/LifecyclePolicies.html) は、リポジトリのイメージを条件で選択し、削除（expire）するルールの集合である。
ルールの`tagStatus`は対象を決定し、`untagged`はタグのないイメージ、`tagged`はタグのパターンに一致するイメージ、`any`はリポジトリの全イメージを対象にする。
`countType`が`imageCountMoreThan`のルールは、対象のイメージが指定の件数を超過した分を、 [プッシュの日時（`pushed_at_time`）の昇順](https://docs.aws.amazon.com/AmazonECR/latest/userguide/LifecyclePolicies.html) に削除する。
タスク定義から参照中のイメージも、この順序で削除の対象になる。

### tagPatternListの一致の条件

`tagPatternList`は`*`をワイルドカードとするタグのパターンの一覧で、`*-api`は末尾が`-api`のタグに一致する。
1つのルールに複数のパターンを指定した場合の対象は、 [全パターンに一致するタグを保有するイメージだけ](https://docs.aws.amazon.com/AmazonECR/latest/userguide/lifecycle_policy_examples.html) である。
`["*-api", "*-batch"]`のルールは、`-api`のタグと`-batch`のタグの両方を保有するイメージを対象にし、`-api`のタグしかないイメージを対象にしない。

## ライフサイクルポリシーの適用後にECSのタスクが起動できなくなった

コスト削減のため、アプリのリポジトリに次のポリシーを適用した。
タグのないイメージを7日で削除し、リポジトリ全体で30件を超過した分を削除するルールである。

```hcl
resource "aws_ecr_lifecycle_policy" "app" {
  repository = aws_ecr_repository.app.name
  policy = jsonencode({
    rules = [
      {
        rulePriority = 1
        description  = "Expire untagged images older than 7 days"
        selection = {
          tagStatus   = "untagged"
          countType   = "sinceImagePushed"
          countUnit   = "days"
          countNumber = 7
        }
        action = { type = "expire" }
      },
      {
        rulePriority = 2
        description  = "Keep only the last 30 images"
        selection = {
          tagStatus   = "any"
          countType   = "imageCountMoreThan"
          countNumber = 30
        }
        action = { type = "expire" }
      }
    ]
  })
}
```

適用の翌日に、ECSの3つのサービスで新規のタスクが`CannotPullContainerError`で停止し、実行中のタスクが0件になった。

## コミットごとのイメージの増加でsidecarのイメージが最古になる

このリポジトリには2種類のイメージがあった。
各イメージのタグはどちらか一方の種類に限られていた。

| 種類 | タグ | プッシュの頻度 |
| --- | --- | --- |
| アプリのビルド | `<commit-sha>-api`、`<commit-sha>-batch`、`<commit-sha>-script`、`<commit-sha>-db-migration` | コミットごと |
| sidecar | `cloudflared-latest`、`aws-for-fluent-bit-stable`、`datadog-agent-latest` | 構築の時点で1回 |

sidecarのイメージは、公開のレジストリから取得したものをアプリ用のリポジトリに1回だけプッシュしていた。
タスク定義はアプリのコンテナと並列に、このリポジトリの固定のタグを参照する。

```json
{
  "name": "cloudflared",
  "image": "<account-id>.dkr.ecr.<region>.amazonaws.com/<repository>:cloudflared-latest"
}
```

`tagStatus = "any"`のルールは、アプリのビルドとsidecarを区別せずに件数を計算し、プッシュの日時の昇順に削除する。
sidecarのイメージはリポジトリで最古なので、30件の超過分の先頭として削除の対象になる。

```mermaid
flowchart LR
  subgraph R[同じリポジトリのイメージ（プッシュの日時の順）]
    direction LR
    S[sidecar<br/>cloudflared-latestなど<br/>構築の時点で1回] --> O[アプリのビルド<br/>過去のコミット] --> N[アプリのビルド<br/>直近の30件]
  end
  P[tagStatus any<br/>30件の超過分を削除] -.->|最古から対象にする| S
  P -.->|次に対象にする| O
  S --> X[新規のタスクの起動で<br/>CannotPullContainerError]
```

稼働中のタスクは起動の時点に取得したイメージで動作を継続する。
停止はデプロイや自動の置換で新規に起動した時点で発生する。

### タスクの起動の失敗がイメージの削除によるものかの判別

以下はFargateで動作するECSのサービスが対象である。

`CannotPullContainerError`は、イメージがない場合のほかに、ECRに接続できない場合や権限がない場合にも発生する。
[ECSのドキュメント](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_cannot_pull_image.html) にエラーの文と原因の対応がある。

ECSのサービスはデフォルトでデプロイの時点に [タスク定義のタグをイメージのダイジェスト（イメージの内容から計算した識別子）に解決](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-type-ecs.html) し、以後の新規のタスクもそのダイジェストで起動する。
そのため、確認するのは現在のタグだけでなく、停止したタスクが取得しようとしたダイジェストである。
停止したタスクのコンテナのダイジェストを取得し、そのダイジェストがリポジトリに存在するかを確認する。

```bash
aws ecs describe-tasks --cluster <cluster> --tasks <stopped-task-id> \
  --query 'tasks[].containers[].[name,image,imageDigest,reason]'

aws ecr describe-images --repository-name <repository> \
  --image-ids imageDigest=<image-digest>
```

イメージがなければ`ImageNotFoundException`になる。

ライフサイクルポリシーによる削除は、CloudTrailに [イベント名`PolicyExecutionEvent`](https://docs.aws.amazon.com/AmazonECR/latest/userguide/logging-using-cloudtrail.html) で記録され、削除したイメージのダイジェストとタグも記録される。

```bash
aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=EventName,AttributeValue=PolicyExecutionEvent \
  --max-results 20
```

イメージが存在するのに取得が失敗する場合は、ネットワークかタスクの実行ロールの権限が原因の候補になる。

## sidecarのイメージの再プッシュとタスクの再起動

削除したイメージは復元できないので、タスク定義が参照するタグを設定したイメージを再度プッシュする。
以下は対象のECRのリポジトリへのプッシュの権限があり、DockerでECRのレジストリにログイン済みの場合の例である。
タスクの実行環境はLinuxのx86_64とする。

```bash
docker pull --platform linux/amd64 cloudflare/cloudflared:latest
docker tag cloudflare/cloudflared:latest <repository-uri>:cloudflared-latest
docker push <repository-uri>:cloudflared-latest

aws ecs update-service --cluster <cluster> --service <service> \
  --force-new-deployment
```

`--force-new-deployment`は、タスク定義を変更せずに新規のデプロイを開始するオプションである。
このデプロイではECSが [タグを最新のダイジェストに再度解決する](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-type-ecs.html) 。
再起動の後、3つのサービスで新規のタスクが起動した。

`latest`のタグは取得の時点の最新版を指すので、再プッシュしたイメージは削除の前と別のバージョンになりうる。

## 件数のルールの対象をビルドのタグに限定する

以下はsidecarとアプリのビルドが別々のイメージで、ビルドの各イメージのタグを1つの接尾辞で分類できる構成が対象である。
件数のルールを`tagStatus = "tagged"`にし、`tagPatternList`で対象をアプリのビルドのタグに限定する。
パターンは1つのルールに1つにし、タグの接尾辞ごとにルールを作成する。

```hcl
locals {
  build_tag_suffixes = ["api", "batch", "script", "db-migration"]
}

resource "aws_ecr_lifecycle_policy" "app" {
  repository = aws_ecr_repository.app.name
  policy = jsonencode({
    rules = concat(
      [{
        rulePriority = 1
        description  = "Expire untagged images older than 7 days"
        selection = {
          tagStatus   = "untagged"
          countType   = "sinceImagePushed"
          countUnit   = "days"
          countNumber = 7
        }
        action = { type = "expire" }
      }],
      [for i, suffix in local.build_tag_suffixes : {
        rulePriority = i + 2
        description  = "Keep the latest 30 ${suffix} images"
        selection = {
          tagStatus      = "tagged"
          tagPatternList = ["*-${suffix}"]
          countType      = "imageCountMoreThan"
          countNumber    = 30
        }
        action = { type = "expire" }
      }]
    )
  })
}
```

sidecarのイメージのタグ（`cloudflared-latest`など）はどのパターンにも一致しないので、どのルールの対象にもならない。
保持の件数は接尾辞ごとに計算されるので、ビルドの種類ごとに`countNumber`の件数（この例では30件）が保持される。

### 異なる接尾辞のパターンを1つのルールに指定した場合

`*-api`、`*-batch`、`*-script`、`*-db-migration`を1つのルールの`tagPatternList`に指定すると、対象は4つのパターンすべてに一致するタグを保有するイメージになる。
タグが1つのビルドのイメージは対象外になるので、sidecarの削除は回避できても、ビルドのイメージの件数が増加し続ける。

### 採用しなかったリポジトリの分割と件数の増加

sidecarを別のリポジトリに移動すれば、アプリのリポジトリの件数のルールの対象外になる。
ただし、タスク定義の参照先とリポジトリの権限の確認が必要になるため、今回はポリシーの変更を選択した。
保持の件数を増加しても、コミットの増加でsidecarはいずれ削除の対象になるため、この案は採用しなかった。

## 適用の前の削除の対象の確認

ECRの [ライフサイクルポリシーのプレビュー](https://docs.aws.amazon.com/AmazonECR/latest/userguide/lpp_creation.html) は、ポリシーを適用せずに削除の対象を一覧で表示する。
`policy.json`には、Terraformの`jsonencode`が出力するJSONを指定する。
プレビューは非同期で処理されるので、`status`が`COMPLETE`になった結果で、タスク定義が参照するタグが一覧にないことを確認してから適用する。

```bash
aws ecr start-lifecycle-policy-preview --repository-name <repository> \
  --lifecycle-policy-text file://policy.json
aws ecr get-lifecycle-policy-preview --repository-name <repository> \
  --query '{status: status, tags: previewResults[].imageTags}'
```
