Executar contêineres Podman como serviços systemd com Quadlet

Objetivo

Definir um contêiner gerenciado pelo Podman como um serviço systemd nativo, usando um arquivo de unidade .container do Quadlet, em vez da abordagem mais antiga de unidades geradas.

Pré-requisitos

Podman 4.4 ou superior (a primeira versão upstream com o gerador Quadlet; verifique com podman --version, pois versões enterprise mais antigas podem não tê-lo ou ter menos chaves); systemd no host. Acesso root para um serviço em todo o sistema, ou uma conta de usuário comum (mais lingering, se o serviço precisar rodar sem uma sessão de login) para um serviço rootless.

Passos

1. Entenda primeiro o mecanismo: podman-systemd.unit(5) documenta o Quadlet como um gerador do systemd que converte arquivos declarativos .container (e .volume, .network, .pod, .kube, .image, .build) em unidades .service comuns na inicialização ou em daemon-reload, sem exigir um arquivo de unidade gerado e mantido separadamente.
2. Não use podman generate systemd para novos serviços: a própria página de manual do comando o marca como obsoleto e recomenda o Quadlet.
3. Coloque uma unidade de sistema em /etc/containers/systemd/myapp.container, ou uma unidade por usuário em ~/.config/containers/systemd/myapp.container (outros caminhos de busca estão listados no manual). Um exemplo mínimo:

[Unit]
Description=My application container

[Container]
Image=docker.io/library/nginx:stable
PublishPort=8080:80
AutoUpdate=registry

[Service]
Restart=on-failure

[Install]
WantedBy=multi-user.target

Para uma unidade rootless (de usuário), use WantedBy=default.target; o gerenciador de usuário não tem multi-user.target. 4. Faça o systemd regenerar as unidades a partir do novo arquivo: sudo systemctl daemon-reload (sistema) ou systemctl --user daemon-reload (rootless). O manual do systemctl descreve daemon-reload como o recarregamento dos arquivos de unidade e, no caso dos geradores, a nova execução deles. 5. Inicie o serviço: sudo systemctl start myapp.service (ou systemctl --user start myapp.service). Não execute systemctl enable: unidades geradas não podem ser habilitadas. A inicialização no boot vem da seção [Install], que o gerador aplica por conta própria a cada execução. O contêiner se chama systemd-myapp, a menos que ContainerName= esteja definido. 6. AutoUpdate=registry marca o contêiner com um rótulo para o podman auto-update, que baixa uma imagem mais nova e reinicia a unidade. Isso só acontece quando o comando é invocado ou quando o podman-auto-update.timer está habilitado (sudo systemctl enable --now podman-auto-update.timer, ou com --user); para uma prévia, use podman auto-update --dry-run. A imagem deve ser uma referência totalmente qualificada. Verifique o rótulo com podman inspect --format '{{ index .Config.Labels "io.containers.autoupdate" }}' systemd-myapp.

Resultado esperado

systemctl status myapp.service --no-pager mostra a unidade gerada como ativa; parar e iniciar a unidade para e inicia o contêiner, respeitando a ordenação de dependências, as políticas de reinício e o registro de logs normais do systemd (journalctl -u myapp.service). Para desfazer, pare o serviço, apague o arquivo .container e execute daemon-reload novamente.

Limites e base de verificação

A sintaxe dos arquivos Quadlet e as chaves disponíveis são específicas do gerador e versionadas junto com a versão do Podman; consulte o man podman-systemd.unit local para ver as chaves suportadas pela versão instalada antes de usar alguma que não esteja mostrada aqui. Um erro de sintaxe ou uma chave não suportada faz o gerador ignorar o arquivo, e por isso o systemctl informa depois Unit myapp.service not found. Para ver a saída gerada e os erros, use /usr/lib/systemd/system-generators/podman-system-generator --dryrun (adicione --user para unidades rootless).