Estação de Trabalho como Código (Parte 7): Infraestrutura como Código com Terraform e LIBVIRT

Tutorial Anterior: Estação de Trabalho como Código (Parte 6): Virtualizando com KVM e LIBVIRT

Introdução

Criar máquinas virtuais manualmente com virt-install é útil para testes rápidos, mas não é escalável. Quando você precisa gerenciar dezenas de VMs, com configurações específicas, redes e armazenamento, a abordagem manual se torna insustentável. É aqui que entra o Terraform, uma ferramenta de infraestrutura como código (IaC) que permite definir sua infraestrutura em arquivos de configuração legíveis e versionáveis.

Neste tutorial, vamos aprender a usar Terraform com o provider LIBVIRT para criar e gerenciar máquinas virtuais de forma declarativa. Você definirá o estado desejado da sua infraestrutura em arquivos HCL (HashiCorp Configuration Language), e o Terraform cuidará de criar, atualizar ou destruir recursos conforme necessário.

Observação: Esta parte é essencial para automatizar a criação de infraestrutura. Se você preferir gerenciar VMs manualmente, pode pular para a Parte 8 (Packer). No entanto, recomendamos completar esta parte para entender infraestrutura como código.

Objetivos desta Parte

• Entender o que é Terraform, HCL e como funcionam
• Instalar o Terraform no Ubuntu 24.04
• Configurar o provider LIBVIRT v0.9.2 para Terraform
• Criar uma estrutura modular de código Terraform
• Definir máquinas virtuais, volumes e redes usando Terraform
• Aprender comandos essenciais do Terraform (init, plan, apply, destroy)
• Configurar Cloud-Init para personalização de VMs
• Gerenciar estado do Terraform e versionar no Git

Pré-requisitos

• Conclusão da Parte 6 desta série
• KVM e LIBVIRT funcionando corretamente
• Pools de armazenamento configurados (images, templates, isos)
• Rede lab-network criada

A quem se destina

Este tutorial é ideal para:

• DevOps Engineers: Que precisam automatizar criação de infraestrutura
• SysAdmins: Que querem aprender infraestrutura como código
• Desenvolvedores: Que precisam de ambientes reproduzíveis
• Profissionais de TI: Que querem experimentar com IaC

Pré-conhecimento: Conhecimento básico de linha de comando e conceitos de virtualização (coberto nas partes anteriores) é recomendado.

Tempo Estimado

⏱ 75-90 minutos

Isso inclui:

• Leitura e compreensão: ~15 min
• Instalação do Terraform: ~10 min
• Preparação de imagem base: ~10 min
• Configuração de Terraform: ~15 min
• Criação de primeira VM: ~15 min
• Exploração de recursos: ~10 min

Dica Útil: Se você quiser apenas copiar e colar, pode fazer em 50 minutos. Mas recomendamos ler e entender cada seção.

---

Entendendo Terraform, HCL e Provider LIBVIRT

Antes de começar a instalar, é importante entender os conceitos fundamentais.

O que é Terraform?

Terraform é uma ferramenta de infraestrutura como código (IaC) que permite definir, provisionar e gerenciar infraestrutura usando arquivos de configuração declarativos. Em vez de executar comandos manualmente, você descreve o estado desejado da sua infraestrutura, e o Terraform cuidará de criar, atualizar ou destruir recursos conforme necessário.

O que é HCL?

HCL (HashiCorp Configuration Language) é uma linguagem de configuração criada pela HashiCorp, projetada para ser legível e expressiva. É usada em ferramentas como Terraform, Packer e Vault. HCL é declarativa, o que significa que você descreve o que quer, não como fazer.

O que é Provider LIBVIRT?

Um provider é um plugin que Terraform usa para interagir com uma plataforma específica. O provider LIBVIRT permite que Terraform crie e gerencie máquinas virtuais no LIBVIRT usando a API do LIBVIRT.

Como Funcionam Juntos?

Componente	Função
Terraform	Orquestra criação de recursos
HCL	Define configuração desejada
Provider LIBVIRT	Comunica com LIBVIRT
LIBVIRT	Gerencia VMs no KVM

