Terraform Import: porta l’infrastruttura esistente sotto controllo del codice

Il tuo team distribuisce risorse cloud da anni tramite clic in console e script shell. Ora vuoi adottare l’Infrastructure as Code, ma ricreare tutto da zero sembra scoraggiante. Ci sono passato anch’io, e la funzionalità di import di Terraform è la soluzione a questa sfida.

I rischi del "ClickOps" e della gestione manuale dell’infrastruttura aumentano nel tempo. Le risorse diventano non documentate, le configurazioni divergono dagli standard e la conoscenza tribale sostituisce la documentazione adeguata. Quando i membri del team se ne vanno, se ne vanno anche le loro decisioni infrastrutturali. 

Ecco perché le organizzazioni adottano l’Infrastructure as Code (IaC). In questo tutorial ti guiderò nell’importazione dell’infrastruttura esistente in Terraform. 

Confronteremo il comando di import basato su CLI con gli import block dichiarativi introdotti in Terraform 1.5, esploreremo workflow pratici per entrambi gli approcci e affronteremo le insidie comuni che possono trasformare un semplice import in un incidente in produzione. Alla fine, avrai la sicurezza per portare la tua infrastruttura esistente sotto la gestione del codice. 

Se sei alle prime armi con IaC e i cloud provider, valuta di seguire uno dei nostri corsi, come AWS Concepts, Understanding Cloud Computing o Understanding Microsoft Azure. 

Cos’è Terraform Import?

Quando crei un’infrastruttura con Terraform sin dall’inizio, fila tutto liscio. Scrivi la configurazione, esegui terraform plan, rivedi le modifiche e le applichi. Terraform tiene traccia di tutto nel suo file di stato, creando una mappatura perfetta tra il tuo codice e le risorse cloud. 

Ma cosa succede quando le risorse esistono già al di fuori della conoscenza di Terraform? Iniziamo capendo esattamente cosa fa l’import e perché esiste.

Definizione e scopo principali

Terraform import mappa l’infrastruttura reale esistente alle voci nel file di stato di Terraform senza creare nuove risorse. Pensalo come un’adozione: stai dicendo a Terraform di iniziare a gestire una risorsa già in esecuzione.

Questo risolve il problema della "shadow IT". Le organizzazioni accumulano infrastruttura in vari modi: deploy da console durante outage, risorse di test diventate permanenti o sistemi legacy precedenti all’adozione di IaC. L’import riconcilia questa realtà con i principi dell’Infrastructure as Code.

Ecco la parte cruciale: l’import è principalmente un’operazione sullo stato. Non scrive automaticamente il codice di configurazione a meno che tu non usi le funzionalità di generazione in Terraform 1.5+. Sta a te assicurarti che la configurazione HCL rispecchi accuratamente la risorsa importata.

Ora che abbiamo capito cosa fa l’import, vediamo quando dovresti usarlo e quando no.

Terraform import vs alternative

Consiglio l’import in tre scenari principali:

• Migrazione di infrastruttura legacy che non può essere ricreata senza tempi di inattività significativi o perdita di dati. Pensa a database di produzione con anni di dati o bilanciatori di carico che servono traffico live.
• Recupero di file di stato persi, che può capitare anche con backend remoti se i backup non sono configurati correttamente.
• Onboarding di modifiche manuali che in qualche modo hanno bypassato il tuo processo di change management, magari fix di emergenza durante un outage.

Tuttavia, l’import non è sempre la scelta giusta. Per risorse di test temporanee o infrastruttura con scarsa standardizzazione, spesso suggerisco una ricreazione pulita. 

Partire da zero ti permette di applicare le best practice attuali, implementare convenzioni di naming corrette e aggiungere configurazioni di sicurezza che le risorse legacy potrebbero non avere. Lo sforzo iniziale della ricreazione spesso ripaga in termini di manutenibilità a lungo termine.

