O pressuposto que o Ansible normalmente pode fazer

Quase todos os módulos Ansible que já usaste funcionam assim: o Ansible liga-se ao anfitrião indicado no inventário, copia para lá um pequeno programa Python, executa-o e lê o resultado. O anfitrião é a coisa que está a ser alterada e a coisa que faz o trabalho.

Criar uma máquina virtual quebra isso da forma mais básica possível. O anfitrião que estás a construir não existe. Não tem IP, nem daemon SSH, nem Python, nem sistema operativo. Não há nada a que te ligares.

Por isso o community.proxmox não é um agente de configuração. É um cliente de API que por acaso é distribuído como coleção Ansible. Como tal, tudo neste artigo decorre desse único facto: onde correm as tarefas, como fazes chegar as credenciais, porque é que voltar a executar não faz o que esperas, e porque é que o --check não te está a dizer a verdade.

Os exemplos aqui são versões reduzidas de um playbook que constrói VMs Windows e Linux a partir de registos do NetBox: proxmox-create-vms.yml. Tornei genéricos os nomes de nós, de armazenamento e de bridges para facilitar a leitura; o original está nesse repositório.

Tudo o que afirmo abaixo sobre o comportamento dos módulos foi verificado contra o community.proxmox 1.6.0, que é a versão que tenho instalada:

$ ansible-galaxy collection list community.proxmox
# /home/damien/.ansible/collections/ansible_collections
Collection        Version
----------------- -------
community.proxmox 1.6.0

Primeiro: a coleção mudou de sítio

Se estás a ler um playbook mais antigo ou uma resposta mais antiga, os módulos chamavam-se community.general.proxmox_kvm. Agora vivem numa coleção dedicada, e é aí que o desenvolvimento está a acontecer. A versão 1.6.0 traz 47 módulos, que cobrem Ceph, SDN, firewall, regras de HA e adesão a cluster, nada do qual existia na era do community.general.

ansible-galaxy collection install community.proxmox
pip install 'proxmoxer>=2.0' requests

A dependência Python não é opcional nem vem incluída: a coleção declara requirements: ["proxmoxer >= 2.0", "requests"], e isso tem de estar instalado onde quer que o módulo seja de facto executado, que, como explica a secção seguinte, não é o nó Proxmox.

O requirements.yml, se preferires fixar a versão:

---
collections:
  - name: community.proxmox
    version: ">=1.6.0"

A coleção é testada contra o ansible-core 2.17 a 2.20. Renomear as tuas tarefas community.general.proxmox_* para community.proxmox.proxmox_* é a maior parte da migração.

Todas as tarefas do Proxmox correm em localhost

Duas linhas no topo do play fazem o trabalho pesado, e ambas parecem estar a desligar algo útil:

- name: Create Proxmox virtual machines
  hosts: "{{ target_hosts | default('cluster_pve:&status_planned') }}"
  gather_facts: false
  serial: 1

O gather_facts: false não é uma otimização. A recolha de factos liga-se ao anfitrião do inventário, e o anfitrião do inventário é uma VM que ainda não foi construída. Deixa-a ligada e o play falha antes da primeira tarefa.

Depois, cada tarefa do Proxmox leva delegate_to: localhost:

- name: Create Proxmox VM
  delegate_to: localhost
  register: created_vm
  community.proxmox.proxmox_kvm:
    api_user: "{{ proxmox_user }}"
    api_password: "{{ proxmox_password }}"
    api_host: "{{ proxmox_api_ip }}"
    name: "{{ inventory_hostname }}"
    node: "{{ proxmox_api_host }}"
    ...

O anfitrião do inventário passa a ser apenas um nome e um saco de variáveis. O inventory_hostname torna-se o nome da VM; as suas variáveis descrevem a máquina que queres. Nada se liga a ele. A tarefa corre no nó de controlo, que abre uma sessão HTTPS para o api_host e envia uma definição de VM.

Também vais ver isto escrito como local_action:, que é a sintaxe mais antiga para a mesma coisa. O playbook de remoção nesse repositório usa-a em todo o lado. São equivalentes. O delegate_to é a forma atual.

A saída de emergência aponta para o nó

Algumas coisas têm mesmo de acontecer num anfitrião Proxmox, e essas tarefas delegam para um sítio completamente diferente:

- name: Fail if no ISO file exists for the OS
  delegate_to: "{{ proxmox_api_host }}"
  ansible.builtin.stat:
    path: "{{ iso | replace('isos:', '/mnt/pve/isos/template/') }}"
  register: iso_file
  failed_when: not iso_file.stat.exists