Quando você executa terraform apply, o fluxo é:

1. Terraform lê arquivos HCL
2. Terraform conecta ao provider LIBVIRT
3. Provider LIBVIRT comunica com LIBVIRT
4. LIBVIRT cria VM no KVM
5. Terraform salva estado em arquivo terraform.tfstate

---

Verificando Pré-Requisitos

Antes de instalar, certifique-se de que seu ambiente está pronto.

Passo 1: Verificar LIBVIRT

# Verifique se libvirtd está rodando
$ systemctl is-active libvirtd

# Você deve ver:
# active

# Verifique pools
$ virsh pool-list

# Você deve ver:
#  Name       State    Autostart
# -----------+----------+-----------
#  images     active   yes
#  templates  active   yes
#  isos       active   yes

Passo 2: Verificar Rede

# Verifique redes
$ virsh net-list

# Você deve ver:
#  Name          State    Autostart   Persistent
# ---------------+---------+-----------+-----------
#  default       active   yes         yes
#  lab-network   active   yes         yes

Passo 3: Verificar Imagem Base

# Verifique se tem imagem base
$ ls -lh ~/workspace-as-code/kvm/templates/

# Você deve ter pelo menos uma imagem
# Se não tiver, baixe uma:
$ wget https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2 \
  -O ~/workspace-as-code/kvm/templates/debian-12-genericcloud-amd64.qcow2

---

Instalando o Terraform

Passo 1: Adicionar Repositório HashiCorp

# Adicione a chave GPG
$ wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg

# Adicione o repositório
$ echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list

# Atualize
$ sudo apt update

Informação: Este repositório será usado também para instalar Packer na Parte 8.

Passo 2: Instalar Terraform

# Instale Terraform
$ sudo apt install -y terraform

# Verifique a instalação
$ terraform --version

# Você deve ver:
# Terraform v1.14.5
# on linux_amd64

Passo 3: Configurar Autocompletar

# Configure autocompletar para bash
$ terraform -install-autocomplete

# Recarregue o shell
$ exec bash

---

Preparando Imagem Base

Passo 1: Baixar Imagem Cloud

Vamos usar uma imagem oficial do Debian como base. Na Parte 8 (Packer), você aprenderá a criar suas próprias imagens.

# Baixe a imagem Debian 12
$ wget https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2 \
  -O ~/workspace-as-code/kvm/templates/debian-12-genericcloud-amd64.qcow2

# Verifique o download
$ ls -lh ~/workspace-as-code/kvm/templates/

# Você deve ver:
# -rw-r--r-- debian-12-genericcloud-amd64.qcow2 (~ 300 MB)

Passo 2: Inspecionar Imagem

# Obtenha informações sobre a imagem
$ qemu-img info ~/workspace-as-code/kvm/templates/debian-12-genericcloud-amd64.qcow2

# Você deve ver:
# image: /home/ubuntu/workspace-as-code/kvm/templates/debian-12-genericcloud-amd64.qcow2
# file format: qcow2
# virtual size: 2 GiB
# disk size: 300 MiB

---

Criando Estrutura Terraform

Passo 1: Criar Diretórios

# Crie a estrutura de diretórios
$ mkdir -p ~/workspace-as-code/terraform/libvirt/debian12
$ cd ~/workspace-as-code/terraform/libvirt/debian12

# Verifique
$ pwd
# /home/ubuntu/workspace-as-code/terraform/libvirt/debian12

Passo 2: Gerar Chave SSH

# Gere uma chave SSH para acessar as VMs
$ ssh-keygen -t ed25519 -f ~/.ssh/terraform-vms -N ""

# Verifique
$ ls -la ~/.ssh/terraform-vms*

# Você deve ver:
# -rw------- terraform-vms
# -rw-r--r-- terraform-vms.pub

---

Configurando Terraform

Passo 1: Criar Arquivo main.tf

# Crie o arquivo principal de configuração
$ cat > ~/workspace-as-code/terraform/libvirt/debian12/main.tf << 'EOF'
terraform {
  required_providers {
    libvirt = {
      source  = "dmacvicar/libvirt"
      version = "~> 0.9.2"
    }
  }
}

