Iniziare con Terraform
Scopri Terraform su Debian o Ubuntu: provider, plan, apply, gestione dello state e protezione dei segreti, con un esempio generico.
In questa pagina
I tuoi valori
Inseriscili una volta: i comandi della guida si aggiornano.
Terraform descrive un'infrastruttura in file di testo, confronta questa descrizione con ciò che esiste già, poi applica solo le modifiche necessarie. Si basa sui provider, che sanno dialogare con un determinato servizio.
Questa guida presenta le basi con un esempio che funziona senza alcun account esterno: Terraform genera una password casuale, un inventario Ansible e un file di configurazione locale.
| Termine | Significato |
|---|---|
| Provider | Estensione che dà accesso a un servizio o a una risorsa |
| Risorsa | Oggetto gestito da Terraform |
| Variabile | Valore di input della configurazione |
| Output | Valore esposto dopo l'applicazione |
| Plan | Elenco delle modifiche proposte da Terraform |
| State | File che collega la configurazione agli oggetti reali |
Prerequisiti
- Una macchina con Debian 12/13 o Ubuntu 22.04/24.04: il tuo computer o un server di amministrazione
- Un utente che dispone di
sudo - Un accesso HTTPS in uscita verso
apt.releases.hashicorp.comeregistry.terraform.io
Terraform non è in ascolto su alcuna porta e questo esempio non richiede di aprire alcuna porta in ingresso.
Installare Terraform
Aggiungi il repository ufficiale di HashiCorp, poi installa il pacchetto:
sudo apt update
sudo apt install -y wget gpg lsb-release
wget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(grep -oP '(?<=UBUNTU_CODENAME=).*' /etc/os-release || lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update
sudo apt install -y terraform
terraform versionCreare il progetto
mkdir -p ~/terraform-demo
cd ~/terraform-demoDichiarare Terraform e i provider
Crea versions.tf:
terraform {
required_version = ">= 1.11"
required_providers {
local = {
source = "hashicorp/local"
version = "~> 2.9"
}
random = {
source = "hashicorp/random"
version = "~> 3.9"
}
}
}Dichiarare le variabili
Crea variables.tf:
variable "ssh_user" {
description = "Utente SSH dei server"
type = string
}
variable "servers" {
description = "Server da inserire nell'inventario (nome => indirizzo IP)"
type = map(string)
validation {
condition = length(var.servers) > 0
error_message = "Dichiara almeno un server."
}
}Assegna loro un valore in terraform.tfvars, caricato automaticamente:
ssh_user = "TUO_USER"
servers = {
web1 = "IP_DEL_TUO_SERVER"
}Descrivere le risorse
Crea un template di inventario inventory.tftpl:
[web]
%{ for name, ip in servers ~}
${name} ansible_host=${ip} ansible_user=${ssh_user}
%{ endfor ~}Crea poi main.tf:
resource "random_password" "app_token" {
length = 32
special = false
}
resource "local_file" "inventory" {
filename = "${path.module}/generated/inventory.ini"
file_permission = "0644"
content = templatefile("${path.module}/inventory.tftpl", {
servers = var.servers
ssh_user = var.ssh_user
})
}
resource "local_sensitive_file" "app_env" {
filename = "${path.module}/generated/app.env"
file_permission = "0600"
content = "APP_TOKEN=${random_password.app_token.result}\n"
}E outputs.tf:
output "inventory_path" {
description = "Percorso dell'inventario generato"
value = local_file.inventory.filename
}
output "app_token" {
description = "Token generato per l'applicazione"
value = random_password.app_token.result
sensitive = true
}Escludere i file locali da Git
Crea .gitignore prima del tuo primo commit:
.terraform/
*.tfstate
*.tfstate.*
*.tfvars
*.tfplan
generated/Versiona invece .terraform.lock.hcl, che fissa le versioni esatte dei provider.
Inizializzare e validare
terraform init
terraform fmt
terraform validate| Comando | Effetto |
|---|---|
terraform init |
Scarica i provider e prepara la cartella |
terraform fmt |
Normalizza la formattazione |
terraform validate |
Controlla la coerenza della configurazione |
Pianificare e applicare
Salva il plan per applicare esattamente ciò che hai riletto:
terraform plan -out=demo.tfplan
terraform apply demo.tfplanIn un plan, + indica una creazione, ~ una modifica, - un'eliminazione e -/+ una sostituzione. Leggi sempre queste righe prima di applicare, soprattutto le eliminazioni e le sostituzioni.
Verifica il risultato:
terraform output
terraform output -raw inventory_path; echo
cat generated/inventory.ini
ls -l generated/
terraform planIl file app.env deve avere i permessi -rw-------, l'output app_token deve comparire come <sensitive> e l'ultimo plan deve annunciare No changes.
Modificare l'infrastruttura
Aggiungi un server in terraform.tfvars:
servers = {
web1 = "IP_DEL_TUO_SERVER"
web2 = "IP_SECONDO_SERVER"
}terraform plan -out=demo.tfplan
terraform apply demo.tfplanIl plan annuncia la sostituzione del solo file di inventario (1 to add, 1 to destroy): il token resta identico. Il file generato può poi servire a un playbook, come nella guida Automatizzare i tuoi server con Ansible.
Capire lo state
Dopo apply, Terraform registra in terraform.tfstate ciò che gestisce. Consultalo con i comandi previsti, senza modificarlo a mano:
terraform state list
terraform state show local_file.inventory| Comando | Utilizzo |
|---|---|
terraform state list |
Elencare le risorse tracciate |
terraform state show INDIRIZZO |
Mostrare una risorsa |
terraform state mv ORIGINE DESTINAZIONE |
Rinominare una risorsa senza ricrearla |
terraform state rm INDIRIZZO |
Smettere di tracciare una risorsa, senza eliminarla |
terraform import INDIRIZZO ID |
Collegare un oggetto esistente, se il provider lo consente |
Limita al minimo i permessi dei file locali:
chmod 600 terraform.tfstate terraform.tfstate.backup demo.tfplan 2>/dev/null || trueGestire i segreti
Non inserire segreti nei file .tf. Passali piuttosto tramite una variabile d'ambiente TF_VAR_:
variable "api_token" {
description = "Token dell'API usata dal provider"
type = string
sensitive = true
}read -rs TF_VAR_api_token
export TF_VAR_api_token
terraform plan -out=demo.tfplan
unset TF_VAR_api_tokenSe il valore serve solo a configurare un provider o ad alimentare un argomento in sola scrittura (write-only), dichiaralo come effimero: Terraform non lo registra allora né nello state né nel plan.
variable "api_token" {
description = "Token dell'API usata dal provider"
type = string
sensitive = true
ephemeral = true
}Una variabile effimera va fornita di nuovo durante terraform apply e non può essere usata in qualsiasi argomento. Per una cassaforte di segreti, consulta la guida Installare HashiCorp Vault.
Archiviare lo state in remoto
Non appena più persone o macchine usano il progetto, metti lo state in uno storage remoto, cifrato, privato e con locking. Ecco un esempio generico con il backend s3 da aggiungere nel blocco terraform:
terraform {
backend "s3" {
bucket = "mon-etat-terraform"
key = "demo/terraform.tfstate"
region = "eu-west-1"
encrypt = true
use_lockfile = true
}
}Fornisci le credenziali tramite l'ambiente, mai in questo blocco, poi migra lo state esistente:
terraform init -migrate-stateUsare un altro provider
La logica resta la stessa per qualsiasi servizio che disponga di un provider. Cercalo nel registry Terraform, leggi la sua documentazione e verifica chi lo mantiene. La forma generale è la seguente. editeur/service e gli argomenti sono fittizi:
terraform {
required_providers {
service = {
source = "editeur/service"
version = "~> 1.0"
}
}
}
provider "service" {
api_token = var.api_token
}Assegna al token dell'API i permessi strettamente necessari e inizia su un progetto di prova: un apply agisce realmente sulle risorse dell'account.
Aggiornare
Terraform si aggiorna con APT. I provider si aggiornano entro i limiti di version:
sudo apt update
sudo apt install --only-upgrade terraform
terraform init -upgrade
terraform planRileggi il plan, poi versiona il file .terraform.lock.hcl se è cambiato.
Eseguire il backup
Conserva la configurazione e .terraform.lock.hcl in un repository Git privato. Per lo state, attiva il versioning dello storage remoto. Con uno state locale, crea una copia protetta:
install -m 600 /dev/null "$HOME/terraform-demo-$(date +%F).tfstate"
terraform state pull > "$HOME/terraform-demo-$(date +%F).tfstate"Questa copia contiene segreti: conservala cifrata e fuori dal server. Se lo state va perso, Terraform non sa più quali oggetti gestisce.
Distruggere le risorse
Visualizza in anteprima l'eliminazione, poi applicala:
terraform plan -destroy -out=destroy.tfplan
terraform apply destroy.tfplanIn questo esempio vengono eliminati solo i file locali e il token. Con un provider reale, questa operazione può cancellare servizi e relativi dati.
In caso di problemi
Inconsistent dependency lock file
I provider richiesti non corrispondono al file di lock. Dopo aver verificato la modifica:
terraform init -upgradeBackend initialization required
La configurazione del backend è cambiata. Esegui di nuovo terraform init, oppure terraform init -migrate-state per spostare lo state.
Error acquiring the state lock
Un'altra esecuzione detiene il lock, oppure un'esecuzione si è interrotta. Verifica prima che nessun comando sia in corso. Solo dopo, usa l'identificativo mostrato:
terraform force-unlock ID_BLOCCOSaved plan is stale
Lo state è cambiato dopo la creazione del plan. Genera un nuovo plan, rileggilo, poi applicalo.
Failed to query available provider packages
Verifica il nome del provider, il vincolo version e l'accesso a registry.terraform.io:
curl -I https://registry.terraform.io/.well-known/terraform.jsonNo value for required variable
Imposta la variabile in terraform.tfvars, con -var, oppure con TF_VAR_nome.
Il plan vuole sostituire una risorsa
Cerca la dicitura forces replacement nel plan. Se hai solo rinominato una risorsa, usa terraform state mv o un blocco moved invece di accettarne la ricreazione.