Isto é uma ligação SSH real a um nó real, a verificar um caminho real em armazenamento partilhado, porque a API aceita alegremente uma referência a um ISO que não corresponde a nenhum ficheiro, e mais vale descobrires agora do que no arranque. Repara na cirurgia de strings que traduz uma referência de armazenamento PVE (isos:iso/debian.iso) num caminho do sistema de ficheiros. A abstração de armazenamento não está disponível para o stat.

Portanto, um único play tem tarefas a executar em três sítios diferentes, e confundi-los é a forma mais comum de estes playbooks falharem:

Onde corre de facto cada tarefa de um playbook de construção ProxmoxNó de controlo Ansibledelegate_to: localhostproxmox_kvmproxmox_vm_infoproxmox_diskproxmox_access_aclcada um deles é umcliente HTTPS, não um agenteproxmoxer ≥ 2.0 + requestsinstalado aqui, não no nógather_facts: falseNó Proxmox — pve1pvedaemon, API RESTna porta 8006qm, /etc/pve, armazenamentoa definição da VM chega aquia VM que estás a criarsem IP · sem SSH · sem Pythonsem sistema operativono inventário é sóum nome e um saco de variáveisAPISSHqm setstatnada a que te ligaressó num play posterior
Três contextos de execução num só play. Os módulos do Proxmox nunca tocam no nó nem no convidado: são clientes HTTPS a correr ao lado do playbook. A saída de emergência qm é a única parte que precisa de SSH para um hipervisor.

Credenciais, e uma predefinição prestes a mudar

As opções de autenticação são partilhadas por todos os módulos da coleção através de um fragmento de documentação, por isso são as mesmas em todo o lado: api_host, api_user, e depois ou api_password ou o par api_token_id / api_token_secret. Todas recorrem a variáveis de ambiente quando não são dadas, PROXMOX_HOST, PROXMOX_USER, PROXMOX_PASSWORD, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET, PROXMOX_VALIDATE_CERTS, que é a forma mais limpa de manter os segredos totalmente fora do play.

Um token de API é a melhor predefinição. Tem âmbito limitado, pode ser revogado sem mudar a palavra-passe de uma pessoa, e pode receber exatamente os privilégios de que o playbook precisa, em vez dos que uma pessoa por acaso tem:

- name: Create Proxmox VM
  delegate_to: localhost
  community.proxmox.proxmox_kvm:
    api_host: "{{ proxmox_api_ip }}"
    api_user: ansible@pve
    api_token_id: automation
    api_token_secret: "{{ proxmox_token_secret }}"
    validate_certs: true
    ca_path: /etc/ssl/certs/pve-cluster-ca.pem

Define o validate_certs explicitamente, hoje. A própria documentação da coleção di-lo claramente:

Currently defaults to false and changes default to true with community.proxmox 2.0.0.

O que significa que um playbook que nunca o menciona não está a validar TLS neste momento, e vai começar a validar, e portanto a falhar contra o certificado autoassinado com que vem cada instalação nova do Proxmox, no momento em que alguém correr --upgrade. Mais vale tomar essa decisão de propósito do que tê-la a cair a meio de uma construção. Se vais manter o certificado autoassinado, escreve validate_certs: false e aceita o reparo; se tens uma cadeia como deve ser, aponta o ca_path para ela. Seja como for, fica escrito.

A criação mínima viável

Reduz a tarefa de produção ao que de facto define uma máquina e ela fica legível:

- name: Create Proxmox VM
  delegate_to: localhost
  register: created_vm
  community.proxmox.proxmox_kvm:
    api_host: "{{ proxmox_api_ip }}"
    api_user: ansible@pve
    api_token_id: automation
    api_token_secret: "{{ proxmox_token_secret }}"
    validate_certs: true

    node: pve1
    name: "{{ inventory_hostname }}"
    cores: "{{ vcpus | int }}"
    memory: "{{ memory }}"
    machine: q35
    bios: ovmf
    ostype: l26
    scsihw: virtio-scsi-single
    scsi:
      scsi0: "vmdata:32,format=qcow2,discard=on,ssd=1"
    sata:
      sata0: "isos:iso/debian-13-netinst.iso,media=cdrom"
    net:
      net0: "virtio,bridge=vmbr0"
    efidisk0:
      storage: vmdata
      format: raw
      efitype: 4m
      pre_enrolled_keys: true
    boot: "order=scsi0;sata0"
    agent: "enabled=1,fstrim_cloned_disks=1"
    onboot: true
    tags:
      - production