provider "libvirt" {
  uri = "qemu:///system"
}

# Volume para a imagem base
resource "libvirt_volume" "debian_base" {
  name   = "debian-12-base.qcow2"
  pool   = "templates"
  source = "/home/ubuntu/workspace-as-code/kvm/templates/debian-12-genericcloud-amd64.qcow2"
  format = "qcow2"
}

# Volume para a VM (cópia da imagem base)
resource "libvirt_volume" "vm_disk" {
  name           = "terraform-vm-01.qcow2"
  pool           = "images"
  base_volume_id = libvirt_volume.debian_base.id
  format         = "qcow2"
}

# Cloud-Init para configuração inicial
resource "libvirt_cloudinit_disk" "cloudinit" {
  name           = "terraform-vm-01-cloudinit.iso"
  user_data      = base64encode(file("${path.module}/cloud-init.yml"))
  pool           = "images"
}

# Máquina Virtual
resource "libvirt_domain" "terraform_vm" {
  name   = "terraform-vm-01"
  memory = "2048"
  vcpu   = 2

  cpu {
    mode = "host-passthrough"
  }

  cloudinit = libvirt_cloudinit_disk.cloudinit.id

  network_interface {
    network_name   = "lab-network"
    wait_for_lease = true
  }

  console {
    type        = "pty"
    target_port = "0"
    target_type = "serial"
  }

  disk {
    volume_id = libvirt_volume.vm_disk.id
  }

  graphics {
    type        = "spice"
    listen_type = "none"
  }

  depends_on = [libvirt_volume.debian_base]
}

# Output com o IP da VM
output "vm_ip" {
  value       = libvirt_domain.terraform_vm.network_interface[0].addresses[0]
  description = "IP da máquina virtual"
}

# Output com o nome da VM
output "vm_name" {
  value       = libvirt_domain.terraform_vm.name
  description = "Nome da máquina virtual"
}
EOF

# Verifique
$ cat ~/workspace-as-code/terraform/libvirt/debian12/main.tf

Passo 2: Criar Arquivo cloud-init.yml

# Crie o arquivo de configuração Cloud-Init
$ cat > ~/workspace-as-code/terraform/libvirt/debian12/cloud-init.yml << 'EOF'
#cloud-config

# Gerenciar /etc/hosts
manage_etc_hosts: true

# Hostname
hostname: terraform-vm-01
fqdn: terraform-vm-01.lab

# Usuários
users:
  - name: ubuntu
    gecos: "Ubuntu User"
    sudo: "ALL=(ALL) NOPASSWD:ALL"
    groups: users, sudo, docker
    shell: /bin/bash
    lock_passwd: false
    ssh_authorized_keys:
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJxZ... # Será substituído

# Permitir SSH com senha
ssh_pwauth: true

# Configurar senha do root
chpasswd:
  list: |
    root: password123
  expire: false

# Comandos a executar
runcmd:
  - apt-get update
  - apt-get upgrade -y
  - apt-get install -y curl wget git vim htop
  - echo "Cloud-Init concluído" > /var/log/cloud-init-custom.log

# Pacotes a instalar
packages:
  - curl
  - wget
  - git
  - vim
  - htop
  - net-tools
EOF

# Verifique
$ cat ~/workspace-as-code/terraform/libvirt/debian12/cloud-init.yml

Passo 3: Criar Arquivo variables.tf

# Crie arquivo com variáveis
$ cat > ~/workspace-as-code/terraform/libvirt/debian12/variables.tf << 'EOF'
variable "vm_name" {
  description = "Nome da máquina virtual"
  type        = string
  default     = "terraform-vm-01"
}

variable "vm_memory" {
  description = "Memória em MB"
  type        = number
  default     = 2048
}

variable "vm_vcpu" {
  description = "Número de vCPUs"
  type        = number
  default     = 2
}

variable "vm_disk_size" {
  description = "Tamanho do disco em GB"
  type        = number
  default     = 20
}

