Come funziona

Questo documento descrive il flusso completo di esecuzione di cloudrift analyze, dall’invocazione CLI fino alla visualizzazione dei risultati.

Flusso di esecuzione

utente: cloudrift analyze -r us-east-1 eu-west-1 [--format json] [--pdf] [--live-pricing]
          │
          ▼
     main.ts (Commander.js parse degli argomenti)
          │
          ▼
     analyze-waste.command.ts (orchestra opzioni/config/output)
     1. loadConfig() — cloudrift.config.json / .cloudriftrc / --config
     2. AwsRegion.parse() per ogni regione
     3. accountId: --account-id oppure STS GetCallerIdentity
          │
          ▼
     analyze-waste.composition.ts (composition root)
     4. Pricing: tabella statica <- live API (--live-pricing) <- config.prices (vincono)
     5. Costruisce gli scanner dai registry dichiarativi
     6. Filtra secondo --scanners / --all-services / wizard interattivo
          │
          ▼
     AnalyzeCloudWasteUseCase.execute({ regions })
     Worker pool: max 12 scan in-flight (scanner x regione)
          │
          ▼
     Ogni scanner: AWS API -> entita di dominio -> waste policy -> findings
          │
          ▼
     WastedResourcesSummary -> formato scelto (table/json/markdown/PDF)
     totalWasteMonthlyUsd > costAlertThresholdUsd -> exit code 2 (gate CI)

Come funzionano gli scanner

Ogni scanner segue lo stesso pattern:

1. Crea il client AWS per la regione (con retry/backoff e timeout)
2. Raccoglie i candidati con paginazione, pre-filtrando lato server dove possibile
3. Recupera metriche CloudWatch (per gli scanner idle/underutilized) con concorrenza limitata (max 5)
4. Mappa a entita di dominio calcolando il costo via PricingPort
5. Applica la waste policy — grace period, tag di esclusione, criteri specifici
6. Distrugge il client nel finally

23 dei 44 scanner estendono un template method condiviso (CloudWatchIdleScanner) che gestisce questo lifecycle. Gli altri 21 implementano direttamente lo stesso schema.

Risoluzione dei prezzi

I costi sono risolti per (regione, chiave) da tre livelli, vince il piu specifico:

1. Override prices nel config — tariffe negoziate/aziendali (massima priorita)
2. AWS Pricing API (--live-pricing) — listino pubblico corrente
3. Tabella statica built-in (prices.json) — sempre presente come fallback

Ogni report mostra prices as of per indicare quale livello e stato usato.

Anche con --live-pricing, AWS restituisce i prezzi di listino, non la tua bolletta. Gli override prices nel config sono l’unico modo per far combaciare il report con cio che paghi davvero.

Concorrenza

• Worker pool globale: max 12 scan in-flight (configurabile via CLOUDRIFT_SCAN_CONCURRENCY), qualsiasi mix scanner/regione
• Fan-out interno: chiamate CloudWatch limitate a 5 concorrenti per scanner (evita throttling)
• Job accodati scanner-major: il primo batch si spalma sulle regioni invece di concentrarsi sulla prima

Gestione errori

La granularita degli errori e per (scanner, regione): un permesso mancante in una regione produce un warning per quella coppia, senza toccare il resto. Il report viene sempre restituito con i dati parziali e la sezione “Scan Warnings”.

L’exit code e guidato solo dalla soglia di costo (costAlertThresholdUsd), mai dagli errori di scansione.

Credenziali AWS

L’SDK AWS v3 usa la catena di credenziali predefinita:

1. Variabili d’ambiente (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
2. File ~/.aws/credentials (profilo default o AWS_PROFILE)
3. IAM Instance Profile (su EC2)
4. ECS Task Role / EKS Service Account

Per la scansione cross-account, --assume-role-arn assume il ruolo target via STS prima di qualsiasi chiamata AWS.

Formato output

• --format table (default) — tabelle colorate a terminale
• --format json — report machine-readable su stdout (componibile con jq)
• --format markdown — pronto per commenti PR / GitHub step summary
• --pdf [filename] — artefatto PDF aggiuntivo su disco
• --json [filename] — artefatto JSON aggiuntivo su disco
• --silent — sopprime tutto lo stdout (per esecuzioni solo-file)