Vale a pena saber algumas coisas sobre esta forma antes de escreveres a tua.

As opções de dispositivo são sintaxe PVE dentro de YAML. scsi, sata, net, virtio, ide são todas do tipo dict, com chaves scsi0, net0 e por aí fora, e os valores são as strings de opções separadas por vírgulas tiradas diretamente do man qm: <storage>:<size>,option=value para um disco, [model=]<enum>,option=value para uma NIC. O módulo não as modela; reencaminha-as. Quando algo é rejeitado, a resposta está na referência de opções do PVE, não na documentação do Ansible.

Também vais ver isto escrito como string JSON em vez de um mapeamento YAML:

    net: '{"net0":"virtio,bridge={{ vlan_bridge }}"}'

Ambas funcionam. O Ansible converte a string para um parâmetro do tipo dict. A forma JSON existe porque é mais fácil gerar uma estrutura inteira numa só expressão Jinja. A forma de mapeamento é mais fácil de ler seis meses depois.

O boot tem duas gerações de sintaxe. O módulo aceita as letras antigas, em que boot: "cdn" significa «tenta o disco, depois o CD-ROM, depois a rede». O PVE atual quer uma lista ordenada explícita, boot: "order=scsi0;sata0;net0", que não deixa dúvidas sobre qual disco. A forma antiga continua a funcionar. A forma explícita é a que queres em trabalho novo. Uma verdadeira ratoeira enterrada na documentação do módulo: o arranque pela rede requer definir rng0 desde o PVE 8.3.5.

numa e numa_enabled são parâmetros diferentes. O numa_enabled é o booleano que liga o NUMA. O numa é um dict que descreve uma topologia (cpus, hostnodes, memory, policy). Definir numa: true é um erro de tipo, e é uma hora fácil de perder. Se queres saber porque é que isto importa, o alinhamento NUMA no Proxmox trata do problema de fundo.

machine: q35 e bios: ovmf são as predefinições certas, não decoração: esse argumento por inteiro.

Omitir o vmid significa que o módulo pede à API o próximo ID livre. Conveniente, e a causa direta da coisa seguinte.

Porquê serial: 1

«Ir buscar o próximo ID disponível, e depois criar uma VM com ele» são duas chamadas à API com um intervalo no meio. Dois workers a fazer isso ao mesmo tempo podem ler o mesmo ID livre, e o perdedor recebe um erro ou, pior, uma surpresa.

O serial: 1 faz a fase de criação um anfitrião de cada vez. Não é rápido e não precisa de ser. A parte cara de construir uma VM acontece depois de este playbook passar o testemunho. O play correspondente que arranca as VMs terminadas usa serial: 5, porque arrancar não tem nenhum contador partilhado onde haja corrida.

Se preferires ter o paralelismo, atribui tu o VMID a partir da tua fonte de verdade e passa-o explicitamente. Assim não há ler-modificar-escrever nem corrida.

A idempotência não é o que esperas

Esta é a secção para ler duas vezes, porque o proxmox_kvm não se comporta como o ansible.builtin.package.

O name não é uma identidade. Os nomes das VMs não são únicos num cluster Proxmox, e o módulo di-lo. Com state: present e sem vmid, se já existir uma VM com esse nome, o módulo sai com changed=false e msg: "VM with name <x> already exists" e não faz nada. Não compara os teus parâmetros com a realidade. Não converge. Recusa-se.

O update tem false por predefinição. Por isso editar o memory: no teu playbook e voltar a executar não faz nada. A VM fica com a memória com que foi construída, a tarefa reporta sucesso, e nada em lado nenhum te diz que as duas divergiram.

O update: true continua a recusar os parâmetros interessantes. Da documentação do módulo:

Because of the operations of the API and security reasons, I have disabled the update of the following parameters net, virtio, ide, sata, scsi. Per example updating net update the MAC address and virtio create always new disk…

O update_unsafe: true levanta essa restrição, e o aviso não está lá para enfeitar:

Use this option with caution because an improper configuration might result in a permanent loss of data (for example disk recreated).

Portanto, o disco que julgavas estar a redimensionar pode ser substituído por um novo e vazio. Não vás por aí: os parâmetros recusados têm os seus próprios módulos, e isso é a secção seguinte.

E o --check não cobre nada disto. A coleção declara o suporte de modo de verificação módulo a módulo, e é inconsistente exatamente na direção errada:

Módulocheck_modediff_mode
proxmox_kvmnenhumnenhum
proxmox_disknenhumnenhum
proxmox_templatenenhumnenhum
proxmox_snaptotalnenhum
proxmox_nictotalnenhum
proxmox_pooltotalnenhum

