aws-firmware-dump

이미 실행할 수 있는 AMI의 디스크를 프라이빗 S3 버킷으로 가져옵니다. 카탈로그도, 제품 목록도, 미리 지정된 AMI id도 없습니다. AMI id를 직접 전달합니다.

S3가 저장소입니다. 부팅, 스냅샷, 압축, 업로드가 모두 AWS 내부에서 실행됩니다. 로컬 대역폭은 나중에 특정 객체를 가져올 때만 사용됩니다.

수행하는 작업

graph LR
  A[AMI you supply] -->|run-instances| B[boot instance]
  B -->|every EBS disk| C[snapshots you own]
  C --> D[terminate boot instance]
  C -->|ListSnapshotBlocks / GetSnapshotBlock| E[helper]
  E -->|raw then zstd| F[(S3 golden store)]
  F -->|optional pull| G[local artifacts]

1. 이 스택의 VPC에서 AMI를 실행합니다. SSH도, 키 페어도, 인바운드 포트도 없습니다.
2. 해당 인스턴스의 모든 EBS 볼륨(루트 및 데이터 디스크)을 스냅샷한 다음 종료합니다. 마켓플레이스 이미지는 보통 DeleteOnTermination을 설정하므로 스냅샷을 먼저 생성합니다.
3. 작은 Amazon Linux 헬퍼가 EBS direct API를 통해 해당 스냅샷을 읽고 raw | zstd | aws s3 cp -로 스트리밍합니다. 볼륨은 생성되거나 연결되지 않습니다.
4. 압축된 스트림의 sha256과 AMI 이름, 소유자, 아키텍처, 제품 코드를 manifest.json에 기록합니다.

수행하지 않는 작업

• AMI를 검색하거나, 목록을 구독하거나, 대상을 선택하지 않습니다.
• 리전 간에 AMI를 복사하지 않습니다. AMI는 이미 region에 존재해야 합니다.
• Marketplace 약관에 동의하지 않습니다. OptInRequired는 콘솔 단계입니다.
• 이 계정이 실행할 수 없는 AMI는 실행하지 않습니다.

실행할 권한이 있는 이미지만 덤프하세요. 아티팩트는 비공개로 유지하세요. 목록에 마켓플레이스 소프트웨어 요금이 있는 경우, 부팅 인스턴스가 실행되는 동안에만 부과됩니다.

읽기 경로가 EBS direct API인 이유

AWS는 구매자에게 Marketplace AMI 뒤의 스냅샷을 제공하지 않습니다. 해당 스냅샷에 대한 copy-image와 create-volume은 실패합니다. AMI를 부팅하면 이 계정이 소유한 볼륨이 생성되고, 그 볼륨은 스냅샷할 수 있습니다.

Marketplace 제품 코드를 여전히 가진 볼륨은 중지된 인스턴스의 루트 디바이스로만 연결할 수 있으므로, 헬퍼에 데이터 디스크로 연결하는 것은 작동하지 않습니다. ListSnapshotBlocks + GetSnapshotBlock은 연결 없이 HTTPS를 통해 바이트를 반환합니다. 할당되지 않은 블록은 오프셋이 정확하게 유지되도록 0으로 출력됩니다.

direct API는 PascalCase 멤버를 사용하는 CBOR로 통신합니다. Checksum은 원시 다이제스트의 base64이며, 16진수가 아닙니다. ebs_snapshot_read.py가 둘 다 처리합니다.

사전 요구 사항

• Terraform >= 1.6, AWS provider >= 6
• AWS CLI v2, jq, flock, 그리고 스택을 적용하고 아래의 인스턴스/스냅샷/SSM/S3 호출을 실행할 수 있는 자격 증명
• zstd는 unpack.sh에만 필요
• 스택의 리전에서 AMI가 보여야 하며, 목록이 허용하는 부팅 인스턴스 유형

스크립트에서 사용하는 운영자 권한(헬퍼 역할은 별도이며 Terraform이 생성합니다):

• ec2:DescribeImages, DescribeInstances, DescribeSnapshots, RunInstances, TerminateInstances, CreateSnapshot, DeleteSnapshot, CreateTags, RegisterImage
• 헬퍼 인스턴스 프로파일에 대한 iam:PassRole
• ssm:GetParameter, SendCommand, GetCommandInvocation, DescribeInstanceInformation
• 아티팩트 버킷에 대한 s3:* (get/put/list/delete/head)
• sts:GetCallerIdentity

빠른 시작

