在 RHEL 10 Server 上使用 Podman 部署容器服务时,可以通过 Podman Quadlet 与 systemd 进行集成,将容器以 systemd 服务的方式统一管理。本文介绍如何使用 Kubernetes YAML 定义 Pod 和容器,并通过 Quadlet 配置实现容器服务的开机自动启动、停止、重启及状态管理,同时结合实际部署场景说明目录挂载、持久化数据以及服务管理中的常见问题,帮助在 RHEL Server 环境中建立更加规范、稳定的 Podman 容器运行方式。
相比手动执行:
podman kube play xxx.yaml
使用 Quadlet 后,可以让 systemd 负责容器服务的启动、停止和开机自动启动。
本文以 Uptime Kuma 为例,使用已有的 Kubernetes YAML 文件,通过 Quadlet 实现开机自动启动。
1. 准备 Podman Kube YAML
假设 Uptime Kuma 的 Kubernetes YAML 保存在:
/opt/data/uptime-kuma/uptime-kuma.yaml
例如:
apiVersion: v1
kind: Pod
metadata:
name: uptime-kuma
spec:
restartPolicy: Always
containers:
- name: uptime-kuma
image: docker.io/louislam/uptime-kuma:2
ports:
- containerPort: 3001
hostPort: 3001
protocol: TCP
env:
- name: TZ
value: "Asia/Shanghai"
volumeMounts:
- name: data
mountPath: /app/data
securityContext:
capabilities:
add:
- NET_RAW
runAsUser: 0
runAsGroup: 0
volumes:
- name: data
hostPath:
path: /opt/data/uptime-kuma/data
type: DirectoryOrCreate
先创建数据目录:
mkdir -p /opt/data/uptime-kuma
2. 创建 Quadlet 配置目录
root 用户使用的 Quadlet 文件可以放在:
/etc/containers/systemd/
创建目录:
mkdir -p /etc/containers/systemd
Podman 官方文档将 /etc/containers/systemd/ 作为 rootful Quadlet 的系统管理员配置目录。
3. 创建 .kube 文件
创建:
vim /etc/containers/systemd/uptime-kuma.kube
写入:
[Unit]
Description=Uptime Kuma Podman Pod
[Kube]
Yaml=/opt/data/uptime-kuma/uptime-kuma.yaml
[Install]
WantedBy=multi-user.target
这里最重要的是:
[Kube]
Yaml=/opt/data/uptime-kuma/uptime-kuma.yaml
它告诉 Quadlet 使用哪个 Kubernetes YAML 文件。
而:
[Install]
WantedBy=multi-user.target
表示该服务加入系统正常运行目标,从而实现系统启动时自动启动。
Podman 官方文档也明确给出了 .kube 配合 [Install] WantedBy=multi-user.target 实现开机启动的方式。
4. 重新加载 systemd
创建 Quadlet 文件后执行:
systemctl daemon-reload
Quadlet 会通过 systemd generator 根据:
/etc/containers/systemd/uptime-kuma.kube
生成对应的:
uptime-kuma.service
可以检查:
systemctl cat uptime-kuma.service
如果看到类似:
# Automatically generated by /usr/lib/systemd/system-generators/podman-system-generator
说明 Quadlet 已经正常识别。
也可以:
systemctl status uptime-kuma.service
5. 启动服务
直接启动:
systemctl start uptime-kuma.service
检查:
systemctl status uptime-kuma.service
正常情况下应该看到:
Active: active (running)
同时检查 Podman:
podman ps
应该可以看到 Uptime Kuma 容器正在运行。
6. 为什么不能执行 systemctl enable
这里有一个和普通 systemd 服务不同的地方。
不要执行:
systemctl enable uptime-kuma.service
Quadlet 生成的 systemd 服务属于 generated/transient unit,不能按照普通 .service 文件的方式执行 systemctl enable。
如果执行:
systemctl enable uptime-kuma.service
可能看到:
Failed to enable unit:
Unit /run/systemd/generator/uptime-kuma.service
is transient or generated
这不是 Quadlet 配置失败。
Quadlet 会在生成 systemd unit 时,根据 .kube 文件里的:
[Install]
WantedBy=multi-user.target
自动建立对应的启动关系。
这是 Podman Quadlet 与普通 systemd unit 的一个重要区别。
7. 验证开机自动启动
可以查看生成的服务:
systemctl cat uptime-kuma.service
确认存在:
[Install]
WantedBy=multi-user.target
然后可以重启服务器进行实际验证:
reboot
服务器重新启动后:
systemctl status uptime-kuma.service
以及:
podman ps
如果 Uptime Kuma 已经自动运行,就说明配置完成。
8. 日常管理
以后不需要再手动执行:
podman kube play uptime-kuma.yaml
直接使用 systemd:
启动:
systemctl start uptime-kuma.service
停止:
systemctl stop uptime-kuma.service
重启:
systemctl restart uptime-kuma.service
查看状态:
systemctl status uptime-kuma.service
查看日志:
journalctl -u uptime-kuma.service
实时查看日志:
journalctl -fu uptime-kuma.service
9. Quadlet 的工作原理
整个启动流程实际上是:
服务器开机
│
▼
systemd
│
▼
podman-system-generator
│
▼
/etc/containers/systemd/uptime-kuma.kube
│
▼
uptime-kuma.service
│
▼
podman kube play
│
▼
Uptime Kuma Pod
│
▼
Uptime Kuma Container
因此,Kubernetes YAML 负责描述容器,Quadlet 负责把它交给 systemd 管理。
Podman 官方文档中,.kube 文件就是用于通过 podman kube play 将 Kubernetes YAML 作为 systemd 服务运行的 Quadlet 类型。
10. 最终目录结构
最终可以保持这样的结构:
/opt/data/uptime-kuma/
└── uptime-kuma.yaml
/opt/data/uptime-kuma/data
└── Uptime Kuma 数据
/etc/containers/systemd/
└── uptime-kuma.kube
其中:
uptime-kuma.yaml
负责定义 Pod 和容器。
uptime-kuma.kube
负责告诉 systemd 如何使用这个 YAML。
/opt/data/uptime-kuma/data
负责保存 Uptime Kuma 的持久化数据。