A divisão não é «os módulos só de leitura podem, os de escrita não», porque o proxmox_nic cria e apaga interfaces e respeita perfeitamente o modo de verificação. É que os três módulos que lidam com armazenamento e ciclo de vida das VMs não o fazem. Uma execução --check de um playbook de construção salta em silêncio a criação da VM e depois reporta sobre um mundo onde a VM nunca foi feita, por isso cada tarefa a seguir está a raciocinar sobre o estado errado. Num playbook de construção, o --check não é uma rede de segurança, e tratá-lo como tal é pior do que não o correr.

O que uma segunda execução do proxmox_kvm faz de factosegunda execução — state: present, e existe uma VM com esse nomeo módulo nunca compara os teus parâmetros com a VM em execuçãoupdate: falsea predefiniçãochanged = false“VM with name <x>already exists”edita a memória no play,volta a executar, e nadaem lado nenhum te avisaupdate: trueconverge quase tudocores, memória, tags,agent, onboot aplicadosnet, virtio, ide, sata,scsi, efidisk0, tpmstate0recusados de propósitousa proxmox_disk eproxmox_nic para essesupdate_unsafe: trueconverge tudoos parâmetros recusadostambém são aplicadosum parâmetro de discopode recriar o discoperda de dados permanenteé o risco documentado--checknão te diz nadacheck_mode: nonea tarefa é saltadacada tarefa seguinteraciocina sobre um mundoonde a VM nuncafoi criadaDois dos quatro convergem alguma coisa, e o quecobre discos é o que os pode destruir.Por isso condiciona tu à existência, e trata a criaçãocomo um acontecimento único.
O que uma segunda execução faz de facto. Dois dos quatro caminhos convergem alguma coisa, e o único que cobre discos é o que os pode destruir.

Então faz da existência a barreira

Dado tudo isso, o padrão que funciona é deixar de pedir ao módulo que seja idempotente e decidir tu se deves construir. O playbook de produção fá-lo assim:

- name: Check if VM is present or manually built
  delegate_to: localhost
  community.proxmox.proxmox_vm_info:
    api_host: "{{ proxmox_api_ip }}"
    api_user: "{{ proxmox_user }}"
    api_password: "{{ proxmox_password }}"
    name: "{{ inventory_hostname }}"
    config: current
  register: existing_vm
  ignore_errors: true
  failed_when: (existing_vm.proxmox_vms | length) == 0

- name: Configure Proxmox VM
  when: existing_vm is failed
  block:
    - name: Create Proxmox VM
      ...

O proxmox_vm_info com config: current devolve a VM e a sua configuração ativa, ou uma lista vazia. O failed_when transforma «lista vazia» numa falha, o ignore_errors: true impede essa falha de terminar o play, e o when: existing_vm is failed passa a ser «a VM não está lá, constrói-a».

Usar uma tarefa deliberadamente falhada como booleano lê-se mal, e não vou fingir o contrário. A alternativa é when: (existing_vm.proxmox_vms | default([]) | length) == 0, que é honesta quanto a ser uma verificação de comprimento e não precisa de ignore_errors. Ambas funcionam. A versão acima é a que está em produção, e a sua única vantagem real é que o resultado registado traz a configuração existente para as tarefas seguintes lerem.

O que importa é a forma, não a grafia: verifica, depois ramifica, e trata a criação como um acontecimento único. A configuração contínua de uma VM é um problema diferente da existência de uma VM, e este módulo só é bom no segundo.

Discos e NICs têm os seus próprios módulos

Eis a coisa por que passei por cima acima, e muda o quadro todo: os parâmetros que o proxmox_kvm se recusa a atualizar não são uma lacuna na coleção. São delegados. O community.proxmox.proxmox_disk e o community.proxmox.proxmox_nic acrescentam, alteram e removem exatamente as coisas em que o módulo de criação não toca, com chaves nos mesmos nomes scsi0 e net0 que usaste quando construíste a VM.

Ambos se portam melhor do que o proxmox_kvm, e um deles é o único módulo neste fluxo de trabalho que pode ser ensaiado a seco.

proxmox_nic — Acrescentar, mudar a tag ou remover uma interface

- name: Move the VM's primary NIC to a new bridge and VLAN
  delegate_to: localhost
  community.proxmox.proxmox_nic:
    api_host: "{{ proxmox_api_ip }}"
    api_user: ansible@pve
    api_token_id: automation
    api_token_secret: "{{ proxmox_token_secret }}"
    vmid: "{{ created_vm.vmid }}"
    interface: net0
    bridge: vmbr1
    tag: 120
    model: virtio
    mtu: 1
    queues: 4
    firewall: true
    state: present