variable "network_name" {
  description = "Nome da rede"
  type        = string
  default     = "lab-network"
}

variable "pool_name" {
  description = "Nome do pool de armazenamento"
  type        = string
  default     = "images"
}
EOF

# Verifique
$ cat ~/workspace-as-code/terraform/libvirt/debian12/variables.tf

Passo 4: Criar Arquivo terraform.tfvars

# Crie arquivo com valores das variáveis
$ cat > ~/workspace-as-code/terraform/libvirt/debian12/terraform.tfvars << 'EOF'
vm_name      = "terraform-vm-01"
vm_memory    = 2048
vm_vcpu      = 2
vm_disk_size = 20
network_name = "lab-network"
pool_name    = "images"
EOF

# Verifique
$ cat ~/workspace-as-code/terraform/libvirt/debian12/terraform.tfvars

---

Executando Terraform

Passo 1: Inicializar Terraform

# Navegue para o diretório
$ cd ~/workspace-as-code/terraform/libvirt/debian12

# Inicialize Terraform
$ terraform init

# Você deve ver:
# Initializing the backend...
# Initializing provider plugins...
# - Finding dmacvicar/libvirt versions matching "~> 0.9.2"...
# - Installing dmacvicar/libvirt v0.9.2...
# Terraform has been successfully initialized!

Passo 2: Validar Configuração

# Valide a sintaxe
$ terraform validate

# Você deve ver:
# Success! The configuration is valid.

# Formate os arquivos
$ terraform fmt

# Você deve ver:
# main.tf

Passo 3: Planejar Mudanças

# Veja o que será criado
$ terraform plan

# Você deve ver:
# Plan: 3 to add, 0 to change, 0 to destroy.
# 
# Changes to Outputs:
#   + vm_ip   = (known after apply)
#   + vm_name = (known after apply)

Passo 4: Aplicar Configuração

# Crie os recursos
$ terraform apply

# Digite 'yes' quando solicitado
# Você deve ver:
# Apply complete! Resources: 3 added, 0 changed, 0 destroyed.
#
# Outputs:
#
# vm_ip   = "192.168.123.50"
# vm_name = "terraform-vm-01"

---

Verificando Máquina Virtual

Passo 1: Listar VMs

# Liste as VMs
$ virsh list

# Você deve ver:
#  Id   Name                State
# ----+---------------------+--------
#  1   terraform-vm-01     running

Passo 2: Obter Informações

# Obtenha informações sobre a VM
$ virsh dominfo terraform-vm-01

# Você deve ver:
# Name:           terraform-vm-01
# UUID:           12345678-1234-1234-1234-123456789012
# OS Type:        hvm
# State:          running
# CPU(s):         2
# Memory:         2048 KiB

Passo 3: Verificar IP

# Obtenha o IP da VM
$ virsh domifaddr terraform-vm-01

# Você deve ver:
#  Name       MAC address          Protocol     Address
# -----------+---------------------+----------+------------------
#  vnet0      52:54:00:12:34:56     ipv4       192.168.123.50/24

Passo 4: Conectar à VM

# Conecte via SSH (após alguns segundos para Cloud-Init)
$ ssh ubuntu@192.168.123.50

# Você deve ver o prompt da VM
# ubuntu@terraform-vm-01:~$

---

Exemplos Práticos

Exemplo 1: Criar Múltiplas VMs

# Crie um arquivo chamado multi-vm.tf
resource "libvirt_domain" "multi_vms" {
  count  = 3
  name   = "terraform-vm-${count.index + 1}"
  memory = "2048"
  vcpu   = 2

  cpu {
    mode = "host-passthrough"
  }

  cloudinit = libvirt_cloudinit_disk.cloudinit.id

  network_interface {
    network_name   = "lab-network"
    wait_for_lease = true
  }

  disk {
    volume_id = libvirt_volume.vm_disk[count.index].id
  }

  graphics {
    type        = "spice"
    listen_type = "none"
  }
}

Exemplo 2: Usar Variáveis

