Automatizzare i tuoi server con Ansible
Inizia con Ansible: installazione, inventario, playbook, ruoli e cifratura dei segreti con Ansible Vault per i tuoi server Debian e Ubuntu.
In questa pagina
I tuoi valori
Inseriscili una volta: i comandi della guida si aggiornano.
Ansible permette di descrivere la configurazione dei tuoi server in file YAML e di applicarla tramite SSH. Non occorre installare alcun agente sui server gestiti: servono solo SSH e Python.
In questa guida creerai un piccolo progetto che installa Nginx, pubblica una pagina di prova e salva un segreto cifrato con Ansible Vault.
| Termine | Significato |
|---|---|
| Nodo di controllo | Macchina su cui è installato Ansible e da cui lanci i comandi |
| Nodo gestito | Server amministrato da Ansible |
| Inventario | Elenco dei server e dei loro gruppi |
| Task | Azione singola, affidata a un modulo |
| Playbook | File YAML che associa task e server |
| Ruolo | Insieme riutilizzabile di task, template e variabili |
| Vault | Meccanismo di cifratura dei dati sensibili |
Prerequisiti
- Un nodo di controllo con Linux: il tuo computer o un server di amministrazione
- Uno o più server gestiti con Debian 12/13 o Ubuntu 22.04/24.04
- Un utente SSH su ogni server gestito, membro del gruppo
sudo - Un'autenticazione SSH a chiave
- La porta SSH raggiungibile dal nodo di controllo e la porta 80 per la pagina di prova
Scegliere il nodo di controllo
La versione di Ansible disponibile dipende da quella di Python sul nodo di controllo:
| Sistema del nodo di controllo | Python | Versione installata da pipx |
Stato |
|---|---|---|---|
| Debian 13 | 3.13 | Ansible 15 (ansible-core 2.22) |
Consigliato |
| Ubuntu 24.04 | 3.12 | Ansible 14 (ansible-core 2.21) |
Consigliato |
| Debian 12 | 3.11 | Ansible 12 (ansible-core 2.19) |
Fine vita a novembre 2026 |
| Ubuntu 22.04 | 3.10 | Ansible 10 (ansible-core 2.17) |
Fine vita |
Questo vincolo riguarda il nodo di controllo. Debian 12 e Ubuntu 22.04 restano utilizzabili come server gestiti.
Installare Ansible
Sul nodo di controllo, installa Ansible con pipx, un metodo descritto nella documentazione ufficiale:
sudo apt update
sudo apt install -y pipx
pipx ensurepathChiudi e riapri la sessione per applicare il PATH, poi installa il pacchetto completo:
pipx install --include-deps ansible
ansible --versionPreparare l'accesso SSH
Crea una chiave se non ne hai una, poi copiala sul server gestito:
ssh-keygen -t ed25519 -C "ansible"
ssh-copy-id TUO_USER@IP_DEL_TUO_SERVER
ssh -t TUO_USER@IP_DEL_TUO_SERVER 'python3 --version && sudo -v'Alla prima connessione ti viene chiesto di confermare l'impronta del server: verificala, perché in seguito Ansible rifiuterà un host sconosciuto. Per rafforzare l'accesso SSH, consulta la guida Proteggi il tuo server.
Creare il progetto
mkdir -p ~/infra/group_vars/web
cd ~/infra
nano ansible.cfg[defaults]
inventory = inventory.ini
roles_path = rolesScrivere l'inventario
nano inventory.ini[web]
web1 ansible_host=IP_DEL_TUO_SERVER ansible_user=TUO_USERSe la tua porta SSH non è la 22, aggiungi ansible_port=TUA_PORTA sulla riga del server. Controlla poi l'inventario e la connessione:
ansible-inventory --graph
ansible all -m ansible.builtin.ping
ansible web -m ansible.builtin.command -a "uptime"Il modulo ping deve rispondere pong. Verifica la connessione SSH e Python: non è un ping di rete.
Scrivere un primo playbook
nano premier-playbook.yml---
- name: Preparare i server web
hosts: web
become: true
tasks:
- name: Installare Nginx
ansible.builtin.apt:
name: nginx
state: present
update_cache: true
cache_valid_time: 3600
- name: Attivare e avviare Nginx
ansible.builtin.service:
name: nginx
state: started
enabled: truebecome: true esegue i task con sudo. Prova prima senza modificare nulla, poi applica:
ansible-playbook premier-playbook.yml --check --diff
ansible-playbook premier-playbook.ymlAggiungi --ask-become-pass se sudo chiede una password. Esegui poi di nuovo il playbook: il riepilogo deve indicare changed=0, perché lo stato desiderato è già stato raggiunto. È il principio di idempotenza.
Organizzare il codice con un ruolo
Genera la struttura di un ruolo chiamato web:
ansible-galaxy role init --init-path roles webVariabili predefinite
File roles/web/defaults/main.yml:
---
web_domain: tuo-dominio.com
web_root: /var/www/demo
app_config_dir: /etc/demo-appTask
File roles/web/tasks/main.yml:
---
- name: Installare Nginx
ansible.builtin.apt:
name: nginx
state: present
update_cache: true
cache_valid_time: 3600
- name: Creare la cartella del sito
ansible.builtin.file:
path: "{{ web_root }}"
state: directory
owner: root
group: root
mode: "0755"
- name: Pubblicare la pagina di prova
ansible.builtin.copy:
dest: "{{ web_root }}/index.html"
content: "<h1>Server gestito da Ansible: {{ inventory_hostname }}</h1>\n"
owner: root
group: root
mode: "0644"
- name: Distribuire la configurazione del sito
ansible.builtin.template:
src: site.conf.j2
dest: /etc/nginx/sites-available/demo.conf
owner: root
group: root
mode: "0644"
notify: Ricaricare Nginx
- name: Attivare il sito
ansible.builtin.file:
src: /etc/nginx/sites-available/demo.conf
dest: /etc/nginx/sites-enabled/demo.conf
state: link
notify: Ricaricare Nginx
- name: Creare la cartella di configurazione dell'applicazione
ansible.builtin.file:
path: "{{ app_config_dir }}"
state: directory
owner: root
group: root
mode: "0750"
- name: Salvare il segreto dell'applicazione
ansible.builtin.copy:
dest: "{{ app_config_dir }}/app.env"
content: "APP_TOKEN={{ app_token }}\n"
owner: root
group: root
mode: "0600"
no_log: true
- name: Attivare e avviare Nginx
ansible.builtin.service:
name: nginx
state: started
enabled: trueno_log: true impedisce al segreto di comparire nell'output di Ansible.
Handler
File roles/web/handlers/main.yml. Un handler viene eseguito solo se un task lo ha notificato, una sola volta, alla fine della serie di task:
---
- name: Ricaricare Nginx
ansible.builtin.service:
name: nginx
state: reloadedTemplate Jinja2
File roles/web/templates/site.conf.j2:
server {
listen 80;
listen [::]:80;
server_name {{ web_domain }};
root {{ web_root }};
index index.html;
location / {
try_files $uri $uri/ =404;
}
}Playbook principale
File site.yml, nella radice del progetto:
---
- name: Configurare i server web
hosts: web
become: true
roles:
- webProteggere i segreti con Ansible Vault
Separa le variabili ordinarie da quelle cifrate. Il file group_vars/web/vars.yml resta leggibile e fa riferimento al segreto:
---
app_token: "{{ vault_app_token }}"Crea il file cifrato. Scegli una password robusta quando il comando te lo chiede:
EDITOR=nano ansible-vault create group_vars/web/vault.ymlScrivici il segreto:
---
vault_app_token: "SOSTITUISCI_CON_IL_TUO_SEGRETO"Una volta salvato, il file inizia con $ANSIBLE_VAULT e il suo contenuto è illeggibile. I comandi utili sono:
| Comando | Effetto |
|---|---|
ansible-vault view group_vars/web/vault.yml |
Mostrare il contenuto |
ansible-vault edit group_vars/web/vault.yml |
Modificare il contenuto |
ansible-vault rekey group_vars/web/vault.yml |
Cambiare la password |
Avviare la distribuzione
Consenti il traffico web sul server gestito se UFW è attivo, poi lancia una simulazione e la distribuzione:
ssh -t TUO_USER@IP_DEL_TUO_SERVER 'sudo ufw allow 80/tcp'
ansible-playbook site.yml --syntax-check --ask-vault-pass
ansible-playbook site.yml --check --diff --ask-vault-pass
ansible-playbook site.yml --ask-vault-passPer automatizzare, conserva la password in un file fuori dal progetto:
install -m 600 /dev/null ~/.ansible-vault-infra
nano ~/.ansible-vault-infra
ansible-playbook site.yml --vault-password-file ~/.ansible-vault-infraVerificare il risultato
curl -H 'Host: tuo-dominio.com' http://IP_DEL_TUO_SERVER/
ansible web -b -m ansible.builtin.stat -a "path=/etc/demo-app/app.env"
ansible-playbook site.yml --ask-vault-passLa pagina deve mostrare il nome web1, il file app.env deve avere la modalità 0600 e l'ultima esecuzione deve concludersi con changed=0.
Questa pagina di prova viene servita in HTTP. Per un sito vero, aggiungi un certificato seguendo la guida Installare un certificato SSL con Let's Encrypt.
Versionare ed eseguire il backup del progetto
Ansible non conserva alcuno stato: il tuo progetto è il riferimento. Mettilo in un repository Git privato ed escludi i file locali:
cd ~/infra
git init
printf '%s\n' '*.retry' '.vault-pass*' > .gitignore
git add .
git status
git commit -m "Progetto Ansible iniziale"Prima del primo commit, verifica che group_vars/web/vault.yml sia davvero cifrato:
head -n 1 group_vars/web/vault.ymlSalva la password di Vault in un gestore di password, separatamente dal repository: senza di essa, i segreti sono irrecuperabili.
Aggiornare Ansible
pipx upgrade --include-injected ansible
ansible --versionSe usi il PPA, esegui sudo apt update e poi sudo apt install --only-upgrade ansible. Dopo un aggiornamento maggiore, consulta la guida alla migrazione ed esegui di nuovo i tuoi playbook con --check --diff.
In caso di problemi
ansible: command not found
La cartella di pipx non è nel PATH. Esegui pipx ensurepath, poi apri una nuova sessione.
UNREACHABLE e Permission denied (publickey,password)
Prova la connessione con gli stessi parametri, poi esegui di nuovo Ansible in modalità dettagliata:
ssh -p 22 TUO_USER@IP_DEL_TUO_SERVER
ansible all -m ansible.builtin.ping -vvvVerifica ansible_host, ansible_user, ansible_port e la chiave utilizzata.
Host key verification failed
L'impronta del server è sconosciuta o è cambiata. Dopo una reinstallazione legittima, elimina la vecchia voce, poi riconnettiti e verifica la nuova impronta:
ssh-keygen -R IP_DEL_TUO_SERVER
ssh TUO_USER@IP_DEL_TUO_SERVERMissing sudo password
Aggiungi --ask-become-pass, oppure configura sudo secondo la tua politica di sicurezza.
Attempting to decrypt but no vault secrets found
Il playbook legge un file cifrato senza password. Aggiungi --ask-vault-pass o --vault-password-file.
Decryption failed
La password non corrisponde a quella del file. Verifica anche che il file della password non contenga un altro valore.
Could not get lock /var/lib/dpkg/lock-frontend
Un'altra operazione APT è in corso, spesso gli aggiornamenti automatici. Attendi la fine dell'operazione, oppure aggiungi lock_timeout: 300 al task ansible.builtin.apt.
Ansible ignora ansible.cfg
Ansible ignora questo file se la cartella corrente è scrivibile da tutti. Correggi i permessi con chmod o-w ~/infra, poi controlla il risultato con ansible --version, che indica il file caricato.
Per approfondire
Per creare l'infrastruttura o generare file prima di configurarla, consulta la guida Iniziare con Terraform. Per centralizzare i tuoi segreti, consulta Installare HashiCorp Vault.