cd terraform && cp terraform.tfvars.example terraform.tfvars
# edit region / name_prefix if needed — still no AMI ids
cd ..
make init && make apply && make configure

make probe AMI=ami-0123456789abcdef0
make dump  LABEL=my-image AMI=ami-0123456789abcdef0
make ls

ami-0123456789abcdef0는 자리 표시자입니다. 이 계정이 실행할 수 있는 AMI id로 바꾸세요.

make apply는 VPC, 이그레스 전용 보안 그룹, S3 버킷, 헬퍼 IAM 역할을 생성합니다. helper_enabled = true가 아니면 과금되는 컴퓨팅을 시작하지 않습니다. VPC에는 NAT 게이트웨이가 없으므로 유휴 비용은 버킷뿐입니다(그리고 무언가를 덤프할 때까지 비어 있습니다).

이미지 가져오기

scripts/dump.sh --ami ami-0123456789abcdef0 --label my-image
scripts/dump.sh --ami ami-0123456789abcdef0 --label my-image --boot-type m5.2xlarge --dwell 60
scripts/dump.sh --ami ami-0123456789abcdef0 --label my-image --dry-run
scripts/dump.sh --ami ami-0123456789abcdef0 --label my-image --snapshot-id snap-0123456789abcdef0

--dry-run은 AMI를 설명하고 계획을 출력합니다. 실행하지는 않습니다.

기본값:

플래그	기본값	비고
--boot-type	m5.xlarge, 또는 AMI가 arm64인 경우 m6g.xlarge	목록이 다른 유형을 거부하는 경우가 많습니다. AWS 오류가 허용하는 유형을 알려줍니다.
--dwell	180	스냅샷 전에 게스트가 실행되는 시간(초). 0은 인스턴스가 실행되자마자 스냅샷합니다.
--workers	32	디스크당 동시 GetSnapshotBlock 호출 수.

레이블은 ^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$와 일치해야 합니다. 레이블은 S3 키가 됩니다.

다시 실행하면 객체가 이미 S3에 있고 sha256이 매니페스트에 있는 레이블은 건너뜁니다. --force는 다시 가져옵니다.

여러 이미지

images.tsv, 한 줄에 이미지 하나. 빈 줄과 # 주석은 무시됩니다. 세 번째 필드는 선택적 인스턴스 유형입니다.

# LABEL            AMI                          BOOT_TYPE
my-image           ami-0123456789abcdef0
other-image        ami-0123456789abcdef0        m5.2xlarge

make dump-batch BATCH=images.tsv JOBS=2

--jobs N은 각 워커에 자체 헬퍼 슬롯을 제공합니다. 매니페스트 업데이트는 flock으로 잠깁니다. 두 개의 별도 드라이버 프로세스가 manifest.json을 공유할 수 있습니다. 헬퍼 슬롯 파일을 공유하지 않아야 하는 경우 서로 다른 DUMP_STATE_DIR 값을 지정하세요.

Marketplace 약관

make probe AMI=ami-0123456789abcdef0

run-instances --dry-run은 무료입니다. DryRunOperation은 계정이 실행할 수 있음을 의미합니다. OptInRequired는 AWS 콘솔에서 해당 목록에 동의한 후 다시 프로브하라는 의미입니다. 이 저장소는 약관에 동의하지 않습니다.

재개, 등록, 유지

• --snapshot-id는 부팅을 건너뛰고 기존 스냅샷 하나를 읽습니다. 단일 이미지만 가능합니다.
• --register-ami는 방금 생성한 스냅샷으로 이 계정에 실행 가능한 AMI를 등록하고 해당 스냅샷을 유지합니다. GB-월 단위로 과금됩니다.
• --keep-snapshot은 AMI를 등록하지 않고 스냅샷을 유지합니다. 정리는 --force를 전달하지 않는 한 Keep=true로 태그된 스냅샷을 건너뜁니다.

S3에 저장된 후

make ls                  # keys + manifest, no download
make watch               # in-flight helper log, multipart upload size
make pull LABELS="my-image"
make pull LABELS="my-image" RAW=1    # also write a sparse .raw
scripts/unpack.sh my-image           # partition metadata next to the raw

pull은 레이블을 다운로드됨으로 기록하기 전에 압축된 객체의 sha256을 확인합니다. unpack은 artifacts/raw/ 아래에 스파스 raw 이미지와 .diskmeta.txt(file, sfdisk, blkid, parted)를 작성합니다. losetup -Pf --show artifacts/raw/<label>.raw로 마운트하세요.

