Tutorial do Debian 13 / Executar contêineres Podman sem root e preservar dados em volumes

No Debian 13, você pode executar o Podman como um usuário comum e criar contêineres sem root. Para reter os arquivos necessários mesmo após a substituição, você precisa guardar os dados persistentes em um volume separado da camada gravável do contêiner e executá-lo novamente com o mesmo usuário e mesmo volume. Este tutorial fixa a imagem oficial httpd por seu digest (identificador do conteúdo) e verifica a resposta e a preservação dos dados em uma porta de loopback.

Separe imagens, contêineres e volumes nomeados

Uma imagem é uma unidade de distribuição contendo o programa e os arquivos necessários para a execução, enquanto um contêiner é uma instância em execução criada a partir de uma imagem. Arquivos escritos na camada gravável do contêiner, fora do armazenamento montado separadamente, são perdidos quando esse contêiner é excluído. Volumes nomeados são espaços de armazenamento gerenciados com nomes separados, cujo ciclo de vida pode ser gerenciado independentemente da substituição do contêiner.

Rootless significa executar com privilégios de usuário comum no host. O identificador do usuário (UID, User ID) 0 dentro do contêiner não é tratado da mesma forma que o root no host. Um contêiner rootless ainda pode usar os recursos disponíveis para aquele usuário do host e compartilha o kernel do host. Seu isolamento não é equivalente a uma VM separada. A estrutura básica de execução pode ser consultada na documentação Podman 5.4.2.

Alvo Nome da prática Manuseio durante a substituição
Imagem digest do docker.io/library/httpd Registre o digest para recriar um contêiner com o mesmo conteúdo da imagem.
Contêiner lf-web27 Pare e exclua, depois crie um novo.
Volume nomeado lf-web27-data Preserve durante a substituição do contêiner e conecte ao novo contêiner.
Porta externa 127.0.0.1:8080 Acessível apenas dentro da VM Debian, e verifique novamente após a execução.

Verifique os pacotes e a sessão do usuário comum

É necessária uma VM Debian 13 separada com acesso sudo e uma rede para acessar o registro de imagens. Execute a instalação apenas com sudo e, a partir daí, todos os comandos do podman devem ser executados como o usuário comum logado. Não mude para sudo podman, pois isso acessaria o armazenamento de imagens e contêineres separado do root, não misture esses dois ambientes de armazenamento durante o diagnóstico.

sudo apt update
sudo apt install podman uidmap passt fuse-overlayfs curl
podman --version
id
printf '%s\n' "$XDG_RUNTIME_DIR"
grep "^$(id -un):" /etc/subuid /etc/subgid
systemctl --user is-system-running
podman info --format json

O teste original usou Podman 5.4.2, um usuário comum com UID e GID (Group ID, identificador do grupo) 1000, e o caminho de execução /run/user/1000. /etc/subuid e /etc/subgid continham cada um lfstudent:100000:65536, e o gerenciador de usuários estava em execução. Esse intervalo é usado ao mapear IDs de usuários adicionais do contêiner. Não copie intervalos de outras contas para alocar duplicatas.

O comando podman info mostrou host.security.rootless como true, cgroupVersion como v2, cgroupManager como systemd, e armazenamento no diretório home do usuário usando overlay. Se houver erros de variáveis de ambiente ou de conexão do gerenciador de usuários, verifique novamente a partir de uma sessão real de login SSH ou console do usuário comum. Não falsifique XDG_RUNTIME_DIR com nenhum caminho nem misture ambientes sudo para que pareça normal.

Se algum nome de laboratório ou a porta 8080 já estiver em uso, planeje mudar o nome do exercício e a porta sem remover os recursos existentes. Use uma sessão Bash dedicada para o laboratório. O bloco de preparação habilita a parada em caso de erro; se uma falha inesperada encerrar o shell, inspecione os recursos restantes a partir de uma nova sessão de usuário comum antes de continuar.

set -euo pipefail
if podman container exists lf-web27; then
    echo "A container with this name already exists." >&2
    exit 1
fi
if podman volume exists lf-web27-data; then
    echo "A volume with this name already exists." >&2
    exit 1
fi
if test -e "$HOME/lf-course27-image.txt"; then
    echo "The image record file already exists." >&2
    exit 1
fi
ss -ltn

Selecione a imagem oficial e registre seu digest

Em vez de usar um nome curto httpd, use um endereço que inclua o registro e o namespace. Guia da Imagem Oficial Docker httpd foi usado para verificar e selecionar a tag, Dockerfile e o caminho raiz da web. Esta é a Imagem Oficial Docker para o Apache HTTP Server e executa programas dentro do contêiner que são diferentes do Nginx do host.