O interface é a única opção obrigatória além da autenticação, net[n] em que n vai de 0 a 31, e state: present ou absent dá-te acrescentar e remover. O model tem virtio por predefinição, que é a resposta certa a não ser que um convidado não aguente.

A razão de este módulo existir é o endereço MAC. Lembra-te porque é que o proxmox_kvm se recusa a atualizar o net: «updating net update the MAC address». O proxmox_nic resolve isso explicitamente:

When not specified this module will keep the MAC address the same when changing an existing interface.

Portanto, podes mudar a tag de uma VLAN, mudar de bridge, alterar o MTU ou ligar a firewall sem que a identidade da NIC do convidado mude por baixo dele. Isso importa mais do que parece: um MAC novo invalida reservas DHCP, estraga tudo o que esteja licenciado a uma NIC, e dessincroniza o registo de interface do NetBox que o playbook de criação escreveu com tanto cuidado. Este é o módulo que deixa uma alteração de rede do dia 2 ser aborrecida.

Algumas opções que vale a pena conhecer antes de precisares delas:

  • O rate é em MBps, MegaBytes por segundo, não bits. A documentação é explícita e o erro de um fator de oito é muito fácil de cometer.
  • link_down: true desliga a interface, descrito na documentação como «like pulling the plug». Uma forma limpa de isolar uma VM suspeita sem a parar nem tocar no convidado.
  • trunks recebe uma lista de IDs de VLAN a deixar passar, para um convidado que faz as suas próprias tags.
  • mtu: 1 não é gralha nem um MTU de 1 byte: significa «herda o MTU da bridge», e só se aplica ao virtio.
  • queues define o multiqueue, de 0 a 16. Vale a pena igualar ao número de vCPUs em tudo o que tenha tráfego a sério.

E suporta totalmente o modo de verificação. O --check numa tarefa proxmox_nic diz-te a verdade, o que faz dele a única parte deste fluxo de trabalho que podes ensaiar em segurança. As suas mensagens também são devidamente idempotentes. Uma interface inalterada reporta Nic net0 unchanged on VM with vmid 103 em vez de alegar uma alteração.

proxmox_disk — O ciclo de vida completo do disco

O proxmox_disk é o maior módulo dos três, e o seu state faz cinco trabalhos diferentes:

stateO que aconteceReversível?
presentcria o disco, ou atualiza as opções de um existenten/a
resizedaumenta-o; o PVE não consegue encolher, e a documentação diz para o fazer à mãonão
detachedpassa a unused[n]; o volume e os seus dados ficamsim
movedmuda o armazenamento de suporte, ou entrega o disco a outra VMoriginal mantido salvo delete_moved
absentremovido do armazenamento de suportenão

O espaço entre detached e absent é a rede de segurança que o proxmox_kvm nunca te dá. Desanexar é uma alteração de configuração; apagar destrói dados. Duas palavras diferentes, duas consequências diferentes.

Acrescentar um segundo disco a uma VM que já existe:

- name: Add a data disk
  delegate_to: localhost
  community.proxmox.proxmox_disk:
    api_host: "{{ proxmox_api_ip }}"
    api_user: ansible@pve
    api_token_id: automation
    api_token_secret: "{{ proxmox_token_secret }}"
    vmid: "{{ created_vm.vmid }}"
    disk: scsi1
    storage: vmdata
    size: 200
    format: qcow2
    iothread: true
    aio: io_uring
    discard: "on"
    ssd: true
    backup: true
    state: present

O create é o botão que o proxmox_kvm devia ter tido. Controla o que o state: present pode fazer:

  • regular (a predefinição): cria o disco se faltar, caso contrário atualiza as suas opções.
  • disabled: só atualiza opções, e nunca cria. É o que deves usar quando estás a mudar cache ou iothread num disco que tem de já existir. Não te pode surpreender a fazer aparecer um volume novo porque uma chave estava mal escrita.
  • forced: cria sempre. Um disco existente é desanexado e deixado sem uso, não apagado.

Esse último comportamento é o pormenor importante. O create: forced é a opção com ar destrutivo, e mesmo assim não destrói nada: o volume antigo sobrevive como unusedN e podes voltar a anexá-lo. Compara isso com o proxmox_kvm mais update_unsafe, cujo modo de falha documentado é um disco recriado. Mais ou menos a mesma operação, raio de explosão muito melhor.

Aumentar um disco:

- name: Grow the data disk by 100 GiB
  delegate_to: localhost
  community.proxmox.proxmox_disk:
    api_host: "{{ proxmox_api_ip }}"
    api_user: ansible@pve
    api_token_id: automation
    api_token_secret: "{{ proxmox_token_secret }}"
    vmid: "{{ created_vm.vmid }}"
    disk: scsi1
    size: "+100G"
    state: resized

Atenção às unidades, porque o size muda de significado com o state. Com state: present é GiB como número simples (size: 200). Com state: resized leva um sufixo: +100G para somar ao tamanho atual, ou 500G como alvo absoluto. Um parâmetro, duas convenções, e a falha é silenciosa se adivinhares mal.

Mover um disco para outro armazenamento, que é o caso da migração ao vivo de um só volume:

- name: Move the disk to NVMe storage
  delegate_to: localhost
  community.proxmox.proxmox_disk:
    api_host: "{{ proxmox_api_ip }}"
    api_user: ansible@pve
    api_token_id: automation
    api_token_secret: "{{ proxmox_token_secret }}"
    vmid: "{{ created_vm.vmid }}"
    disk: scsi1
    target_storage: nvme-pool
    bwlimit: 200000
    delete_moved: true
    timeout: 3600
    state: moved

O target_storage move dentro de uma VM; o target_vmid entrega o disco a outra VM e requer o mesmo armazenamento em ambas. São mutuamente exclusivos. O delete_moved tem false por predefinição, por isso, por omissão, acabas com duas cópias e o original ali parado como não usado: seguro, e uma boa forma de encher um pool de armazenamento se nunca lá voltares.

O timeout tem 600 por predefinição aqui, contra 30 no proxmox_kvm. Parâmetro com o mesmo aspeto, diferença de vinte vezes, porque estas operações copiam dados. Aumenta-o para imagens grandes ou armazenamento lento; a documentação di-lo tanto para moved como para import_from.

O que nos leva à opção que faz deste módulo o caminho para V2V e imagens cloud:

    import_from: "vmdata:9000/base-debian13.qcow2"

O import_from constrói o disco a partir de um volume existente em vez de alocar um vazio: <STORAGE>:<VMID>/<NAME>, ou <STORAGE>:import/<NAME> usando o diretório de importação do armazenamento no PVE 9.x e posteriores. É mutuamente exclusivo com size, e só o root pode usar caminhos absolutos do sistema de ficheiros.

O resto da lista de parâmetros é a razão para anexar discos com este módulo em vez de diretamente na chamada de criação: cache, aio, iothread, discard, ssd, backup, detect_zeroes, e toda a família de limitação, iops, iops_rd, iops_wr, as variantes _max e _max_length, e os controlos de rajada bps_*_max_length. Nada disso é alcançável através do proxmox_kvm depois da criação.

Duas ressalvas, ambas da própria documentação do módulo:

  • Algumas alterações de opções precisam de reinício. «Some updates on options (like cache) are not being applied instantly and require VM restart.» Uma tarefa verde significa que a configuração foi escrita, não que a VM em execução se esteja a comportar de forma diferente.
  • Não suporta o modo de verificação. check_mode: none, tal como o proxmox_kvm. Por isso a coleção divide-se ao meio: as alterações de NICs podem ser ensaiadas com --check, as de discos não.

A divisão do trabalho

Para fazer istoUsa
Criar a VMproxmox_kvm, uma vez, condicionado à existência
Mudar cores, memória, tags, agent, onbootproxmox_kvm com update: true
Acrescentar, mudar a tag, desligar ou remover uma NICproxmox_nic
Acrescentar, aumentar, mover, desanexar ou remover um discoproxmox_disk
Snapshotproxmox_snap (também com modo de verificação total)
Tudo o que nenhum deles expõeqm set por SSH
Mudar um disco ou uma NIC através do proxmox_kvmnada: é para isto que serve o update_unsafe, e é por isso que não o deves usar

Constrói a VM com uma chamada mínima ao proxmox_kvm, e depois anexa os discos e as interfaces com os seus próprios módulos. São mais tarefas, e é a versão em que as alterações do dia 2 têm um caminho que não envolve uma opção cujo risco documentado é perder um disco.

Onde o módulo para

O proxmox_kvm tem uma lista enorme de parâmetros e mesmo assim não cobre tudo o que o qm consegue fazer. Em vez de esperar, o playbook de produção desce para a linha de comandos no nó:

- name: Set RNG source and better SPICE quality
  delegate_to: "{{ proxmox_api_host }}"
  become: true
  ansible.builtin.command:
    cmd: >-
      /usr/sbin/qm set {{ created_vm.vmid }}
      --rng0 source=/dev/urandom
      --spice_enhancements videostreaming=all

Não há nada de errado nisto. Não é idempotente em nenhum sentido útil, porque o qm set é uma escrita e vai reportar changed em cada execução, mas é explícito, é legível, e não finge. Se um módulo ganhar o parâmetro mais tarde, apagas a tarefa.

Outras coisas precisam de uma segunda passagem pelo módulo com update: true, porque não podem ser definidas na mesma chamada que cria a VM:

- name: Add SPICE-compatible USB device
  delegate_to: localhost
  community.proxmox.proxmox_kvm:
    api_host: "{{ proxmox_api_ip }}"
    api_user: "{{ proxmox_user }}"
    api_password: "{{ proxmox_password }}"
    node: "{{ proxmox_api_host }}"
    vmid: "{{ created_vm.vmid }}"
    usb:
      usb0: "spice,usb3=1"
    update: true
  when: spice_usb | default(false)

Repara que passa o vmid, não o name. Assim que tens o ID, usa-o. É o único identificador que a API trata como único.

E para as coisas que o QEMU consegue fazer e para as quais o PVE não tem opção, há o args, que é passado tal e qual para a linha de comandos do QEMU:

    args: >-
      -global scsi-hd.physical_block_size=4k
      -global scsi-hd.logical_block_size=4096

Esse apresenta o disco virtual como 4Kn em vez de 512e, o que importa mais do que parece: tamanhos de bloco, 4Kn e 512e. O módulo marca o args como «for experts only», e a razão é que o PVE não o valida e uma flag errada impede a VM de arrancar com um erro que vem do QEMU e não do Proxmox.

O cluster não é instantaneamente consistente

- name: Let registration complete on cluster
  ansible.builtin.pause:
    seconds: 5
  when: created_vm.changed

Uma pause num playbook costuma ser mau sinal, e esta aguenta peso. A chamada de criação regressa quando a API aceitou a definição, o que não é o mesmo que todos os nós concordarem que a VM existe, e a tarefa seguinte quer definir uma ACL em /vms/<vmid>. Cinco segundos de paciência saem mais baratos do que um ciclo de repetição à volta de um erro que só aparece sob carga.

O playbook de remoção tem a mesma forma pela mesma razão: parar, esperar, depois apagar.

Ler de volta o que construíste

O proxmox_kvm documenta três valores de retorno: vmid, status e msg. Na prática vais querer um quarto, e ele não está na documentação.

- name: Get MAC address of VM
  ansible.builtin.set_fact:
    primary_mac_addr: "{{ created_vm.mac.net0 }}"

O created_vm.mac é real, o módulo constrói-o em get_vminfo() e despeja-o no resultado, mas não consta do bloco RETURN documentado, o que significa que nada promete que continue a funcionar. Vale a pena saber exatamente como se comporta, porque tem duas armadilhas:

  1. Só aparece quando o módulo criou de facto a VM. O mac só é montado no caminho de criar e implementar. Vai pelo ramo «already exists» e o resultado tem vmid e msg e mais nada.
  2. Só contém as interfaces que passaste. O código percorre os parâmetros que tu forneceste e escolhe os que correspondem a net[0-9], depois lê a configuração guardada de cada um a partir da API. Sem parâmetro net, não há chave mac.

É por isso que o playbook de produção precisa das duas metades, e a segunda é feia:

- name: Get MAC address of VM
  ansible.builtin.set_fact:
    primary_mac_addr: >-
      {{ created_vm.mac.net0 if created_vm is defined and created_vm.changed
         else ((existing_vm.proxmox_vms[0].config.net0 | split(','))[0] | split('='))[1] }}

Quando a VM já existia, não há mac, por isso o MAC tem de ser escavado da string de configuração em bruto. O net0 volta da API como virtio=AE:AE:5C:A8:89:85,bridge=vmbr0, portanto: divide pelas vírgulas, fica com o primeiro campo, divide pelo =, fica com a segunda metade. É cirurgia de strings numa resposta de API, e é o custo honesto de um módulo cuja forma de retorno depende do ramo que seguiu.

Se precisas do MAC de forma fiável nos dois casos, vai buscá-lo ao proxmox_vm_info incondicionalmente e analisa uma forma em vez de duas.

Conduzi-lo a partir de uma fonte de verdade

Olha outra vez para a linha que abre o play:

hosts: "{{ target_hosts | default('cluster_pve:&status_planned') }}"

