Skip to content

locaweb/tf-cloud-starter-kit

Repository files navigation

Terraform - Provisionamento Locaweb Cloud

Este projeto contém configurações Terraform para provisionar 5 cenários diferentes na plataforma Locaweb Cloud.

🚀 Quick Start

# 1. Instalar dependências
sudo apt-get install -y docker.io docker-compose make jq sshpass

# 2. Configurar credenciais
cp terraform.tfvars.example terraform.tfvars
# Edite terraform.tfvars com suas credenciais da Locaweb Cloud

# 3. Inicializar projeto
make install

# 4. Criar seu primeiro cenário (exemplo: VPS com Easypanel)
make cenario1-up

# 5. Ver credenciais
make cenario1-credentials

Pronto! Sua infraestrutura está no ar. Para outros cenários, veja a seção "Executar Cenários Específicos".

💡 Perfil das Instâncias: Todos os cenários utilizam instâncias medium (2 vCPUs x 2.00 GHz, 4 GB RAM, 80 GB disco).


Cenários Implementados

Cenário 1 (VPS Servidor Único - Easypanel em VM)

  • Infraestrutura: Uma instância Ubuntu Server 24.04 (medium)
  • Rede: Guest network "rede padrão" com IP público
  • Senha: Gerada aleatoriamente (20 caracteres alfanuméricos)
  • Aplicação: Easypanel (painel de gerenciamento web)
    • Acesso: http://<IP_PUBLICO>/admin
    • Nginx como proxy reverso + Firewall UFW
  • Portas expostas: 22 (SSH), 80 (HTTP), 443 (HTTPS)
  • Autenticação SSH: Chave SSH local gerada automaticamente
    • Criada em tools/cenario1_key durante make cenario1-up
    • Removida automaticamente durante make cenario1-down
    • Nova chave gerada a cada provisionamento (rotação automática)
  • Zona: ZP01

Cenário 2 (Alta Disponibilidade com Load Balancer)

  • Infraestrutura: Duas instâncias Ubuntu Server 24.04 (medium) + Load Balancer
  • Rede: Guest network "rede-lb-cenario2" (instâncias sem IPs públicos)
  • Senhas: Geradas aleatoriamente para cada instância
    • Instância A: usuário usuario1
    • Instância B: usuário usuario2
  • Load Balancer:
    • IP público único para distribuição de tráfego
    • Algoritmo: round-robin
    • Listeners: porta 80 (HTTP) e 443 (HTTPS)
    • Health check: HTTP GET em /health (esperando código 200)
    • Members: Instância A e Instância B
  • Acesso SSH: Via Load Balancer com port forwarding
    • Porta 2222 → Instância A
    • Porta 2223 → Instância B
  • Storage: Volume de 40GB compartilhado via NFS
    • Instância A: Servidor NFS (volume montado em /mnt/shared)
    • Instância B: Cliente NFS (acessa /mnt/shared remotamente)
  • Aplicações: Nginx instalado em ambas instâncias
  • Zona: ZP01

Cenário 3 (Multiambiente Econômico - QA/TST/PRD com 1 IP por ambiente + NFS)

  • Infraestrutura: 6 instâncias Ubuntu Server 24.04 (medium) - 2 por ambiente
  • Redes: Três guest networks isoladas (QA, TST, PRD)
  • Senhas: 6 senhas únicas geradas aleatoriamente (uma por instância)
  • Storage: Volume NFS de 40GB por ambiente compartilhado entre instâncias
    • Instância 1: Servidor NFS
    • Instância 2: Cliente NFS
  • IPs: 1 IP público por ambiente (port forwarding para ambas instâncias)
    • QA: portas 222/223 | TST: portas 122/123 | PRD: portas 22/23
  • Aplicações: Docker instalado em todas as instâncias
  • Zona: ZP01

