aws-firmware-dump

Acquisisci i dischi di un'AMI che puoi già avviare in un bucket S3 privato. Nessun catalogo, nessuna lista di prodotti, nessun AMI id predefinito. Passi tu l'AMI id.

S3 è l'archivio. Avvio, snapshot, compressione e upload vengono eseguiti interamente all'interno di AWS. La banda locale viene utilizzata solo se successivamente scarichi un oggetto specifico.

Cosa fa

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. Avvia l'AMI nella VPC di questo stack. Nessun SSH, nessuna coppia di chiavi, nessuna porta in ingresso.
2. Esegui lo snapshot di ogni volume EBS su quell'istanza (dischi root e dati), poi termina l'istanza. Gli snapshot vengono creati per primi perché le immagini del marketplace di solito impostano DeleteOnTermination.
3. Un piccolo helper Amazon Linux legge quegli snapshot tramite le API dirette EBS e trasmette in streaming raw | zstd | aws s3 cp -. Nessun volume viene creato o collegato.
4. Registra lo sha256 dello stream compresso insieme a nome AMI, proprietario, architettura, e product code in manifest.json.

Cosa non fa

• Non cerca AMI, non ti iscrive a una listing, né seleziona un target.
• Non copia un'AMI tra regioni. L'AMI deve già esistere in region.
• Non accetta i termini del Marketplace. OptInRequired è un passaggio da console.
• Non avvierà un'AMI che questo account non può avviare.

Esegui il dump solo di immagini che hai il diritto di eseguire. Mantieni gli artefatti privati. Una tariffa software del Marketplace, se la listing ne prevede una, matura solo mentre l'istanza di avvio è in esecuzione.

Perché il percorso di lettura usa le API dirette EBS

AWS non fornisce agli acquirenti lo snapshot dietro un'AMI del Marketplace. copy-image e create-volume su quello snapshot falliscono. Avviare l'AMI crea un volume di proprietà di questo account, e quel volume può essere sottoposto a snapshot.

Un volume che porta ancora un product code del Marketplace può essere collegato solo come dispositivo root di un'istanza arrestata, quindi collegarlo a un helper come disco dati non funziona. ListSnapshotBlocks + GetSnapshotBlock restituiscono i byte via HTTPS senza collegamento. I blocchi non allocati vengono emessi come zeri così gli offset rimangono corretti.

L'API diretta parla CBOR con membri in PascalCase. Checksum è base64 del digest grezzo, non hex. ebs_snapshot_read.py gestisce entrambi.

Prerequisiti

• Terraform >= 1.6, provider AWS >= 6
• AWS CLI v2, jq, flock, e credenziali che possono applicare lo stack ed eseguire le chiamate instance/snapshot/SSM/S3 riportate di seguito
• zstd solo per unpack.sh
• L'AMI visibile nella regione dello stack, e un tipo di istanza di avvio che la listing consente

Permessi dell'operatore usati dagli script (il ruolo dell'helper è separato, ed è creato da Terraform):

• ec2:DescribeImages, DescribeInstances, DescribeSnapshots, RunInstances, TerminateInstances, CreateSnapshot, DeleteSnapshot, CreateTags, RegisterImage
• iam:PassRole sul profilo dell'istanza helper
• ssm:GetParameter, SendCommand, GetCommandInvocation, DescribeInstanceInformation
• s3:* sul bucket degli artefatti (get/put/list/delete/head)
• sts:GetCallerIdentity

Avvio rapido

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 è un segnaposto. Sostituiscilo con un AMI id che questo account può avviare.

make apply crea una VPC, un security group solo in uscita, un bucket S3, e il ruolo IAM dell'helper. Non avvia risorse di calcolo fatturabili a meno che helper_enabled = true. La VPC non ha NAT gateway, quindi il costo a riposo è solo il bucket (e questo è vuoto finché non esegui il dump di qualcosa).

Acquisire un'immagine

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 descrive l'AMI e stampa il piano. Non avvia nulla.

Valori predefiniti:

Flag	Default	Notes
--boot-type	m5.xlarge, o m6g.xlarge se l'AMI è arm64	Le listing spesso rifiutano altri tipi. L'errore AWS indica quelli che consentono.
--dwell	180	Secondi di esecuzione del guest prima dello snapshot. 0 esegue lo snapshot non appena l'istanza è in esecuzione.
--workers	32	Chiamate GetSnapshotBlock concorrenti per disco.

Le label devono corrispondere a ^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$. Diventano chiavi S3.

Una ri-esecuzione salta una label il cui oggetto è già in S3 e il cui sha256 è nel manifest. --force esegue di nuovo il fetch.

Più immagini

images.tsv, un'immagine per riga. Le righe vuote e i commenti # vengono ignorati. Il terzo campo è un tipo di istanza opzionale.

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

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

--jobs N assegna a ogni worker il proprio slot helper. Gli aggiornamenti del manifest sono protetti con flock. Due processi driver separati possono condividere manifest.json; assegna loro valori DUMP_STATE_DIR diversi se non devono condividere un file di slot helper.

Termini del Marketplace

make probe AMI=ami-0123456789abcdef0

run-instances --dry-run è gratuito. DryRunOperation significa che l'account può avviarla. OptInRequired significa accettare quella listing nella console AWS, poi eseguire di nuovo il probe. Questo repo non accetterà i termini per te.

Riprendere, registrare, conservare

• --snapshot-id salta l'avvio e legge uno snapshot esistente. Solo immagine singola.
• --register-ami registra un'AMI avviabile in questo account dagli snapshot appena creati, e conserva quegli snapshot. Vengono fatturati per GB-mese.
• --keep-snapshot conserva gli snapshot senza registrare un'AMI. La pulizia salta gli snapshot taggati Keep=true a meno che tu non passi --force.

Dopo che è in 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 verifica lo sha256 dell'oggetto compresso prima di registrare la label come scaricata. unpack scrive un'immagine raw sparsa sotto artifacts/raw/ e un .diskmeta.txt (file, sfdisk, blkid, parted). Monta con losetup -Pf --show artifacts/raw/<label>.raw.

Layout 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/ non ha scadenza del ciclo di vita. Gli upload multipart incompleti vengono interrotti dopo 3 giorni. terraform destroy elimina il bucket (force_destroy = true), incluso golden/.