# Use variáveis para configurações
resource "libvirt_domain" "custom_vm" {
  name   = var.vm_name
  memory = var.vm_memory
  vcpu   = var.vm_vcpu

  # ... resto da configuração
}

Exemplo 3: Criar Snapshots

# Crie snapshots para backup
resource "libvirt_domain_snapshot" "vm_snapshot" {
  name           = "terraform-vm-01-snapshot-1"
  domain_name    = libvirt_domain.terraform_vm.name
  description    = "Snapshot de backup"
}

---

Tabela de Comandos Terraform

Comando	Descrição
terraform init	Inicializa diretório Terraform
terraform validate	Valida sintaxe dos arquivos
terraform fmt	Formata arquivos HCL
terraform plan	Mostra mudanças que serão aplicadas
terraform apply	Aplica mudanças
terraform destroy	Destrói recursos
terraform state list	Lista recursos no estado
terraform state show	Mostra detalhes de um recurso
terraform output	Mostra outputs
terraform refresh	Atualiza estado
terraform import	Importa recurso existente

---

Troubleshooting

Erro: “Provider not found”

Problema: Provider LIBVIRT não foi instalado.

Solução:

# Execute terraform init novamente
$ terraform init

# Ou force reinicialização
$ rm -rf .terraform
$ terraform init

Erro: “Connection refused”

Problema: LIBVIRT não está rodando.

Solução:

# Inicie libvirtd
$ sudo systemctl start libvirtd

# Verifique
$ sudo systemctl status libvirtd

Erro: “Pool not found”

Problema: Pool de armazenamento não existe.

Solução:

# Verifique pools
$ virsh pool-list

# Se não existir, crie
$ virsh pool-define-as images --type dir --target ~/workspace-as-code/kvm/images
$ virsh pool-start images
$ virsh pool-autostart images

Erro: “Network not found”

Problema: Rede não foi criada.

Solução:

# Verifique redes
$ virsh net-list

# Se não existir, crie
$ virsh net-define ~/workspace-as-code/kvm/lab-network.xml
$ virsh net-start lab-network
$ virsh net-autostart lab-network

Erro: “Disk space insufficient”

Problema: Não há espaço em disco.

Solução:

# Verifique espaço
$ df -h ~/workspace-as-code/kvm/

# Libere espaço ou mude pool
$ virsh pool-edit images

Cloud-Init não executou

Problema: Configuração Cloud-Init não foi aplicada.

Solução:

# Conecte à VM e verifique logs
$ ssh ubuntu@<ip>
$ sudo tail -f /var/log/cloud-init-output.log

# Ou verifique arquivo de status
$ sudo cat /var/lib/cloud/instance/boot-finished

---

Dicas e Boas Práticas

Dica 1: Use Módulos para Reutilização

# Crie um módulo para VMs
# modules/vm/main.tf
resource "libvirt_domain" "vm" {
  name   = var.vm_name
  memory = var.vm_memory
  # ... resto da configuração
}

# Use o módulo
module "vm1" {
  source = "./modules/vm"
  vm_name = "vm-1"
}

Dica 2: Versionamento do Estado

# Adicione terraform.tfstate ao .gitignore
$ echo "terraform.tfstate*" >> ~/.gitignore

# Mas versione arquivos de configuração
$ git add *.tf *.tfvars
$ git commit -m "feat: add terraform configuration"

Dica 3: Use Workspaces para Ambientes

# Crie workspace para desenvolvimento
$ terraform workspace new dev

# Crie workspace para produção
$ terraform workspace new prod

# Liste workspaces
$ terraform workspace list

# Mude de workspace
$ terraform workspace select dev

Dica 4: Valide Antes de Aplicar

# Sempre valide antes de aplicar
$ terraform validate
$ terraform fmt
$ terraform plan

# Revise o plano antes de aplicar
$ terraform apply

Dica 5: Use Remote State para Equipes

# Configure backend remoto
terraform {
  backend "local" {
    path = "terraform.tfstate"
  }
}

# Ou use S3, Consul, etc para equipes

---

Integrando com workspace-as-code

Passo 1: Organizar Estrutura

