A automação de infraestrutura é um pilar fundamental para profissionais de TI que gerenciam ambientes de virtualização em escala. Embora a interface web do Proxmox VE (PVE) seja intuitiva e robusta para tarefas manuais, ela se torna um gargalo quando precisamos executar operações repetitivas, criar scripts de provisionamento ou integrar o hipervisor com ferramentas de orquestração como Ansible, Terraform ou Jenkins. É aqui que a linha de comando entra em jogo, oferecendo velocidade, precisão e a capacidade de scriptar ações complexas.
O pvesh é uma ferramenta de linha de comando incluída nativamente no Proxmox VE. Ela permite acessar a API REST do Proxmox sem a necessidade de instalar bibliotecas externas ou gerenciar tokens manualmente. Combinada com o jq, um processador JSON leve e flexível, você ganha o poder de transformar dados brutos da API em informações estruturadas e acionáveis instantaneamente. Neste tutorial, vamos explorar como configurar seu ambiente e utilizar essas ferramentas para gerenciar sua VPS Proxmox via CLI.
Entendendo a Ferramenta pvesh
O pvesh funciona como uma interface de linha de comando para a API REST do Proxmox. Diferente das ferramentas tradicionais de gerenciamento que muitas vezes dependem de chamadas complexas ao shell do host, o pvesh comunica-se diretamente com os endpoints da API. Isso significa que qualquer ação que você pode realizar na interface gráfica, pode ser replicada via linha de comando, garantindo consistência e permitindo a automação.
A grande vantagem do pvesh é sua simplicidade de autenticação. Ele utiliza as credenciais do usuário configuradas no sistema local ou pode ser direcionado para usar certificados SSH, facilitando a execução remota segura. Além disso, o formato de saída padrão é JSON, o que torna a ferramenta perfeitamente compatível com jq e outras ferramentas de processamento de dados.
Instalação do jq no Ambiente Local
Para extrair valor completo dos dados retornados pelo pvesh, precisamos de uma ferramenta para analisar JSON. O jq é o padrão da indústria para essa tarefa em ambientes Linux. Antes de prosseguir com os comandos, certifique-se de que o jq está instalado na máquina onde você irá executar os scripts (seja no nó Proxmox ou em sua estação de trabalho administrativa).
Em distribuições baseadas em Debian/Ubuntu, utilize o gerenciador de pacotes apt:
sudo apt update
sudo apt install jq -yPara sistemas RHEL/CentOS/Rocky Linux:
sudo dnf install jq -yVerifique a instalação executando jq --version. Se a versão for exibida, seu ambiente está pronto para processar as saídas JSON do Proxmox.
Configurando Autenticação e Permissões
Antes de emitir qualquer comando, é crucial entender como o pvesh se autentica. Por padrão, ele tenta usar as credenciais armazenadas no arquivo /etc/pve/priv/accesscontrol ou solicita interação via terminal. Para automação, a melhor prática é utilizar um token de API específico ou configurar o uso de chaves SSH.
Importante: Nunca utilize a conta root para scripts de automação se puder evitar. Crie um usuário dedicado com permissões mínimas necessárias (Privilégio Mínimo). No Proxmox VE, vá em Datacenter > Permissions > Users e crie um novo usuário, por exemplo, automation@pam. Atribua a este usuário apenas as permissões de leitura ou escrita específicas para os recursos que ele precisa gerenciar.
Se você estiver executando os comandos diretamente no nó Proxmox, o pvesh já terá acesso local. Se for executar remotamente, use a flag --server e forneça as credenciais via variáveis de ambiente ou entrada padrão para evitar expor senhas no histórico de comandos.
Listando Máquinas Virtuais e Containers
A primeira tarefa comum é obter um inventário dos recursos disponíveis. O pvesh organiza os comandos em hierarquias que espelham a estrutura da API. Para listar todas as VMs (máquinas virtuais QEMU), utilizamos o caminho /nodes/{node}/qemu.
O comando básico seria:
pvesh get /nodes/proxmox1/qemuNo entanto, a saída padrão pode ser verbosa. Para obter uma lista limpa apenas dos IDs das VMs e seus estados, combinamos o pvesh com o jq. Isso é essencial para criar loops em scripts bash.
pvesh get /nodes/proxmox1/qemu | jq -r '.[] | "\(.id) \(.status)"'Neste comando, o jq -r remove as aspas da saída final. A expressão .[] itera sobre cada item do array JSON retornado. Em seguida, interpolamos as propriedades id e status para exibir apenas o identificador da máquina (ex: 100) e seu estado atual (ex: running, stopped). Isso permite que você crie relatórios rápidos de saúde do ambiente.
Para listar containers LXC, a lógica é idêntica, alterando apenas o caminho:
pvesh get /nodes/proxmox1/lxc | jq -r '.[] | "\(.id) \(.status)"'Gestão de Recursos e Storage
Além de máquinas virtuais, a gestão de armazenamento é crítica. O Proxmox utiliza conceitos como datastores (lvm-thin, nfs, dir, etc.). Para verificar o uso de espaço em disco dos storage disponíveis no nó, podemos consultar o endpoint de storage.
pvesh get /nodes/proxmox1/storage | jq -r '.[] | "\(.storage): \(.content)"'Este comando retorna uma lista simples de cada nome de storage e os tipos de conteúdo permitidos (vm, images, iso, backup). Para obter informações mais detalhadas sobre capacidade, uso e tipo específico, podemos filtrar ainda mais:
pvesh get /nodes/proxmox1/storage | jq -r '.[] | select(.enabled == true) | "\(.storage): Total=\(.maxdisk) Used=\(.used)"'O uso de select no jq é poderoso para filtrar apenas recursos ativos, ignorando storages desabilitados ou offline. Essa abordagem permite monitorar a saúde do armazenamento diretamente via CLI e integrar com sistemas de alerta como Prometheus ou Zabbix.
Criando e Configurando VMs via Script
A verdadeira potência da automação surge quando criamos recursos programaticamente. Embora a criação completa de uma VM com todas as opções via linha de comando seja extensa, o pvesh permite a execução de métodos POST na API.
Para criar uma VM básica, você deve montar um payload JSON e enviá-lo ao endpoint correto. No entanto, o pvesh facilita isso aceitando parâmetros via linha de comando ou stdin. Um exemplo simplificado de criação de uma VM QEMU seria:
pvesh create /nodes/proxmox1/qemu \
--name my-new-vm \
--memory 2048 \
--cores 2 \
--net0 virtio=92:7E:3A:1B:2C:3D,bridge=vmbr0 \
--scsi0 local-lvm:0Atenção: Este comando é um exemplo básico. Em produção, você deve especificar discos com tamanhos explícitos e garantir que o disco de boot exista. A validação dos parâmetros antes da execução é vital para evitar a criação de VMs incompletas.
Para tarefas mais complexas, como clonagem de templates ou criação de snapshots, o fluxo envolve gerar um JSON estruturado e passá-lo ao comando create. O jq pode ser usado para construir esse payload dinamicamente baseado em variáveis do ambiente:
SNAPSHOT_NAME="backup-$(date +%F)"
PAYLOAD=$(jq -n --arg snap "$SNAPSHOT_NAME" '{vmid: 100, description: $snap}')
echo $PAYLOAD | pvesh create /nodes/proxmox1/qemu/100/snapshot
Neste exemplo, geramos dinamicamente o nome do snapshot baseado na data atual e criamos uma nova cópia de segurança instantânea da VM com ID 100. Isso é extremamente útil para rotinas de backup noturno automatizado.
Monitoramento de Status e Logs
A automação também serve para monitoramento. Você pode criar scripts que verificam periodicamente o status das VMs e enviam alertas se alguma máquina crítica parar inesperadamente.
pvesh get /nodes/proxmox1/qemu | jq -r '.[] | select(.status != "running") | "\(.id) is \(.status)"'Se este comando retornar linhas, significa que há VMs não em execução. Você pode integrar essa lógica a um script cron:
#!/bin/bash
DOWN_VMS=$(pvesh get /nodes/proxmox1/qemu | jq -r '.[] | select(.status != "running") | .id')
if [ -n "$DOWN_VMS" ]; then
echo "Alerta: As seguintes VMs estão paradas: $DOWN_VMS"
# Adicione aqui a lógica de envio de e-mail ou notificação Slack
fiEsse script pode ser executado a cada 5 minutos. A combinação de pvesh para coleta de dados e jq para filtragem torna o script leve, rápido e sem dependências pesadas.
Boas Práticas e Segurança
Ao adotar a automação via CLI no Proxmox, considere as seguintes práticas para manter a estabilidade e segurança do seu ambiente:
- Teste em Ambiente Homologado: Nunca execute scripts de criação ou modificação diretamente em produção sem testar antes. Use um nó de laboratório idêntico.
- Versionamento de Scripts: Mantenha seus scripts de automação em repositórios Git. Isso permite rastrear mudanças, reverter erros e colaborar com a equipe.
- Logs Detalhados: Ao escrever scripts bash que utilizam
pvesh, redirecione saídas de erro para logs separados. A API do Proxmox retorna códigos de erro específicos que ajudam na depuração. - Limites de Rate: A API do Proxmox possui limites de requisições. Evite loops infinitos ou consultas excessivamente frequentes (ex: a cada segundo) para não bloquear seu usuário na API.
Integração com Ansible
Embora o pvesh seja excelente para scripts bash simples, para orquestração complexa de múltiplos nós, a integração com Ansible é recomendada. O Proxmox oferece módulos oficiais no Ansible Galaxy que utilizam internamente chamadas similares à API REST. No entanto, entender o pvesh ajuda diretamente na escrita de playbooks Ansible personalizados ou na resolução de problemas quando os módulos padrão não cobrem um caso de uso específico.
Você pode usar o módulo command ou shell no Ansible para chamar o pvesh se precisar de uma funcionalidade muito específica que ainda não tenha um módulo dedicado, aproveitando a mesma sintaxe JSON e filtros do jq.
Conclusão
O gerenciamento de VPS Proxmox via CLI com pvesh e jq representa o nível seguinte na maturidade operacional de qualquer administrador de sistemas. Ao abandonar a dependência exclusiva da interface web, você ganha controle granular, velocidade de execução e a capacidade de integrar seu ambiente de virtualização a pipelines CI/CD modernos.
A curva de aprendizado inicial para entender a estrutura JSON da API pode ser íngrime, mas uma vez dominada, a produtividade aumenta significativamente. Comece simples: liste suas VMs, monitore o status do storage e automatize backups básicos. À medida que ganha confiança, expanda para criação dinâmica de recursos e integração com ferramentas de monitoramento.
Lembre-se sempre de validar seus comandos em ambiente seguro e manter suas credenciais protegidas. A automação é uma ferramenta poderosa que, quando usada corretamente, transforma a gestão de infraestrutura de uma tarefa manual propensa a erros em um processo confiável e escalável.