Podman Quadletでコンテナをsystemdユニット化する｜Compose資産の移行と自動起動・ログ管理の確認手順

Quadletが生まれた背景と解決する課題

コンテナ運用の現場では、docker-composeやpodman-composeで構成されたサービス群をLinuxサーバの起動・停止ライフサイクルと連携させる際に、何らかの「糊付け」が必要になります。従来はsystemdユニットファイルを手書きしてExecStartにPodmanコマンドを記述する方法が広く使われていましたが、ユニットファイルの保守が煩雑になること、ネットワークやボリュームの依存順序を別途管理しなければならないことが長年の課題でした。

Quadletはこの問題をPodman側で吸収するアプローチです。Podman 4.4（2023年初頭）で実装が取り込まれ、2024年後半以降はRHEL 9.4・Fedora 40以降の標準パッケージに同梱されています。.container・.network・.volume・.podといった専用拡張子を持つファイルをsystemdの管理下に置くだけで、以前のpodman generate systemdのような一時的な変換作業なしにコンテナをサービスとして扱えるようになります。

重要な点は、QuadletがsystemdのGeneratorとして動作することです。/etc/containers/systemd/（rootユニット）または~/.config/containers/systemd/（rootlessユニット）に配置されたファイルを、systemd起動時に読み取って通常のサービスユニットへ自動変換します。運用者はComposeファイルに近い感覚で記述でき、かつ管理はすべてsystemctlに集約されます。

.containerファイルの基本構成と書き方

Quadletの中心となるのが.containerファイルです。INIスタイルのセクション構造で、systemdユニット標準の[Unit]・[Service]・[Install]に加え、Podman固有の[Container]セクションが追加されます。

例として、nginxをrootlessで動かす最小構成を示します。

# ~/.config/containers/systemd/nginx.container

[Unit]
Description=Nginx Web Server (Quadlet)
After=network-online.target

[Container]
Image=docker.io/library/nginx:1.27
PublishPort=8080:80
Volume=%h/nginx/html:/usr/share/nginx/html:ro,Z
Environment=NGINX_ENTRYPOINT_QUIET_LOGS=1
AutoUpdate=registry

[Service]
Restart=always
TimeoutStartSec=30

[Install]
WantedBy=default.target

[Container]セクションの主要キーを整理します。Imageはレジストリパスを含む完全な形式が推奨されます。PublishPortはdocker-composeのportsに相当し、複数行記述で複数ポートを指定できます。Volume末尾の:ZはSELinuxラベルの自動付与指示で、RHEL・Fedora環境では省略しないのが安全です。AutoUpdate=registryを指定しておくと、podman auto-updateコマンドまたはシステムタイマーが最新イメージの有無を自動確認します。

ユーザー変数として%h（ホームディレクトリ）や%u（ユーザー名）がsystemdのSpecifierとして使えるため、rootlessユニットの可搬性が高まります。環境ごとのパスを変数化しておくことで、開発機と本番サーバで同じファイルをそのまま使い回せます。

Compose資産からQuadletへの移行手順

既存のdocker-composeまたはpodman-composeのYAMLをQuadletへ移行する場合、コミュニティ製の自動変換ツールpodman-compose2quadletが参考になりますが、複雑な構成では出力を手動修正することが多く、現時点では「たたき台」として活用するのが現実的です。以下では手動移行の考え方を整理します。

ComposeファイルからQuadletへの対応関係は次のとおりです。

• services の各エントリ → 対応する.containerファイル（1サービス1ファイル）
• networks → .networkファイル（外部ネットワーク参照でなければ省略可）
• volumes（名前付き） → .volumeファイル
• depends_on → [Unit]のRequires=/After=で表現

サービス間通信にComposeの内部ネットワークを使っていた場合、.networkファイルを用意してネットワークを定義し、各.containerファイルでNetwork=myapp.networkと参照します。この参照記法が重要で、拡張子を含む「ファイル名.network」という形式がQuadlet内部で解決されます。

ファイルを配置したら、systemdにGeneratorを再実行させます。

# rootlessの場合
systemctl --user daemon-reload

# root（/etc/containers/systemd/ 配置）の場合
systemctl daemon-reload

daemon-reload後、Quadletが変換したユニット名は元のファイル名から拡張子を除いたものになります。nginx.containerならnginx.serviceとして参照できます。変換が正しく行われたかどうかはsystemctl --user cat nginx.serviceで生成済みユニットの内容を確認する方法が手っ取り早いです。