Cenário 4 (Rede Segregada - APP ↔ BD isolados)

  • Infraestrutura: 2 instâncias Ubuntu Server 24.04 (medium)
  • Redes: Duas guest networks isoladas (BD e APP)
  • Senhas: Geradas aleatoriamente para cada instância
    • Instância BD: usuário usuariobd
    • Instância APP: usuário usuarioapp
  • Storage: Volume de ~160GB exclusivo para BD
    • Montado em /var/persistent-data (formatação automática)
  • Segregação: Volume BD inacessível pela instância APP
  • Aplicações: Docker instalado em ambas
  • IPs: 1 IP público por instância
  • Zona: ZP01

Cenário 5 (Cluster Kubernetes - K3s + Rancher)

  • Infraestrutura: 3 instâncias Ubuntu Server 24.04 (medium)
    • 1 Control Plane (Master) + 2 Workers (Agents)
  • Rede: Guest network "k8s-cluster" (10.5.1.0/24)
  • Senhas: Geradas aleatoriamente para cada node (usuário k3suser)
  • Cluster: K3s (Kubernetes leve e simplificado)
    • Instalação totalmente automática
    • Workers se conectam automaticamente ao Control Plane
  • Aplicações:
    • Rancher (UI web de gerenciamento) - credenciais padrão: admin/admin
    • Acesso: https://<control-plane-ip>/
  • IPs: 1 IP público por instância
  • Tempo: ~10-15 minutos para cluster pronto
  • Zona: ZP01

Pré-requisitos

  • Sistema Operacional: Linux
  • Docker: >= 20.10 (ou Docker Compose >= 2.0)
  • Make: Instalado no sistema
  • sshpass: Instalado no sistema (necessário para scripts de configuração SSH automatizada)
  • jq: Instalado no sistema (necessário para parsing de JSON nos comandos make)
  • TFLint: Instalado no sistema (opcional, mas recomendado para verificações de qualidade)
  • Credenciais Locaweb Cloud: API Key e Secret Key
  • Acesso à zona ZP01 na plataforma Locaweb Cloud

Instalação das Ferramentas Necessárias

sshpass (Obrigatório)

O sshpass é necessário para automação SSH com senha nos scripts de configuração.

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y sshpass

CentOS/RHEL/Fedora:

sudo yum install -y sshpass
# ou
sudo dnf install -y sshpass

Arch Linux:

sudo pacman -S sshpass

jq (Obrigatório)

O jq é necessário para processar saídas JSON do Terraform.

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y jq

CentOS/RHEL/Fedora:

sudo yum install -y jq
# ou
sudo dnf install -y jq

Arch Linux:

sudo pacman -S jq

TFLint (Opcional)

Para instalar o TFLint no Linux, execute:

bash <(curl -s https://raw.githubusercontent.com/terraform-linters/tflint/master/install_linux.sh)

Ou siga as instruções oficiais para outras plataformas.

Configuração

Configurar Credenciais do Locaweb Cloud

Para utilizar este projeto, você precisa das credenciais de API do Locaweb Cloud. Siga o passo a passo abaixo:

Passo 1: Acessar o Painel Locaweb Cloud

Acesse o painel em: https://painel-cloud.locaweb.com.br

Faça login com suas credenciais.

Passo 2: Acessar Configurações de Perfil

No canto superior direito, clique no seu avatar/nome de usuário e selecione "Perfil".

Passo 2 - Acessar Perfil

Passo 3: Gerar Novas Chaves API

Na página de perfil, role até a seção de API e clique em "Gerar novas chaves API/Secretas".

Passo 3 - Visualizar Perfil

Nota: Se você já possui chaves geradas anteriormente e deseja reutilizá-las, pule para o Passo 4.

Passo 4: Copiar as Chaves

Aguarde alguns segundos até que as chaves sejam geradas e apareçam na tela. Você verá:

  • Chave da API (API Key)
  • Chave secreta (Secret Key)

Passo 4 - Chaves Geradas

Passo 5: Configurar o arquivo terraform.tfvars

No diretório do projeto, copie o arquivo de exemplo:

cp terraform.tfvars.example terraform.tfvars

Abra o arquivo terraform.tfvars em seu editor de texto favorito e preencha com as credenciais copiadas:

# Credenciais do Locaweb Cloud (obrigatórias)
cloudstack_api_key    = "sua-chave-api-aqui"
cloudstack_secret_key = "sua-chave-secreta-aqui"

Exemplo preenchido:

cloudstack_api_key    = "NcuBdr7ap5Y8dQ8cxfR..."
cloudstack_secret_key = "xYz9k8m3n2L4p5Q6r7S..."

Salve o arquivo.

Passo 6: Verificar Configuração

Para verificar se as credenciais estão corretas, execute:

make validate

Se tudo estiver correto, você verá a mensagem: ✓ Success! The configuration is valid.


⚠️ SEGURANÇA:

  • NUNCA commite o arquivo terraform.tfvars (já está no .gitignore)
  • Guarde suas chaves em local seguro (gerenciador de senhas)
  • Se suas chaves forem expostas, gere novas imediatamente no painel

⚠️ Trocando de Conta

Se você já usou este projeto com uma conta e deseja trocar para outra:

Opção 1: ANTES de trocar as credenciais (recomendado)

# Destruir TODOS os recursos na conta atual
make clean

Opção 2: Se Já trocou as credenciais e recebe erros como invalid character '<'

# Remove TODOS os recursos do Terraform State sem tentar destruir na nuvem
make state-clean

# Este comando:
# ✓ Remove todos os recursos de TODOS os cenários do state
# ✓ NÃO deleta os recursos na nuvem (apenas remove do controle do Terraform)
# ✓ Permite criar novos recursos na nova conta
# ⚠️  Requer confirmação (digite 'sim')

Uso

Este projeto usa Docker para executar o Terraform. Todos os comandos são executados via Makefile.

Setup Inicial

# Construir a imagem Docker e inicializar o Terraform
make install

Comandos Gerais

# Ver todos os comandos disponíveis
make help

# Ver o plano de execução (todos os cenários)
make plan

# Aplicar todos os cenários (com confirmação)
make apply

# Aplicar sem confirmação (todos os cenários)
make apply-auto

# Destruir todos os recursos
make destroy

# Limpar todos os cenários e recursos órfãos (recomendado)
make clean

# Limpar TODOS os recursos do Terraform State (útil ao trocar de conta)
# ⚠️  NÃO deleta recursos na nuvem, apenas remove do controle do Terraform
make state-clean

# Validar configuração
make validate

# Executar todas as verificações de qualidade (TFLint, fmt-check, validate)
make lint

# Ver outputs
make output

Verificações de Qualidade de Código

O comando make lint executa três verificações em sequência para garantir a qualidade do código Terraform:

  1. TFLint: Analisa o código Terraform procurando por problemas comuns, más práticas e possíveis erros. Verifica:

    • Variáveis não utilizadas
    • Recursos duplicados
    • Configurações incorretas
    • Boas práticas do Terraform
  2. Formatação (terraform fmt -check): Verifica se todos os arquivos .tf estão formatados corretamente segundo o padrão do Terraform. Não modifica os arquivos, apenas verifica.

  3. Validação (terraform validate): Valida a sintaxe e configuração do Terraform, verificando se:

    • A sintaxe está correta
    • Os recursos estão configurados corretamente
    • As referências entre recursos são válidas

Uso:

# Executar todas as verificações
make lint

Corrigir problemas encontrados:

# Se houver problemas de formatação, corrija automaticamente com:
make fmt

# Execute novamente para verificar se tudo está OK
make lint

Nota: O TFLint é instalado automaticamente quando você executa make install. Se o TFLint não estiver instalado, o comando make lint exibirá instruções para instalação manual.

Executar Cenários Específicos

# Cenário 1 (VPS Servidor Único com Senha Aleatória)
make cenario1-up      # Cria todos os recursos do Cenário 1
make cenario1-down    # Destrói todos os recursos do Cenário 1
make cenario1-credentials # Exibe as credenciais de acesso (senha aleatória) e URLs do Easypanel

# Cenário 2 (Alta Disponibilidade com Load Balancer)
make cenario2-up      # Cria todos os recursos do Cenário 2 + configura NFS automaticamente
make cenario2-down    # Destrói todos os recursos do Cenário 2
make cenario2-credentials # Exibe as credenciais de acesso (senhas aleatórias) e URL do LB

# Cenário 3 (Multiambiente Econômico com NFS)
make cenario3-up      # Cria todos os recursos do Cenário 3 + configura NFS automaticamente
make cenario3-down    # Destrói todos os recursos do Cenário 3
make cenario3-credentials # Exibe as credenciais de acesso (senhas aleatórias) dos 3 ambientes

# Cenário 4 (Rede Segregada com Senhas Aleatórias)
make cenario4-up      # Cria todos os recursos do Cenário 4 + configura discos automaticamente
make cenario4-down    # Destrói todos os recursos do Cenário 4
make cenario4-credentials # Exibe as credenciais de acesso (senhas aleatórias)

# Cenário 5 (Cluster Kubernetes com Senhas Aleatórias)
make cenario5-up      # Cria todos os recursos do Cenário 5 (aguarde ~10-15min para cluster ficar pronto)
make cenario5-down    # Destrói todos os recursos do Cenário 5
make cenario5-credentials # Exibe as credenciais de acesso (senhas aleatórias) dos 3 nodes + Rancher

Guias de Uso por Cenário

Cenário 1 - VPS com Easypanel

Acesso Web:

  • URL: https://<IP_PUBLICO>/ (Easypanel responde na raiz e em /admin)
  • Certificado auto-assinado (aceite no navegador)

SSH com chave local:

# Chave gerada automaticamente em tools/cenario1_key
ssh -i tools/cenario1_key -o StrictHostKeyChecking=no root@<IP_PUBLICO>

SSH com senha:

# Use o comando exibido em: make cenario1-credentials
sshpass -p '<SENHA>' ssh root@<IP_PUBLICO>

📝 Nota sobre Rotação de Chaves: A cada execução de make cenario1-up, uma nova chave SSH é gerada em tools/cenario1_key. Ao executar make cenario1-down, a chave local é automaticamente removida. Isso garante que cada provisionamento use credenciais únicas e evita o acúmulo de chaves antigas.

Cenário 2 - Alta Disponibilidade com Load Balancer

Acesso Web (via Load Balancer):

  • URL Principal: http://<IP_PUBLICO_LB>/
  • Health Check: http://<IP_PUBLICO_LB>/health
  • Recarregue a página várias vezes para ver o balanceamento entre Instância A e Instância B

Acesso SSH (via Load Balancer):

# Instância A (porta 2222)
ssh -p 2222 usuario1@<IP_PUBLICO_LB>

# Instância B (porta 2223)
ssh -p 2223 usuario2@<IP_PUBLICO_LB>

# Com sshpass (use as senhas de make cenario2-credentials)
sshpass -p '<SENHA_INST_A>' ssh -p 2222 usuario1@<IP_PUBLICO_LB>
sshpass -p '<SENHA_INST_B>' ssh -p 2223 usuario2@<IP_PUBLICO_LB>

Testar Load Balancer:

# Fazer múltiplas requisições para ver o balanceamento
for i in {1..10}; do curl -s http://<IP_PUBLICO_LB>/ | grep -o "Instancia [AB]"; done

# Verificar health check
curl http://<IP_PUBLICO_LB>/health
# Resultado esperado: OK

Testar NFS Compartilhado:

# Criar arquivo na Instância A (via SSH com sshpass)
sshpass -p '<SENHA_INST_A>' ssh -o StrictHostKeyChecking=no -p 2222 usuario1@<IP_PUBLICO_LB> \
  "echo 'Teste NFS - criado na Instancia A' > /mnt/shared/teste.txt"

# Ler arquivo da Instância B
sshpass -p '<SENHA_INST_B>' ssh -o StrictHostKeyChecking=no -p 2223 usuario2@<IP_PUBLICO_LB> \
  "cat /mnt/shared/teste.txt"

# Verificar espaço do volume compartilhado
sshpass -p '<SENHA_INST_A>' ssh -o StrictHostKeyChecking=no -p 2222 usuario1@<IP_PUBLICO_LB> \
  "df -h /mnt/shared"

Obter Comandos Prontos:

# Exibe informações completas incluindo IPs, senhas e comandos SSH prontos
make cenario2-credentials

Estrutura dos Arquivos

├── cenario1.tf              # Recursos e outputs do Cenário 1 (VPS Servidor Único - Easypanel em VM)
├── cenario2.tf              # Recursos e outputs do Cenário 2 (Alta Disponibilidade Básica com NFS)
├── cenario3.tf              # Recursos e outputs do Cenário 3 (Multiambiente Econômico)
├── cenario4.tf              # Recursos e outputs do Cenário 4 (Rede Segregada)
├── cenario5.tf              # Recursos e outputs do Cenário 5 (Cluster Kubernetes - K3s + Rancher)
├── scripts/
│   ├── setup-nfs-cenario2.sh # Script pós-provisionamento para configurar NFS no Cenário 2
│   └── setup-nfs-cenario3.sh # Script pós-provisionamento para configurar NFS no Cenário 3 (3 ambientes)
├── provider.tf              # Configuração do provider Locaweb Cloud
├── variables.tf             # Definição de variáveis (API keys)
├── locals.tf                # Valores locais (zone, service offering, template, disk offering)
├── terraform.tfvars        # Arquivo de configuração com credenciais (não versionado)
├── terraform.tfvars.example # Exemplo de configuração
├── Makefile                 # Comandos simplificados para gerenciar os cenários
├── docker-compose.yml       # Configuração Docker Compose
├── Dockerfile               # Imagem Docker com Terraform 1.14
├── README.md                # Este arquivo
└── .gitignore               # Arquivos ignorados pelo Git (tfstate, tfvars, etc.)

Descrição dos Arquivos

  • cenario*.tf: Arquivos de configuração Terraform para cada cenário. Cada arquivo contém:

    • Recursos Locaweb Cloud (networks, instances, volumes, IPs, port forwards)
    • Outputs específicos do cenário
  • provider.tf: Configuração do provider Locaweb Cloud, incluindo:

    • Versão do provider (cloudstack/cloudstack ~> 0.4)
    • URL da API Locaweb Cloud
    • Referências às variáveis de credenciais
  • variables.tf: Define as variáveis utilizadas no projeto:

    • cloudstack_api_key: Chave de API da Locaweb Cloud
    • cloudstack_secret_key: Chave secreta da Locaweb Cloud
  • locals.tf: Define valores locais reutilizáveis:

    • IDs de zone, service offering, template e disk offering
    • Valores fixos que não mudam entre execuções
  • terraform.tfvars: Arquivo de configuração local (não versionado) contendo:

    • Credenciais da API Locaweb Cloud
  • Makefile: Facilita a execução de comandos Terraform via Docker:

    • Comandos gerais (plan, apply, destroy, validate, etc.)
    • Comandos específicos por cenário (cenario1-up, cenario2-down, etc.)
    • Comandos de formatação e validação
  • docker-compose.yml: Define o serviço Docker para executar Terraform:

    • Usa a imagem construída pelo Dockerfile
    • Monta o diretório atual como volume
    • Configura variáveis de ambiente
  • Dockerfile: Define a imagem Docker com:

    • Terraform 1.14
    • Provider Locaweb Cloud pré-instalado
    • Ferramentas necessárias para execução

Recursos Locaweb Cloud Utilizados

Todos os cenários utilizam os seguintes recursos da Locaweb Cloud:

  • Zona: ZP01
  • Sistema Operacional: Ubuntu Server 24.04 LTS
  • Perfil das Instâncias: medium (padrão para todos os cenários)
    • CPU: 2 vCPUs x 2.00 GHz
    • Memória RAM: 4 GB
    • Disco Raiz: 80 GB
  • Volumes Adicionais:
    • 40 GB para compartilhamento NFS (Cenários 2 e 3)
    • ~160 GB para banco de dados (Cenário 4)

Detalhes técnicos: Os IDs específicos de zone, template e disk offerings estão definidos em locals.tf.

Notas Importantes

🔐 Segurança e Credenciais

  1. Senhas Aleatórias: Os cenários 1-5 geram senhas únicas automaticamente (20 caracteres alfanuméricos). Use make cenarioX-credentials para visualizá-las. Guarde em local seguro - não são recuperáveis após o provisionamento.

  2. Proteção de Credenciais: O arquivo terraform.tfvars contém suas credenciais e está protegido pelo .gitignore. Nunca faça commit deste arquivo.

📦 Storage e Compartilhamento

  1. NFS (Cenários 2 e 3): O compartilhamento NFS é configurado automaticamente via script pós-provisionamento. A Instância 1 atua como servidor NFS e a Instância 2 como cliente, compartilhando o diretório /mnt/shared.

  2. Volumes Persistentes (Cenário 4): O volume de banco de dados é montado automaticamente em /var/persistent-data com formatação ext4 e configuração no /etc/fstab para montagem automática.

🌐 Rede e Acesso

  1. Port Forwarding SSH: Cada cenário usa portas SSH diferentes para evitar conflitos quando múltiplos cenários estão ativos simultaneamente. Consulte a seção "Executar Cenários Específicos" para detalhes de cada porta.

  2. Informações de Conexão: Após make cenarioX-up, todas as informações necessárias (IPs, credenciais, comandos SSH) são exibidas automaticamente no terminal. Use make cenarioX-credentials para visualizar novamente.

Credenciais de Exemplo

As credenciais abaixo são criadas automaticamente via user_data em cada instância.

Cenário Instância/Ambiente Usuário Senha Observações
Cenário 1 Instância única root [GERADA ALEATORIAMENTE] VPS - Exibida após provisionar
Cenário 2 Instância A usuario1 [GERADA ALEATORIAMENTE] Servidor NFS - Exibida após provisionar
Cenário 2 Instância B usuario2 [GERADA ALEATORIAMENTE] Cliente NFS - Exibida após provisionar
Cenário 3 QA - Instância 1 usuarioqa1 [GERADA ALEATORIAMENTE] NFS Server - Exibida após provisionar
Cenário 3 QA - Instância 2 usuarioqa2 [GERADA ALEATORIAMENTE] NFS Client - Exibida após provisionar
Cenário 3 TST - Instância 1 usuariotst1 [GERADA ALEATORIAMENTE] NFS Server - Exibida após provisionar
Cenário 3 TST - Instância 2 usuariotst2 [GERADA ALEATORIAMENTE] NFS Client - Exibida após provisionar
Cenário 3 PRD - Instância 1 usuarioprd1 [GERADA ALEATORIAMENTE] NFS Server - Exibida após provisionar
Cenário 3 PRD - Instância 2 usuarioprd2 [GERADA ALEATORIAMENTE] NFS Client - Exibida após provisionar
Cenário 4 BD usuariobd [GERADA ALEATORIAMENTE] Banco de Dados - Exibida após provisionar
Cenário 4 APP usuarioapp [GERADA ALEATORIAMENTE] Aplicação - Exibida após provisionar
Cenário 5 K3s Server (Control Plane) k3suser [GERADA ALEATORIAMENTE] Master do cluster K3s - Exibida após provisionar
Cenário 5 K3s Worker 1 k3suser [GERADA ALEATORIAMENTE] Agent do cluster K3s - Exibida após provisionar
Cenário 5 K3s Worker 2 k3suser [GERADA ALEATORIAMENTE] Agent do cluster K3s - Exibida após provisionar
Cenário 5 Rancher (UI Web) admin admin Interface web do Rancher - https://<control-plane-ip>

Nota: Para visualizar as credenciais e informações de conexão, use os comandos do Makefile:

  • make cenario1-up, make cenario2-up, etc. - Mostram automaticamente IPs e comandos SSH após criar os recursos
  • make output - Mostra todos os outputs do Terraform, incluindo credenciais e informações detalhadas

Cada comando make cenario*-up exibe automaticamente:

  • IPs públicos das instâncias
  • Credenciais (usuário e senha)
  • Comandos SSH prontos para copiar e colar (com e sem sshpass)

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors