CodeBuild Docker Cache Break-Even Analysis: S3 vs Local

Should you use S3 or local cache for Docker caching in AWS CodeBuild? The bottom line: in most cases, local cache is the best choice. This article shows the concrete break-even points.

TL;DR (Conclusion)

Two Caching Methods

Local Cache

1
2
3
4

cache {
  type  = "LOCAL"
  modes = ["LOCAL_DOCKER_LAYER_CACHE"]
}

• Cost: Free
• Constraints: Only effective on the same build host, requires privileged mode
• Use case: CI/CD environments that build frequently

S3 Cache

1
2
3
4

cache {
  type     = "S3"
  location = "my-bucket/cache"
}

• Cost: Storage $0.023/GB/month + transfer $0.09/GB
• Advantage: Can be shared across all build hosts
• Use case: Environments where the build host changes frequently

Pricing (2026)

CodeBuild

S3 Cache

1

Monthly cost = (0.023 × cache GB) + (number of builds × cache GB × 0.09)

Real-World Cost Comparison

For a typical project (1GB cache, 70% hit rate):

Above 50 builds per month, S3 costs exceed $3.

How Docker Layer Caching Works

A Docker image is made up of multiple layers, and when an upper layer changes, all subsequent layers are invalidated.

Typical Layer Structure

1
2
3
4
5
6

FROM node:20-alpine              # 150MB（変更: 月1回）
RUN apk add python3              # 50MB（変更: 月1回）
COPY package*.json ./
RUN npm ci                       # 300MB（変更: 週1回）
COPY . .                         # 20MB（変更: 毎日）
RUN npm run build                # 100MB（変更: 毎日）

Cache Efficiency

Average effective cache: 600-900MB, hit rate: 70-75%

Dockerfile Optimization Tips

❌ Bad Example

1
2

COPY . .
RUN npm install  # コード変更のたびに実行される

✅ Good Example

1
2
3
4
5
6

# 依存関係を先にインストール
COPY package*.json ./
RUN npm ci --only=production

# コードは後でコピー
COPY . .

Effect: Cache hit rate improves from 60% to 75%

Decision Flowchart

1
2
3
4
5
6

ビルドホストは毎回変わる？
├─ Yes → S3 キャッシュ（必須）
└─ No
   └─ ビルド頻度は？
      ├─ 週2回以上 → ローカルキャッシュ（推奨）
      └─ 週1回以下 → どちらでも可

Implementation Examples

Local Cache (Recommended)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

resource "aws_codebuild_project" "app" {
  name = "my-app"

  environment {
    compute_type    = "BUILD_GENERAL1_SMALL"
    image          = "aws/codebuild/standard:7.0"
    type           = "LINUX_CONTAINER"
    privileged_mode = true  # 必須
  }

  cache {
    type  = "LOCAL"
    modes = ["LOCAL_DOCKER_LAYER_CACHE"]
  }
}

S3 Cache

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

resource "aws_codebuild_project" "app" {
  name = "my-app"

  environment {
    compute_type = "BUILD_GENERAL1_SMALL"
    image       = "aws/codebuild/standard:7.0"
    type        = "LINUX_CONTAINER"
  }

  cache {
    type     = "S3"
    location = "${aws_s3_bucket.cache.bucket}/my-app"
  }
}

resource "aws_s3_bucket_lifecycle_configuration" "cache" {
  bucket = aws_s3_bucket.cache.id

  rule {
    id     = "expire-cache"
    status = "Enabled"
    expiration {
      days = 7  # 7日後に自動削除
    }
  }
}

Summary

General Recommendation

For most CI/CD environments, local cache is the best choice

• Zero transfer costs
• No network latency
• Saves $5-$30/month

Exceptional Cases for Choosing S3

1. The build host differs every time (e.g., spot instances)
2. It needs to run in a VPC environment
3. Build frequency is very low (4 or fewer per month)

Checklist

Optimize your Dockerfile:

• Place instructions that change infrequently higher up
• Copy dependency files first
• Exclude unnecessary files with .dockerignore

When using local cache:

• Set privileged_mode = true
• Verify security requirements

When using S3 cache:

• Delete after 7 days with a lifecycle policy
• Set a dynamic cache key (codebuild-hash-files)

Reference Links

• AWS CodeBuild Pricing
• CodeBuild Build Caching
• CodeBuild Local Caching
• CodeBuild S3 Caching