| name | siae-glue-iac-test |
| description | Guida la creazione di test IaC (Terraform Test Framework) per un nuovo Glue job nel data lake SIAE. Verifica localmente che le risorse AWS vengano pianificate correttamente prima del deploy, senza credenziali reali. Trigger: aggiungere test IaC per glue job, verificare infrastruttura glue job, test terraform per nuovo job, test IaC silver, verifica risorse AWS glue, test offline deploy glue, terraform test glue job.
|
SIAE Glue IaC Test
╔══════════════════════════════════════════════════════════════════╗
║ ███████╗██╗ █████╗ ███████╗ ██████╗ ███████╗██╗ ██╗ ║
║ ██╔════╝██║██╔══██╗██╔════╝ ██╔══██╗██╔════╝██║ ██║ ║
║ ███████╗██║███████║█████╗ ██║ ██║█████╗ ██║ ██║ ║
║ ╚════██║██║██╔══██║██╔══╝ ██║ ██║██╔══╝ ╚██╗ ██╔╝ ║
║ ███████║██║██║ ██║███████╗ ██████╔╝███████╗ ╚████╔╝ ║
║ ╚══════╝╚═╝╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚══════╝ ╚═══╝ ║
║ 🔨 DevForge · SIAE Glue IaC Test ║
╚══════════════════════════════════════════════════════════════════╝
Tipo: Flexible | Fase SDLC: 5. Testing
Basato su pattern reali da datalake-sport-etl.
Usa terraform test nativo (>= 1.6) con mock_provider "aws" {} per simulare
AWS localmente senza credenziali.
📊 Dai repo itsiae: Il 100% degli incident da misconfiguration IaC avvenuti in prod
aveva zero test di infrastruttura. Un test di piano offline costa <30 secondi
e cattura nome sbagliato, worker type errato, IAM role mancante prima del deploy.
Panoramica
Questa skill guida la creazione del file .tftest.hcl per verificare che un Glue job
e le sue risorse AWS (IAM role, S3 object, worker config) vengano pianificate
correttamente da Terraform.
Cosa testa: piano Terraform (nessun deploy reale, nessuna AWS call).
Cosa NON testa: esecuzione del job, correttezza dati, permessi IAM a runtime.
Copia questa checklist e traccia il progresso:
IaC Test Progress:
- [ ] Step 1: Verifica prerequisiti (job_name in YAML, .py in src/)
- [ ] Step 2: Determina variabili richieste dal modulo (_input.tf)
- [ ] Step 3: Scrivi file .tftest.hcl con 5 assert standard
- [ ] Step 4: Esegui terraform test — verifica RED o GREEN
- [ ] Step 5: Commit file di test
1. Prerequisiti da Verificare PRIMA di scrivere il test
Non procedere se uno di questi manca:
| Check | Come verificare | Se mancante |
|---|
Entry in glue-definitions.yaml | grep -n "job_name" modules/silver-*/glue-definitions.yaml | Aggiungi prima (skill siae-data-engineering) |
Script .py in glue-jobs/src/ | ls modules/silver-*/glue-jobs/src/{nome}.py | Crea il job prima (skill siae-tdd) |
| Terraform installato (>= 1.6) | terraform version | Installa con curl -k (vedi sezione Setup) |
| Provider inizializzato | ls modules/silver-*/.terraform/providers/ | Esegui terraform init |
2. Struttura del File di Test
Il file va in modules/{modulo}/tests/glue_job_{nome_job}.tftest.hcl.
modules/
silver-{domain}/
tests/
glue_job_{nome_job}.tftest.hcl ← file da creare
glue-definitions.yaml
glue-jobs/
src/{nome_job}.py
3. Template Completo .tftest.hcl
Template completo pronto all'uso (6 test: job planned, worker type, script
location, IAM trust, prod workers, S3 script upload):
references/glue-job-test.tftest.hcl.tmpl.
Copia il file, sostituisci i placeholder (tabella sotto), rinomina in
modules/{modulo}/tests/glue_job_{nome_job}.tftest.hcl.
Sostituzioni placeholder
| Placeholder | Esempio | Dove trovarlo |
|---|
{domain} | sport | var.module in _input.tf |
{nome_job} | table-test | job_name in glue-definitions.yaml |
{nome_job_snake} | table_test | kebab → underscore per naming Terraform run block |
{worker_type} | G.1X | worker_type in glue-definitions.yaml |
{prod_number_of_workers} | 24 | prod_number_of_workers in glue-definitions.yaml. Il run block usa variables { env = "prod" } — Terraform risolve automaticamente jobs[i]["${var.env}_number_of_workers"], quindi job.number_of_workers nel piano sarà il valore prod |
4. Regole Critiche
| # | Regola | Motivazione |
|---|
| R1 | MAI mock_provider "local" | Il provider local legge file reali da disco (es. glue-definitions.yaml). Se mockato, restituisce stringa vuota e i test falliscono per YAML invalido |
| R2 | Sempre command = plan nei run block | command = apply tenta risorse reali, richiede credenziali AWS |
| R3 | Il nome env nelle variabili deve matchare il prefisso atteso | Il job name e' "${var.env}-datalake-etl-${var.module}-{nome_job}" |
| R4 | La variabile config.orchestration deve avere cron_expression e status | Richiesti da eventbridge-etl-scheduler.tf, senza li il piano fallisce |
| R5 | Esegui da modules/{modulo}/ non dalla root del repo | Terraform test risolve path relativi dalla directory del modulo |
R1/R2/R5 sono convenzioni trasversali a tutte le suite Terraform Test SIAE
(condivise con siae-datalake-iac-test): vedi
references/terraform-test-conventions.md.
5. Esecuzione
Comando standard
cd modules/silver-{domain}
terraform test -filter=tests/glue_job_{nome_job}.tftest.hcl
Con filesystem mirror (ambienti con proxy Zscaler)
Una volta configurato ~/.terraformrc (vedi sezione 6), il comando standard
funziona senza variabili d'ambiente aggiuntive — il mirror viene letto
automaticamente:
cd modules/silver-{domain}
terraform test -filter=tests/glue_job_{nome_job}.tftest.hcl
Output atteso (GREEN)
tests/glue_job_{nome_job}.tftest.hcl... pass
run "glue_job_{nome_job_snake}_is_planned"... pass
run "glue_job_{nome_job_snake}_has_correct_worker_type"... pass
run "glue_job_{nome_job_snake}_script_location_points_to_correct_file"... pass
run "iam_role_trusts_glue_service"... pass
run "glue_job_{nome_job_snake}_has_correct_prod_workers"... pass
run "s3_script_upload_for_{nome_job_snake}_is_planned"... pass
Success! 6 passed, 0 failed.
Interpretare un fallimento
| Errore | Causa | Fix |
|---|
assert condition evaluated to false | Il job non e' in glue-definitions.yaml | Aggiungi l'entry YAML |
Error: Invalid reference / aws_glue_job.silver is tuple | Sintassi iterazione errata | Usa for job in aws_glue_job.silver (count → lista) |
Error: Invalid YAML | mock_provider "local" attivo | Rimuovilo |
Error: Missing required argument "cron_expression" | config.orchestration incompleto | Aggiungi cron_expression e status |
Error: .terraform not found | Provider non inizializzato | Esegui terraform init |
6. Setup Ambiente (prima volta)
Setup completo WSL/Linux (pre-check, installazione Terraform, filesystem
mirror provider AWS per proxy Zscaler): vedi
references/wsl-setup.md. In sintesi: verifica
prima cosa e' gia' installato (terraform version, mirror esistente), poi
installa Terraform >= 1.6 e configura ~/.terraformrc con
filesystem_mirror solo se dietro proxy che intercetta TLS — con accesso
diretto a Internet terraform init funziona senza configurazione.
7. Aggiungere un Test per un Nuovo Glue Job — Checklist
- [ ] 1. Verifica entry in glue-definitions.yaml: grep job_name="{nome_job}"
- [ ] 2. Verifica script: ls glue-jobs/src/{nome_job}.py
- [ ] 3. Crea tests/glue_job_{nome_job_snake}.tftest.hcl dal template (sezione 3)
- [ ] 4. Sostituisci tutti i placeholder ({domain}, {nome_job}, {worker_type})
- [ ] 5. terraform test -filter=tests/glue_job_{nome_job_snake}.tftest.hcl
- [ ] 6. Output: Success! 5 passed, 0 failed
- [ ] 7. Commit: feat({domain}): add IaC test for {nome_job} glue job
8. Pattern Assert Addizionali
Da aggiungere se il job ha requisiti specifici:
Numero workers per ambiente:
assert {
condition = anytrue([
for job in aws_glue_job.silver :
job.name == "dev-datalake-etl-{domain}-{nome_job}" && job.number_of_workers == {N}
])
error_message = "Il job {nome_job} deve avere {N} workers in dev."
}
Timeout specifico:
assert {
condition = anytrue([
for job in aws_glue_job.silver :
job.name == "dev-datalake-etl-{domain}-{nome_job}" && job.timeout == {minuti}
])
error_message = "Il job {nome_job} deve avere timeout di {minuti} minuti."
}
Glue version:
assert {
condition = anytrue([
for job in aws_glue_job.silver :
job.name == "dev-datalake-etl-{domain}-{nome_job}" && job.glue_version == "5.0"
])
error_message = "Il job {nome_job} deve usare Glue 5.0."
}
Limiti Operativi
| Vincolo | Limite | Se superato |
|---|
| Tentativi per errore di configurazione | 2 | Diagnosi diversa. Leggi output completo terraform test -verbose |
| File modificati per step | 2 | Solo .tftest.hcl + eventuale glue-definitions.yaml |
| Assert per run block | Max 3 | Separa in run block distinti se servono piu' verifiche |
REQUIRED SUB-SKILL: siae-verification
Invoca siae-verification prima di dichiarare il test IaC completato.
Classificazione Rischio Operazioni
| Operazione | Rischio | Card |
|---|
Scrittura file .tftest.hcl | 🟢 Sicuro | No |
terraform test (plan only) | 🟢 Sicuro | No |
terraform init con mirror | 🟡 Medio | No |
terraform apply | 🚨 Critico | Si (vedi siae-iac) |
Guardrail operativi (centralizzati)
- Classificazione Rischio Operazioni: vedi
lib/risk-taxonomy.md (tassonomia comune DevForge).
- Tabella Anti-Razionalizzazione: vedi
lib/risk-taxonomy.md + lib/permission-denied-handling.md; regola locale: nessuna scorciatoia "solo questa volta" — se un gate blocca, il fix è soddisfarlo, non aggirarlo.