È fondamentale distinguere l’import dalle data source di Terraform. Le data source ti permettono di referenziare informazioni in sola lettura da infrastruttura esistente senza gestirla. Ad esempio, potresti usare una data source per cercare una VPC esistente creata da un altro team e poi distribuirci dentro le tue risorse. 

L’import, invece, porta le risorse sotto la gestione completa di Terraform, inclusa la possibilità di modificarle o distruggerle. Scegli l’import quando devi gestire l’intero ciclo di vita di una risorsa, non solo referenziarla.

Prima di iniziare a importare, ci sono alcuni vincoli fondamentali da capire.

Vincoli chiave e fondamentali

Ogni risorsa importata richiede un identificatore univoco specifico del provider. Per AWS, potrebbe essere i-0123456789abcdef0. Per Azure, è un percorso completo della risorsa come /subscriptions/{id}/resourceGroups/{rg}/providers/{provider}/{resource}. Sbagliare questo è la causa principale dei fallimenti di import.

Le operazioni di import modificano direttamente il file di stato, quindi i backup sono essenziali. Se usi backend versionati come S3, verifica che il versioning sia abilitato. Con stato locale, copia manualmente in terraform.tfstate.backup.

Dopo l’import, incontrerai il "drift": la discrepanza tra lo stato importato e la configurazione locale. Aggiornerai il tuo codice HCL iterativamente finché terraform plan non mostrerà zero modifiche in sospeso.

Prerequisiti e preparazione per Terraform Import 

Prima di importare qualsiasi cosa, assicurati di essere impostato per il successo. Ho visto import fallire perché i team hanno saltato i passaggi di preparazione.

Il primo passo è assicurarti che il tuo ambiente Terraform sia configurato correttamente.

Validare l’ambiente

Inizia verificando la tua installazione di Terraform con terraform version. Se vuoi accedere agli import block dichiarativi e alla generazione automatica del codice, assicurati di essere su Terraform 1.5 o successivo. Queste funzionalità semplificano drasticamente l’import per risorse complesse.

Prima di importare, verifica questi prerequisiti:

• Credenziali del provider attive: per AWS, controlla che AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY siano impostate o che il tuo profilo AWS CLI sia configurato. Testa con aws sts get-caller-identity.

• Workspace corretto selezionato: esegui terraform workspace show per verificare di non importare per errore nell’ambiente sbagliato.

• File di stato sbloccato: coordina con i membri del team e verifica le pipeline CI/CD per assicurarti che non ci siano operazioni concorrenti.

• Backend accessibile: se usi stato remoto, verifica la connettività a S3, Azure Storage o Terraform Cloud.

Un file di stato bloccato farà fallire l’import immediatamente con un errore di acquisizione del lock, quindi questo passaggio di coordinamento è critico negli ambienti di team.

Con l’ambiente validato, il passo successivo fondamentale è trovare l’identificatore esatto della risorsa che vuoi importare.

Individuare l’ID della risorsa

Gli ID delle risorse variano molto in base al provider e al tipo di risorsa, rendendo questo passaggio più insidioso di quanto sembri. Ecco esempi di provider comuni:

Per le risorse AWS, puoi trovare gli ID direttamente in console. Vai al servizio (EC2, S3, ecc.), seleziona la tua risorsa e copia l’identificatore dal pannello dei dettagli.

Per Azure, usa l’Azure CLI per recuperare il percorso completo della risorsa:

az resource show --name myresource --resource-group mygroup

L’output include l’ID completo della risorsa che ti servirà per l’import.

Ecco un tranello in cui sono caduto spesso: tentare di importare una risorsa dalla regione o sottoscrizione sbagliata. Se la tua configurazione del provider Terraform punta a us-east-1 ma la tua istanza EC2 si trova in us-west-2, l’import fallirà con "resource not found" anche se l’ID dell’istanza è corretto. 

Verifica sempre che l’ambito corrisponda alla configurazione del provider prima di procedere. Una volta ottenuto l’ID corretto, devi decidere quale metodo di import usare.

Scegliere la strategia di import