podman pull docker.io/library/httpd:2.4.71-trixie
image=$(podman image inspect docker.io/library/httpd:2.4.71-trixie --format '{{index .RepoDigests 0}}')
case "$image" in
    docker.io/library/httpd@sha256:*) ;;
    *) echo "Unexpected image reference." >&2; exit 1 ;;
esac
printf '%s\n' "$image" | tee "$HOME/lf-course27-image.txt"
podman image inspect "$image" --format '{{.Architecture}} {{.Os}} {{.Id}}'

As referências registradas durante a verificação são as seguintes. Na execução real, use os valores obtidos na inspeção acima e, se a tag mudar, um novo digest pode aparecer. A arquitetura era amd64 e o sistema operacional era linux.

docker.io/library/httpd@sha256:32e9403360ab2f1047523e72f256527fb9aee68b342abf6ad03f0d629157f3d9

As tags podem se mover para outras imagens, mas o digest é usado para identificar o conteúdo. Registrar o digest não resolve automaticamente quem criou a imagem nem responde a vulnerabilidades. Imagens fixas não atualizam automaticamente para os patches de segurança mais recentes, então o cronograma de revisão, teste e substituição das novas versões é gerenciado separadamente. Se o pull falhar, diferencie entre autenticação do registro, limites de solicitação, DNS, TLS e erros de rede, e não execute imagens arbitrárias com o mesmo nome em vez disso.

Preencha um volume dedicado e publique uma porta no loopback

Primeiro, crie um volume nomeado e depois registre index.html com um contêiner de uso único. O contêiner de preparação não precisa de uma rede, então ele roda com none e é removido com --rm após sair. O volume em si permanece. Este volume é para fins de prática novos, então ele não sobrescreve o diretório raiz da web de serviços existentes.

podman volume create lf-web27-data
podman run --rm --network none -v lf-web27-data:/data --entrypoint /bin/sh "$image" -c 'printf "LF PODMAN 27\n" > /data/index.html'
podman run -d --name lf-web27 -p 127.0.0.1:8080:80 -v lf-web27-data:/usr/local/apache2/htdocs:ro "$image"
podman ps
podman port lf-web27
curl --noproxy '*' -fsS http://127.0.0.1:8080/

O lado esquerdo de -p é o endereço do host e porta, e o lado direito 80 é a porta dentro do contêiner. Especificar 127.0.0.1 faz com que seja acessível apenas dentro da VM. O :ro no final de -v monta o volume como somente leitura para este servidor web. Não é uma configuração global que impede outros contêineres ou processos do host de escrever no volume, portanto, esta etapa se distingue da etapa em que o contêiner de preparação escreve nele.

A porta realmente reportada foi 80/tcp → 127.0.0.1:8080, e a resposta foi LF PODMAN 27. Se for imediatamente após a inicialização, faça a solicitação novamente após um curto período. Se continuar a falhar, verifique conflitos de porta com podman logs lf-web27 e podman inspect lf-web27. Um contêiner estar em execução não significa que o serviço HTTP tenha sido bem-sucedido.

Substitua o contêiner e verifique a persistência dos dados

Os passos a seguir envolvem armazenar o hash dos arquivos do volume e criar um arquivo de comparação em /tmp do container. podman volume inspect é usado para ler o caminho do volume, mas outros diretórios dentro do armazenamento do Podman não são modificados diretamente. Após parar e deletar o container, verifique se os arquivos no volume permanecem os mesmos.

point=$(podman volume inspect lf-web27-data --format '{{.Mountpoint}}')
hash_before=$(sha256sum "$point/index.html")
podman exec lf-web27 sh -c 'printf "ephemeral\n" > /tmp/lf-web27-marker'
podman stop lf-web27
podman rm lf-web27
test -f "$point/index.html"
test "$hash_before" = "$(sha256sum "$point/index.html")"
podman run -d --name lf-web27 -p 127.0.0.1:8080:80 -v lf-web27-data:/usr/local/apache2/htdocs:ro "$image"
curl --noproxy '*' -fsS http://127.0.0.1:8080/
podman exec lf-web27 test ! -e /tmp/lf-web27-marker

No teste original, a resposta HTTP do novo contêiner foi a mesma, e o hash do index.html também era idêntico. Por outro lado, os arquivos em /tmp do contêiner anterior não estavam presentes no novo contêiner. O último teste não imprime nada se for bem-sucedido e retorna o código de saída 0. A partir desses resultados, você pode distinguir as diferenças de duração entre volumes e camadas graváveis do contêiner.