# Verifique a estrutura
$ tree ~/workspace-as-code/terraform/

# Você deve ver:
# ~/workspace-as-code/terraform/
# └── libvirt/
#     └── debian12/
#         ├── main.tf
#         ├── variables.tf
#         ├── terraform.tfvars
#         ├── cloud-init.yml
#         └── terraform.tfstate

Passo 2: Criar .gitignore

# Crie arquivo .gitignore
$ cat > ~/workspace-as-code/terraform/.gitignore << 'EOF'
# Terraform files
*.tfstate
*.tfstate.*
.terraform/
.terraform.lock.hcl
crash.log
crash.*.log
override.tf
override.tf.json
*_override.tf
*_override.tf.json
.DS_Store
EOF

# Verifique
$ cat ~/workspace-as-code/terraform/.gitignore

Passo 3: Versionar no Git

# Adicione ao Git
$ cd ~/workspace-as-code
$ git add terraform/
$ git commit -m "feat: add terraform configuration for libvirt"
$ git push origin main

# Verifique
$ git log --oneline | head -5

---

Script de Validação

Para verificar se tudo foi configurado corretamente:

#!/bin/bash
# Script de validação de Terraform

echo "Validando Terraform..."

# Verificar Terraform
if command -v terraform &> /dev/null; then
    echo "✓ Terraform instalado"
else
    echo "✗ Terraform não instalado"
    exit 1
fi

# Verificar versão
if terraform version | grep -q "v1"; then
    echo "✓ Terraform versão OK"
else
    echo "✗ Versão do Terraform incorreta"
    exit 1
fi

# Verificar arquivos
if [ -f "main.tf" ]; then
    echo "✓ Arquivo main.tf existe"
else
    echo "✗ Arquivo main.tf não existe"
    exit 1
fi

# Validar configuração
if terraform validate &> /dev/null; then
    echo "✓ Configuração Terraform válida"
else
    echo "✗ Configuração Terraform inválida"
    exit 1
fi

# Verificar provider
if [ -d ".terraform" ]; then
    echo "✓ Provider instalado"
else
    echo "✗ Provider não instalado"
    exit 1
fi

echo ""
echo "Validação concluída com sucesso!"

---

Conclusão

Você aprendeu a usar Terraform para definir e gerenciar máquinas virtuais de forma declarativa. Com Terraform e o provider LIBVIRT, você pode criar infraestrutura reproduzível, versionável e escalável.

O Que Você Alcançou

✓ Entendimento de Terraform, HCL e Provider LIBVIRT ✓ Instalação do Terraform ✓ Configuração do provider LIBVIRT v0.9.2 ✓ Criação de estrutura modular de código ✓ Definição de VMs, volumes e redes ✓ Aprendizado de comandos essenciais ✓ Configuração com Cloud-Init ✓ Integração com workspace-as-code

Próximos Passos Imediatos

1. Verifique pré-requisitos:

   $ systemctl is-active libvirtd
   $ virsh pool-list
   

2. Instale Terraform:

   $ sudo apt install -y terraform
   $ terraform --version
   

3. Crie estrutura:

   $ mkdir -p ~/workspace-as-code/terraform/libvirt/debian12
   $ cd ~/workspace-as-code/terraform/libvirt/debian12
   

4. Configure Terraform:

   $ terraform init
   $ terraform validate
   $ terraform plan
   

5. Crie VM:

   $ terraform apply
   

6. Versione no Git:

   $ cd ~/workspace-as-code
   $ git add terraform/
   $ git commit -m "feat: add terraform configuration"
   $ git push origin main
   

Próximo Tutorial

Com Terraform configurado, o próximo passo é aprender a criar imagens customizadas usando Packer, que será usado com Terraform para criar VMs pré-configuradas.

• Próximo: Estação de Trabalho como Código (Parte 8): Criando Imagens com Packer

---

Recursos Adicionais

• Terraform Documentation
• Terraform LIBVIRT Provider
• HCL Syntax
• Cloud-Init Documentation
• Terraform Best Practices

---

Fim da Parte 7

Próxima: Criando Imagens com Packer