自動起動の有効化と動作検証

Quadletユニットはsystemdの管理下に入るため、自動起動はsystemctl enableで設定します。[Install]セクションにWantedBy=が記述されている場合、--nowフラグで有効化と即時起動を同時に行えます。

# rootlessユニットの有効化と起動
systemctl --user enable --now nginx.service

# サーバ起動時（ユーザーログイン前）から動作させる
loginctl enable-linger $(whoami)

rootlessコンテナをサーバ起動直後から動作させるには、loginctl enable-lingerによるlinger有効化が必須です。これを設定していないと、ユーザーセッションが存在しない状態ではsystemdユーザーインスタンス自体が起動せず、コンテナも起動しません。移行後のトラブルとして現場でよく挙がるポイントのため、確認項目として必ず含めてください。

起動後の状態確認は次のコマンドで行います。

systemctl --user status nginx.service
podman ps --filter label=io.containers.autoupdate

systemctl statusで「Active: active (running)」が確認できれば基本動作は問題ありません。podman psで表示されるコンテナのラベルにも注目すると、Quadletが付与したメタデータを確認でき、Composeで管理されているコンテナとの区別にも役立ちます。

journaldによるログ管理と確認手順

Quadletで管理されるコンテナのログはsystemdのジャーナルに統合されます。コンテナのstdout/stderrがそのままjournaldへ転送されるため、podman logsの代わりにjournalctlを中心としたログ管理が可能です。

# リアルタイム追跡
journalctl --user -u nginx.service -f

# 直近1時間のログ
journalctl --user -u nginx.service --since "1 hour ago"

# エラー以上のみ表示
journalctl --user -u nginx.service -p err

コンテナ内のアプリケーションがJSONフォーマットでログを出力している場合、journalctl -o jsonオプションとjqを組み合わせることで構造化ログとして扱えます。コンテナのPIDとsystemdのユニット名が紐付いているため、複数サービスが混在する環境でもユニット名でのフィルタリングが有効です。

ログの保持期間は/etc/systemd/journald.confのSystemMaxUseやMaxRetentionSecで制御します。コンテナが大量のログを出力する構成ではシステム全体のジャーナルサイズへの影響を事前に見積もることが重要です。podman logsコマンドも引き続き使用できますが、ログの永続性と検索性においてjournaldに劣るため、本番環境のログ管理はjournalctl中心で設計することが推奨されます。

2026年現行環境での注意点と差分

2026年8月時点では、Podman 5.x系が主要ディストリビューションの標準パッケージとなっています。Podman 5.0で.kube形式（Kubernetes YAMLからの直接起動）のQuadletサポートが強化されており、Kubernetes移行を見据えた構成として採用するケースも増えています。既存の.containerファイルをそのまま使いながら、段階的にKubernetes YAML形式へ移行する経路が現実的な選択肢として浮上しています。

RHEL 10 / Fedora 42以降ではpodman-quadletパッケージが分離して提供される形になっており、作業前にインストール状況を確認することが推奨されます。rpm -q podman-quadletまたはdpkg -l podmanでバージョンを確認し、Podman 4.4未満の環境では別途対応が必要です。一部のLTSディストリビューションでは古いPodmanが残っているケースがあるため注意が必要です。

podman auto-updateのsystemdタイマー（podman-auto-update.timer）はRHEL 9以降でデフォルト提供されています。AutoUpdate=registryを指定したQuadletユニットは、このタイマーが定期的にイメージの更新チェックを行い、新バージョンがあれば自動でサービスを再起動します。本番環境でこの挙動が望ましくない場合はAutoUpdateキーを省略するか、タイマーを無効化した上で手動更新フローを整備してください。

切り戻しを想定した運用では、イメージのタグにlatestを使わず、SHA256ダイジェスト指定または具体的なバージョンタグを用いることが基本です。Quadletファイル自体はテキストファイルであるためGitで管理しやすく、バージョン管理した.containerファイルの差し替えとdaemon-reload・restartの組み合わせが、最もシンプルな切り戻し手順として機能します。Infrastructure as Codeの観点でも、コンテナ定義とsystemdユニットが一体化したQuadletの構造は、GitOpsフローとの親和性が高いといえます。