Se o novo contêiner demorar para ficar pronto e o curl falhar, verifique o estado atual e os logs e tente a solicitação novamente. Em um shell que para em caso de erros, não presuma que a limpeza foi realizada posteriormente; verifique os recursos restantes com podman ps -a e podman volume ls. Preservar volumes é diferente de backup. Perder o diretório home do usuário ou o disco do host também poderia resultar na perda dos mesmos volumes locais.

Inspecione o estado real do AppArmor no contêiner em execução

Mesmo que o AppArmor esteja habilitado no host, não se deve assumir que todos os contêineres sem root estejam restritos por um perfil aplicado. Com o contêiner substituído agora em execução, compare as informações de inspeção e o estado real do processo usando o seguinte comando.

podman info --format json
podman inspect lf-web27 --format '{{.AppArmorProfile}}'
podman exec lf-web27 cat /proc/self/attr/current

O registro do teste original foi obtido com o primeiro contêiner em execução; o leitor pode repetir a consulta no contêiner substituído antes de pará-lo. O módulo AppArmor do host era Y, mas o apparmorEnabled das informações de rootless era false, o AppArmorProfile do contêiner estava vazio e a saída do processo era crun (unconfined). Não interprete esses resultados como um perfil AppArmor em modo enforce aplicado a este contêiner. Não desabilitamos o AppArmor nem o seccomp, nem adicionamos --privileged para evitar erros.

Compare os mapeamentos UID do host e do contêiner

Verifique o mapeamento de ID numérico em vez do nome de usuário do container sem root. No namespace padrão desta prática, o UID 0 do container correspondia ao UID 1000 do host, e os UIDs 1 a 65536 correspondiam a UID 100000 em diante no host. Os grupos tinham a mesma estrutura. Isso pode variar com uma conta diferente ou com a opção --userns.

podman unshare cat /proc/self/uid_map /proc/self/gid_map
stat -c '%u:%g' "$point/index.html"
podman unshare stat -c '%u:%g' "$point/index.html"

O index.html aparecia como 1000:1000 no host e 0:0 dentro do podman unshare. Unshare é uma ferramenta para observar o mesmo arquivo sob a perspectiva de um ID diferente dentro do namespace de usuário do Podman, e não é um comando que lhe dá acesso root em todo o host. O manual do podman unshare descreve este escopo de namespace.

Para comparação adicional, após parar o servidor, crie um único arquivo no mesmo volume de prática e defina-o para o UID/GID do contêiner 33. Este número é apenas para observar o mapeamento e não significa que todas as imagens usem a mesma conta de serviço.

podman stop lf-web27
podman rm lf-web27
podman run --rm --network none -v lf-web27-data:/data --entrypoint /bin/sh "$image" -c 'printf "mapped\n" > /data/mapped.txt; chown 33:33 /data/mapped.txt'
stat -c '%u:%g' "$point/mapped.txt"
podman unshare stat -c '%u:%g' "$point/mapped.txt"

O resultado real foi host 100032:100032, namespace 33:33. Isso não é o mesmo que alterar o proprietário do arquivo para 33 no host. Para resolver problemas de permissão, não aplicamos chown em todo o diretório home do usuário. A opção :U pode alterar recursivamente a propriedade do lado do host, e :z e :Z estão relacionadas a rótulos do SELinux, portanto, não são aplicadas como uma solução geral para problemas do AppArmor. Os efeitos exatos das opções de volume podem ser verificados em Opções de volume e segurança do Podman run.

Remova apenas o volume do laboratório e preserve o registro da imagem

Se você concluiu a comparação de mapeamento acima, lf-web27 já foi parado e removido. Confirme isso em podman ps -a antes de remover seu volume. Se você pulou essa comparação e o contêiner do laboratório ainda existir, pare-o com podman stop lf-web27 e remova-o com podman rm lf-web27. Não force a remoção de um volume em uso.

Excluir os volumes dedicados restantes neste exercício também excluirá seus dados. Primeiro, determine se algum arquivo precisa ser preservado e, em seguida, remova apenas o nome específico. O escopo de criação e gerenciamento de volumes nomeados pode ser verificado na documentação Podman volume create.

podman ps -a
podman volume inspect lf-web27-data
podman volume rm lf-web27-data
podman volume ls
ss -ltn

Na limpeza do teste original, apenas o contêiner lf-web27 e o volume lf-web27-data foram removidos. As imagens recebidas e os registros de digest de lf-course27-image.txt foram mantidos, e o prune, que exclui outras imagens e volumes em massa, não foi usado. Decidindo separadamente se mantém os dados persistentes e as informações de reprodução de imagens, é possível evitar confundir a limpeza de exercícios com a exclusão de dados operacionais.