IT

Applicazioni

Iniziare con Terraform

Scopri Terraform su Debian o Ubuntu: provider, plan, apply, gestione dello state e protezione dei segreti, con un esempio generico.

6 min di lettura, aggiornato il 18 novembre 2026

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.com e registry.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:

Terminale
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 version

Creare il progetto

Terminale
mkdir -p ~/terraform-demo
cd ~/terraform-demo

Dichiarare Terraform e i provider

Crea versions.tf:

hcl
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:

hcl
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:

hcl
ssh_user = "TUO_USER"

servers = {
  web1 = "IP_DEL_TUO_SERVER"
}

Descrivere le risorse

Crea un template di inventario inventory.tftpl:

Testo
[web]
%{ for name, ip in servers ~}
${name} ansible_host=${ip} ansible_user=${ssh_user}
%{ endfor ~}

Crea poi main.tf:

hcl
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:

hcl
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:

Testo
.terraform/
*.tfstate
*.tfstate.*
*.tfvars
*.tfplan
generated/

Versiona invece .terraform.lock.hcl, che fissa le versioni esatte dei provider.

Inizializzare e validare

Terminale
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:

Terminale
terraform plan -out=demo.tfplan
terraform apply demo.tfplan

In 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:

Terminale
terraform output
terraform output -raw inventory_path; echo
cat generated/inventory.ini
ls -l generated/
terraform plan

Il 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:

hcl
servers = {
  web1 = "IP_DEL_TUO_SERVER"
  web2 = "IP_SECONDO_SERVER"
}
Terminale
terraform plan -out=demo.tfplan
terraform apply demo.tfplan

Il 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:

Terminale
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:

Terminale
chmod 600 terraform.tfstate terraform.tfstate.backup demo.tfplan 2>/dev/null || true

Gestire i segreti

Non inserire segreti nei file .tf. Passali piuttosto tramite una variabile d'ambiente TF_VAR_:

hcl
variable "api_token" {
  description = "Token dell'API usata dal provider"
  type        = string
  sensitive   = true
}
Terminale
read -rs TF_VAR_api_token
export TF_VAR_api_token
terraform plan -out=demo.tfplan
unset TF_VAR_api_token

Se 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.

hcl
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:

hcl
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:

Terminale
terraform init -migrate-state

Usare 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:

hcl
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:

Terminale
sudo apt update
sudo apt install --only-upgrade terraform
terraform init -upgrade
terraform plan

Rileggi 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:

Terminale
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:

Terminale
terraform plan -destroy -out=destroy.tfplan
terraform apply destroy.tfplan

In 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:

Terminale
terraform init -upgrade

Backend 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:

Terminale
terraform force-unlock ID_BLOCCO

Saved 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:

Terminale
curl -I https://registry.terraform.io/.well-known/terraform.json

No 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.

Riferimenti