Hai due strade: il comando CLI terraform import o i blocchi import. Ecco come si confrontano:

Consiglio gli import block ai team che richiedono code review e piani riproducibili, e la CLI per correzioni rapide su versioni legacy.

Perché è importante? Gli import block trattano l’adozione dell’infrastruttura come codice, quindi gli import diventano parte del tuo workflow versionato con la stessa rigorosità di qualsiasi altra modifica infrastrutturale. Questo riduce il rischio di errori e crea una traccia di audit essenziale per compliance e coordinamento del team. 

Gli import block si integrano perfettamente con il tuo workflow Git esistente, permettendo ai colleghi di rivedere e approvare gli import come qualsiasi altra modifica. La CLI, pur essendo più veloce per attività individuali, non lascia tracce di audit e non è facilmente riproducibile tra ambienti.

Scelta la strategia, entriamo nel dettaglio di ciascun workflow, iniziando dall’approccio CLI tradizionale.

Workflow principale A: comando CLI Terraform Import

Ti guido attraverso il processo tradizionale basato su CLI. Anche se gli import block dichiarativi stanno diventando preferiti, capire il metodo CLI resta utile per versioni Terraform legacy e import isolati e rapidi.

Il primo passo nel workflow CLI è impostare il file di configurazione.

Preparare il blocco di destinazione

Prima di eseguire terraform import, devi definire un blocco resource nella tua configurazione. È un requisito imprescindibile: Terraform deve sapere dove mappare lo stato importato. Il blocco può essere vuoto o parzialmente compilato.

Ecco un esempio per importare un bucket AWS S3:

resource "aws_s3_bucket" "legacy_data" {
  # Configuration to be filled after import
}

Il tipo di risorsa (aws_s3_bucket) deve corrispondere esattamente al tipo di infrastruttura che stai importando. Il nome della risorsa (legacy_data) dovrebbe seguire le convenzioni di naming del tuo progetto. Usa nomi descrittivi come production_data_bucket piuttosto che generici bucket1.

Con il blocco della risorsa in posizione, sei pronto a eseguire il comando di import.

Eseguire l’import

Esegui terraform import <resource_address> <resource_id>. Per il nostro bucket S3:

terraform import aws_s3_bucket.legacy_data my-existing-bucket-name

Terraform recupera gli attributi correnti del bucket dalle API del provider e li registra nello stato. Vedrai:

aws_s3_bucket.legacy_data: Import complete! 
Imported aws_s3_bucket

Lo stato ora contiene la risorsa, ma la tua configurazione resta vuota o incompleta.

Qui inizia il vero lavoro: allineare il codice con lo stato importato.

Riconciliare la configurazione

Esegui terraform plan per vedere le differenze tra stato e configurazione. Vedrai attributi calcolati (valori in sola lettura come timestamp) e requisiti di configurazione espliciti che devi dichiarare.

Aggiorna la configurazione in modo incrementale usando i valori dall’output del plan. Se il plan propone di "sostituire" la risorsa, fermati. Indica incongruenze su argomenti immutabili, come regione o availability zone. Adegua la configurazione per corrispondere agli attributi immutabili della risorsa esistente.

Workflow principale B: Import Block di Terraform

Vediamo ora l’approccio moderno introdotto in Terraform 1.5. Gli import block trasformano l’import da comando imperativo a configurazione dichiarativa che vive accanto al tuo codice infrastrutturale.

Il vantaggio chiave è la riproducibilità e la visibilità per il team. Con gli import via CLI non c’è traccia nel codice di ciò che è stato importato. Con gli import block, ogni import è documentato, versionato e revisionabile tramite pull request.

Iniziamo creando l’import block vero e proprio.

Definire l’import block

Un import block ha due componenti: to (indirizzo di destinazione) e id (identificatore della risorsa):

import {
  to = aws_instance.web_server
  id = "i-0123456789abcdef0"
}