S3 레이아웃

s3://<bucket>/
  golden/<label>/<label>.raw.zst
  golden/<label>/<label>.raw.zst.sha256    # checksum of the compressed stream
  golden/<label>/<label>.stats.json
  golden/<label>/<label>.<device>.raw.zst  # extra disks, root is the unsuffixed object
  _scripts/snapshot_to_s3.sh
  _scripts/ebs_snapshot_read.py
  _status/<label>.json                     # expires after 7 days
  _logs/<label>.log                        # expires

golden/에는 수명 주기 만료가 없습니다. 완료되지 않은 멀티파트 업로드는 3일 후 중단됩니다. terraform destroy는 버킷을 삭제하며(force_destroy = true), golden/도 포함됩니다.

manifest.json(로컬, gitignored)은 인덱스입니다: AMI id, 이름, 소유자, 아키텍처, 제품 코드, 디스크별 키, sha256, 크기, 가져온 시간.

명령

make init / plan / apply / destroy
make configure
make probe AMI=ami-...
make dump LABEL=name AMI=ami-... [BOOT=type] [DWELL=seconds]
make dump-batch BATCH=images.tsv [JOBS=n]
make watch / ls / pull / unpack
make list
make cleanup                 # tagged resources only
make cleanup FORCE=1         # also delete Keep=true snapshots
make check                   # bash -n + python compile, no AWS

정리는 Purpose 태그(purpose_tag를 변경하지 않는 한 firmware-dump)로 리소스를 검색합니다. 계정의 다른 항목은 건드리지 않습니다.

비용

유휴 상태, apply 후 helper_enabled = false인 경우: 버킷만. NAT 게이트웨이 없음.

이미지당 대략:

• --dwell 동안의 부팅 인스턴스와 스냅샷 시간, 해당 인스턴스 유형의 온디맨드 요율, 더하기 해당 시간에 대한 Marketplace 소프트웨어 요금.
• 읽기를 위한 헬퍼(기본 t3.medium). 실행 중 이미지 간에 재사용됩니다. make cleanup이 종료합니다.
• 읽기가 끝날 때까지의 스냅샷 스토리지(유지하지 않은 경우).
• 이후 압축된 객체의 S3 스토리지. pull하는 경우에만 이그레스.

중단된 업로드가 멀티파트 파트를 영원히 과금되게 남길 수는 없습니다. 수명 주기 규칙이 3일 후 중단합니다. make cleanup은 잊어버린 헬퍼를 중지하는 방법입니다.

실행할 때만 나타나는 제약 사항

• 기본 VPC를 가정하지 않습니다. Terraform이 하나를 만들거나, vpc_id와 subnet_ids를 설정합니다. 관련 없는 VPC는 절대 선택되지 않습니다.
• 헬퍼는 Amazon Linux 2023 x86_64입니다. 대상 AMI는 x86 또는 arm일 수 있습니다. arm AMI에는 arm 부팅 유형을 전달하세요. 헬퍼가 일치할 필요는 없습니다.
• boto3는 인스턴스 메타데이터에서 리전을 가져오지 않습니다. 드라이버가 --region을 헬퍼에 전달합니다.
• SSM --parameters는 원격 명령을 안전하게 전달할 수 없습니다. 드라이버가 --cli-input-json을 보냅니다.
• 원격 읽기는 SSM 명령 타임아웃을 견디도록 nohup됩니다. _status/<label>.json이 ok를 말할 때까지 해당 스냅샷을 삭제하지 마세요. 실패 시 스냅샷은 의도적으로 make cleanup을 위해 남겨집니다.
• 계정 수준 EBS 암호화는 괜찮습니다: 헬퍼 역할에 kms:Decrypt가 있어 GetSnapshotBlock이 이 계정이 소유한 암호화된 스냅샷을 읽을 수 있습니다.
• register-image는 소스 AMI에서 아키텍처, 루트 디바이스 이름, 가상화 유형, ENA, 부팅 모드를 복사합니다. 제품 코드는 제거하지 않습니다.

레이아웃

terraform/          VPC, bucket, helper role, optional long-lived helper
scripts/dump.sh     boot, snapshot, remote read, manifest
scripts/probe.sh    free run-instances --dry-run
scripts/snapshot_to_s3.sh
scripts/ebs_snapshot_read.py
scripts/pull.sh scripts/unpack.sh scripts/watch.sh scripts/cleanup.sh