Essa é a arquitetura real, e vale a pena dizê-lo claramente: as VMs a construir não são uma lista num ficheiro de variáveis. São os anfitriões do teu inventário cujo estado registado diz que deviam existir e ainda não existem.

O inventário aqui é o NetBox. Uma VM é pedida criando um registo no NetBox com o estado planned, com o seu CPU, memória, disco, VLAN, dono e plataforma. O playbook seleciona as máquinas planned, constrói-as, atribui um IP, escreve o DNS, e depois põe o registo em staged, momento em que esse anfitrião deixa de corresponder ao padrão de anfitriões do play, e um handler atualiza o inventário para que o play seguinte veja o novo estado:

handlers:
  - name: Refresh inventory
    ansible.builtin.meta: refresh_inventory

O campo de estado é uma máquina de estados, o playbook é uma transição dentro dela, e a coisa toda pode ser executada de novo porque um anfitrião que já avançou deixa de ser selecionado. Essa é uma propriedade muito melhor do que qualquer quantidade de idempotência ao nível do módulo, e é a razão pela qual a tarefa de criação se pode dar ao luxo de ser de uma só vez.

O community.proxmox também traz o seu próprio plugin de inventário, que constrói um inventário a partir do cluster: a escolha certa quando o Proxmox é a fonte de verdade. Aqui é ao contrário: o NetBox é a autoridade e o Proxmox é onde a sua intenção se concretiza. Isso dá um artigo inteiro e vou escrevê-lo à parte.

Desfazer tudo outra vez

Criar sem remover é meio ciclo de vida, e o caminho de remoção tem a sua própria armadilha: não podes apagar uma VM em execução:

- name: Force stop the VM if it is running
  delegate_to: localhost
  community.proxmox.proxmox_kvm:
    api_host: "{{ proxmox_api_ip }}"
    api_user: "{{ proxmox_user }}"
    api_password: "{{ proxmox_password }}"
    name: "{{ inventory_hostname }}"
    state: stopped
    force: true
    timeout: 10

- name: Allow the cluster to stop the VM before removing it
  ansible.builtin.pause:
    seconds: 10

- name: Remove the VM from the cluster
  delegate_to: localhost
  community.proxmox.proxmox_kvm:
    api_host: "{{ proxmox_api_ip }}"
    api_user: "{{ proxmox_user }}"
    api_password: "{{ proxmox_password }}"
    name: "{{ inventory_hostname }}"
    state: absent
    force: true
    timeout: 10

O state: stopped é um encerramento ordenado, e a interação com o timeout está documentada e vale a pena decorar: se o tempo limite for atingido com force: true, a VM é desligada à força; com force: false, a tarefa falha. Uma janela ordenada de dez segundos seguida de puxar a ficha é uma política razoável para uma máquina que está a ser desmantelada, e péssima para qualquer outra coisa.

A remoção completa (proxmox-remove-vms.yml) desfaz depois o resto do registo: o DNS, o IP atribuído, as interfaces no NetBox, a VM no NetBox, e as entradas obsoletas no known_hosts. Envolve o bloco em ignore_errors: true, o que se defende numa remoção. Estás a remover coisas que podem já ter desaparecido, e uma máquina meio apagada é pior do que um registo barulhento.

O que eu mudaria numa construção de raiz

Tendo lido o código-fonte do módulo e não só a documentação, cinco coisas:

  • Usa um token de API, não api_user mais api_password. Com âmbito limitado, revogável, e nunca pertence a uma pessoa.
  • Define o validate_certs explicitamente, antes que a 2.0.0 o mude por baixo de ti.
  • Atribui tu o VMID a partir da fonte de verdade. Elimina a corrida de ler-modificar-escrever, deixa-te abandonar o serial: 1, e dá a cada tarefa seguinte um identificador estável em vez de um nome que não é único.
  • Cria a VM despida, e depois anexa os discos e NICs com proxmox_disk e proxmox_nic. Mais tarefas, mas cada disco e interface passa a ter um módulo que o pode alterar mais tarde, incluindo create: disabled para edições só de opções e state: detached em vez de apagar, em vez de uma configuração que só pode ser mudada através do update_unsafe.
  • Vai buscar o MAC ao proxmox_vm_info num só sítio, para haver uma forma a analisar em vez de uma condição entre um valor de retorno documentado e um não documentado.

E não recorras ao --check num playbook de construção. O módulo que importa não o consegue respeitar.

Um ensaio a seco que diz sempre que sim é pior do que nenhum ensaio, porque vais acreditar nele.

Referências