Questo fornisce visibilità nel controllo versione. I team possono rivedere gli import block nelle pull request prima dell’esecuzione. Metti gli import block in imports.tf per rimuoverli facilmente dopo import riusciti.

Ma è qui che gli import block brillano davvero: Terraform può generare automaticamente il codice di configurazione per te, eliminando il lavoro noioso di scrivere HCL da zero.

Generare la configurazione (Terraform 1.5+)

Gli import block abilitano la generazione automatica della configurazione. Esegui terraform plan -generate-config-out=generated.tf per pianificare l’import e scrivere contemporaneamente HCL completo.

Il file generato contiene ogni attributo con i suoi valori attuali. Rivedilo, rimuovi i default verbosi e integra la configurazione significativa nel tuo codebase. Questo previene errori comuni: attributi con nomi sbagliati, tipi errati e campi obbligatori mancanti. È particolarmente utile per risorse complesse.

Con la configurazione pronta, è il momento di eseguire l’import.

Applicare e finalizzare

Infine, esegui terraform apply per effettuare l’import e allineare lo stato con la configurazione. Terraform ti mostrerà esattamente cosa sta importando prima di apportare modifiche al file di stato.

Dopo l’applicazione riuscita, rimuovi gli import block dalla configurazione. Hanno svolto il loro compito e tenerli creerebbe confusione nelle esecuzioni future. Infine, esegui ancora terraform plan per verificare che non ci siano modifiche in sospeso, confermando che configurazione e stato sono perfettamente sincronizzati.

I workflow visti finora funzionano alla perfezione per risorse semplici e autonome. Ma l’infrastruttura di produzione è raramente così lineare. Affrontiamo la complessità reale di moduli, iterazioni e dipendenze.

Terraform Import per risorse complesse e moduli

L’infrastruttura reale raramente è costituita da risorse semplici e autonome. Le risorse gestite dai moduli richiedono una sintassi di indirizzamento speciale, che è la nostra prima sfida.

Importare nei moduli figli

Le risorse dei moduli richiedono un indirizzo a percorso completo: module.<module_name>.<resource_type>.<resource_name>, che può apparire così:

terraform import module.network.aws_vpc.main vpc-0abcdef123456789

Per trovare l’indirizzo corretto, usa terraform state list dopo un normale apply. Ti mostra esattamente come Terraform referenzia le risorse dei moduli. Sbagliare l’indirizzo crea voci duplicate nello stato, che Terraform proverà poi a creare al successivo apply.

Inoltre, quando importi in istanze di modulo con count o for_each, dovrai includere l’identificatore dell’istanza tra virgolette:

terraform import 'module.network[0].aws_vpc.main' vpc-0abcdef123456789

Oltre all’indirizzamento dei moduli, le risorse che usano i meta-argomenti count o for_each presentano un loro set di sfide.

Gestire count e for_each

Quando la tua configurazione Terraform usa count per creare più istanze di una risorsa, per l’import servirà la sintassi di array. Ad esempio, se la tua configurazione è così:

resource "aws_instance" "server" {
  count         = 3
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"
}

Importerai ciascuna istanza singolarmente usando il suo indice:

terraform import 'aws_instance.server[0]' i-0123456789abcdef0
terraform import 'aws_instance.server[1]' i-1234567890abcdef1
terraform import 'aws_instance.server[2]' i-2345678901abcdef2

Le risorse che usano for_each in configurazione richiedono invece chiavi stringa. Considera questo esempio:

resource "aws_instance" "server" {
  for_each      = toset(["web", "api", "worker"])
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t3.micro"
}

Qui importerai usando i nomi delle chiavi:

terraform import 'aws_instance.server["web"]' i-0123456789abcdef0
terraform import 'aws_instance.server["api"]' i-1234567890abcdef1
terraform import 'aws_instance.server["worker"]' i-2345678901abcdef2

Se incontri errori "index out of range", significa che il valore di count non corrisponde al numero di risorse che stai importando. La correzione è semplice: imposta il count corretto o definisci le chiavi for_each appropriate in configurazione prima di eseguire l’import.

Inoltre, dovrai pensare a come le risorse si relazionano tra loro, soprattutto con architetture complesse.

Gestire dipendenze ed effetti collaterali

Alcune risorse cloud non si importano come entità singole. Invece, si importano come più risorse Terraform: esempi comuni includono:

• Regole dei security group
• Associazioni di policy IAM
• Regole delle Network ACL

In questi casi, importa sempre prima le risorse "genitore". Ad esempio, importa le VPC prima delle subnet, i ruoli IAM prima delle associazioni di policy e i security group prima delle singole regole. Questo stabilisce la corretta catena di dipendenze nel file di stato.

Dopo l’import, rivedi la configurazione e dichiara esplicitamente le dipendenze usando depends_on dove il provider non le rileva automaticamente. Questo assicura che i futuri apply vengano eseguiti nell’ordine corretto, prevenendo errori come Terraform che tenta di creare una subnet prima che la sua VPC esista.

Con le risorse importate correttamente e configurate a dovere, la fase successiva si concentra su manutenzione a lungo termine e organizzazione.

Gestione dello stato e refactoring

Importare risorse è solo l’inizio. Il successo a lungo termine richiede una corretta gestione dello stato e occasionali refactoring.

La sicurezza dovrebbe essere la tua prima preoccupazione quando importi risorse di produzione.

Mettere in sicurezza uno stato sensibile

C’è qualcosa che coglie di sorpresa molti team: importare database o chiavi di cifratura inserisce valori sensibili, come password, chiavi private e stringhe di connessione, nel file di stato in chiaro. È una considerazione di sicurezza critica che devi affrontare subito.

La soluzione è usare backend remoti criptati. Per AWS significa S3 con opzione encrypt = true e, facoltativamente, cifratura KMS abilitata. Per Azure, usa Azure Storage con crittografia a riposo. Se utilizzi HCP Terraform / Terraform Cloud, lo stato è cifrato a riposo e in transito per impostazione predefinita, ma vorrai comunque verificare i controlli di accesso.

Inoltre, dopo aver importato risorse di produzione con dati sensibili, fai due ulteriori passaggi: verifica che i controlli di accesso all’archiviazione dello stato siano configurati correttamente e abilita l’audit logging per tracciare chi accede allo stato e quando. Queste misure creano una traccia di audit preziosa per la compliance.

Man mano che l’infrastruttura evolve, vorrai riorganizzare e rinominare le risorse importate.

Refactoring delle risorse importate

Hai due opzioni per rinominare le risorse: terraform state mv (imperativo) o i blocchi moved (dichiarativi). Preferisco i blocchi moved perché documentano la modifica nella cronologia del controllo versione:

moved {
  from = aws_instance.old_name
  to   = aws_instance.new_name
}

Oltre a rinominare, dovresti anche sostituire gli ID hard-coded con riferimenti a risorse. Invece di vpc_id = "vpc-123456", usa vpc_id = aws_vpc.main.id. Questo approccio costruisce grafi di dipendenza corretti che Terraform può usare per determinare il giusto ordine delle operazioni.

L’ultimo tassello della gestione dello stato è prevenire il drift futuro.

Rinforzare contro il drift

Dopo l’import, la policy più importante da stabilire è questa: tutte le modifiche passano da Terraform, non dalla console del cloud. È l’unico modo per prevenire il drift tra codice e realtà.

Tuttavia, alcuni attributi vanno in drift continuamente ma non necessitano di gestione. Per questi, usa l’argomento di lifecycle ignore_changes:

lifecycle {
  ignore_changes = [tags["LastModified"]]
}

Infine, stabilisci uno standard di "clean plan" in cui terraform plan mostra solo modifiche intenzionali. Prendi l’abitudine di eseguire spesso i plan, anche quando non stai distribuendo, per intercettare il drift presto, prima che diventi un problema serio.

Risoluzione dei problemi comuni con Terraform Import

Nonostante un’accurata preparazione, le operazioni di import possono fallire. Diagnostichiamo e risolviamo i problemi più comuni che incontrerai.

Le discrepanze tra address e ID sono le questioni più frequenti.

Risoluzione degli errori di address e ID

Ecco gli errori di import più comuni e come risolverli:

Resource address does not exist

• Causa: Terraform non trova il blocco resource nella configurazione
• Fix per import via CLI: Crea un blocco resource vuoto prima di eseguire il comando
• Fix per import block: Controlla errori di battitura nell’indirizzo to o percorsi di modulo errati

Cannot import non-existent remote object

• Causa: Formato ID errato o regione/sottoscrizione del provider non corretta
• Fix: Verifica che la configurazione del provider punti alla regione AWS, sottoscrizione Azure o progetto GCP corretti
• Controlla anche: Il formato dell’ID della risorsa nella documentazione del provider

Resource already managed

• Causa: Voci duplicate nello stato. La risorsa è già tracciata con un altro nome

• Fix: Esegui terraform state list per trovare i duplicati, poi usa terraform state rm per rimuovere la voce vecchia prima di re-importare

Prevenire sostituzioni accidentali

Una volta importate con successo le risorse, fai attenzione ai plan che vogliono sostituirle.

Se terraform plan mostra "forces replacement" dopo l’import, devi identificare quale argomento sta causando la ricreazione. Le cause comuni sono argomenti immutabili come gli AMI ID di EC2 o le availability zone. Non possono essere cambiati dopo la creazione della risorsa.

La soluzione è semplice: allinea la configurazione alla realtà. Copia i valori effettivi dall’output del plan nel tuo file di configurazione. 

E una regola di sicurezza fondamentale: non confermare né applicare se viene proposto di distruggere risorse critiche. È il segnale che qualcosa non va.

Affrontare i problemi del provider

A volte il problema non è nella tua configurazione, ma in come sono configurati i provider.

Gli errori "Provider configuration depends on non-var" si verificano quando il tuo provider impedisce l’uso di valori calcolati durante l’import. Terraform ha bisogno di una configurazione del provider statica per individuare la risorsa da importare.

Il workaround è un hard-coding temporaneo: sostituisci le impostazioni dinamiche del provider con valori letterali, esegui l’import, poi ripristina la configurazione dinamica. In alternativa, puoi usare variabili d’ambiente per l’autenticazione del provider, che Terraform può risolvere durante l’import.

Se l’ID della risorsa sembra corretto ma l’import fallisce comunque, controlla la sezione "Import" della documentazione del provider per i requisiti esatti di formato dell’ID. Alcune risorse usano ID composti con slash o due punti come separatori, e ottenere il formato esatto è essenziale.

Conclusione

Hai imparato a portare l’infrastruttura esistente sotto la gestione di Terraform usando sia i comandi CLI che gli import block. Prima di ogni import, segui questa checklist di sicurezza:

• Verifica che gli ID delle risorse siano corretti per il tuo provider
• Esegui il backup del file di stato (abilita il versioning sui backend remoti)
• Rivedi con attenzione i plan per sostituzioni inattese
• Conferma di essere nel workspace/ambiente corretto
• Fai test con risorse non critiche per prime

Tuttavia, l’import non finisce con terraform apply. Il vero lavoro inizia dopo: stabilire policy anti-drift, fare refactoring delle risorse importate per allinearle ai tuoi standard ed educare il team a gestire l’infrastruttura esclusivamente tramite codice. Questo cambiamento culturale è importante quanto l’implementazione tecnica.

Per il prossimo passo, ti consiglio di esplorare la manipolazione dello stato di Terraform con terraform state mv e terraform state rm. Questi comandi completano l’import aiutandoti a riorganizzare e fare refactoring del file di stato man mano che l’infrastruttura evolve.

Ti consiglio anche di dare un’occhiata alla nostra guida su usare Terraform con Docker e di prepararti al tuo prossimo colloquio con le nostre migliori domande di colloquio su Terraform.