Rocky Linux 10 강좌 / Quadlet으로 컨테이너 자동 시작·재시작 관리

Rocky Linux 10에서 Podman 컨테이너를 서비스로 운영하려면 Quadlet 파일에 실행 조건을 선언하고 systemd가 시작·중지·재시작을 관리하게 할 수 있습니다. 일반 사용자 컨테이너의 부팅 자동 시작에는 Quadlet의 시작 대상과 로그인하지 않아도 사용자 관리자를 유지하는 linger 설정을 함께 확인해야 합니다.

Quadlet과 사용자 서비스의 관계

Quadlet은 이미지·포트·볼륨 같은 컨테이너 조건을 파일로 기술하는 Podman 기능입니다. systemd의 생성기(generator)가 이 파일을 읽어 일반 서비스 파일을 만들고, 이후에는 systemctl로 관리합니다. 긴 podman run 명령을 기록하는 것에서 나아가 서비스의 재시작 정책과 시작 대상을 함께 관리할 수 있습니다.

이번 실습은 Rocky Linux 10.2, Podman 5.8.2, systemd 257, 프로세스 자원 관리를 위한 cgroups v2와 SELinux Enforcing 환경의 일반 사용자 lfstudent에서 진행합니다. rootless Podman 실습에서 확인한 공식 Nginx 이미지와 로컬 자료를 사용하며, 포트는 127.0.0.1:18028에만 연결합니다. 이 강좌의 Quadlet은 사용자 서비스이므로 sudo systemctl로 시스템 서비스를 관리하는 명령과 구분해야 합니다.

podman version
podman info --format '{{.Host.Security.Rootless}}'
podman info --format '{{.Host.CgroupsVersion}}'
systemctl --user list-unit-files
podman ps -a
ss -lnt 'sport = :18028'
loginctl show-user "$(id -un)" -p Linger

rootless 값은 true, cgroups는 v2여야 합니다. 같은 이름의 기존 서비스·컨테이너·자료가 있으면 새 설정으로 덮어쓰지 말고 먼저 확인하세요. 이 VM의 기존 linger는 no였고, 실습을 위해 해당 사용자만 yes로 바꿨다가 마지막에 복원합니다.

지원 옵션은 설치한 버전에 맞게 확인합니다. Podman 5.8 계열 Quadlet 문서는 사용자 검색 경로, 생성 방식과 각 설정의 대응 관계를 설명합니다. 최신 문서의 새 옵션이 이전 배포판 패키지에서도 지원된다고 가정하지 않습니다.

이 계정에서 관리 중인 사용자 서비스를 확인한 뒤 해당 사용자에만 linger를 설정합니다. 이는 컨테이너 하나의 옵션이 아니라 그 계정의 사용자 관리자 수명에 영향을 줍니다. 기존에 yes였던 계정은 실습 종료 시 임의로 no로 바꾸지 않습니다.

sudo loginctl enable-linger "$(id -un)"
loginctl show-user "$(id -un)" -p Linger

loginctl 매뉴얼은 linger가 부팅 때 사용자 관리자를 시작하고 로그아웃 뒤에도 유지하는 기능이라고 설명합니다.

문서 경로와 전체 Quadlet 파일 준비

다음은 일반 사용자 셸에서 실행합니다. 자료 디렉터리 lf-course28은 새로 만들며, 27강에서 기록한 이미지 참조를 재사용합니다. 27강을 수행하지 않았다면 공식 이미지를 내려받고 출처·digest를 확인해 같은 참조 파일을 먼저 준비해야 합니다.

LAB28="$HOME/lf-course28"
test ! -e "$LAB28" || { printf '기존 실습 경로를 확인하세요.\n' >&2; exit 1; }
mkdir -m 0755 "$LAB28"
mkdir -m 0755 "$LAB28/site"
printf 'LF28 Quadlet service works\n' > "$LAB28/site/index.html"
chmod 0644 "$LAB28/site/index.html"
mkdir -p "$HOME/.config/containers/systemd"
cat "$HOME/lf-course27/image.ref"

~/.config/containers/systemd/lf-course28.container에 다음 전체 내용을 저장합니다. 여기의 홈 경로는 실제 실습 사용자의 경로입니다. 다른 계정으로 실행한다면 Volume의 원본 경로를 해당 계정에 맞춰 수정하고 이미지 참조도 자신이 확인한 값으로 지정합니다.

test ! -e "$HOME/.config/containers/systemd/lf-course28.container" || { printf '기존 Quadlet 파일을 확인하세요.\n' >&2; exit 1; }
cat > "$HOME/.config/containers/systemd/lf-course28.container" <<'EOF'
[Unit]
Description=Course28 rootless web service
[Container]
Image=docker.io/library/nginx@sha256:583b7f2fce1cdb8da5ad5c39ebd3c33b98b87d493190e548bdee1fa8c619c311
ContainerName=lf-course28-web
Label=lf.course=28
PublishPort=127.0.0.1:18028:80
Volume=/home/lfstudent/lf-course28/site:/usr/share/nginx/html:ro,Z
Pull=never
[Service]
Restart=on-failure
RestartSec=2
TimeoutStartSec=90
[Install]
WantedBy=default.target
EOF
구역·설정 이번 서비스에서의 역할
[Container] 이미지·이름·포트·마운트 등 Podman 실행 조건입니다.
Pull=never 이미 확인해 저장한 로컬 이미지를 사용합니다. 캐시에 없으면 시작에 실패하므로 미리 준비합니다.
Volume=…:ro,Z 새 전용 문서를 읽기 전용으로 제공하고 컨테이너에 맞는 SELinux 문맥을 적용합니다.
Restart=on-failure 서비스가 비정상 종료했을 때 다시 시작합니다. 명시적인 stop과는 구분됩니다.
WantedBy=default.target 사용자 관리자의 기본 시작 대상에 서비스를 연결합니다.

이미지의 임시 태그를 자동 추적하는 구성이 아니므로 업데이트는 새 digest를 검토하고 파일을 변경한 뒤 다시 검증하는 과정입니다. 마운트는 새 전용 경로만 사용하며 홈 전체를 다시 표시하지 않습니다.

서비스 생성·실행과 실제 HTTP 확인

systemctl --user daemon-reload
systemctl --user cat lf-course28.service
systemctl --user start lf-course28.service
systemctl --user show lf-course28.service -p ActiveState -p SubState -p FragmentPath -p UnitFileState -p NRestarts
curl --retry 3 --retry-all-errors --retry-delay 1 --max-time 5 -fsS http://127.0.0.1:18028/
journalctl --user -u lf-course28.service -b -n 30 --no-pager

실제로 생성된 서비스는 /run/user/1000/systemd/generator/lf-course28.service에 있었고 상태는 generated였습니다. 생성 파일에는 컨테이너 실행 명령과 중지·정리 명령이 들어 있었습니다. 이 파일을 직접 편집하지 말고 원본 .container 파일을 수정한 뒤 daemon-reload로 다시 생성합니다.

이번 서비스는 active/running이었고 LF28 Quadlet service works를 반환했습니다. 생성된 서비스의 기본 Type은 notify이고 컨테이너 감시 프로그램 conmon이 시작을 알리지만, 이것만으로 웹 애플리케이션이 올바르게 응답한다고 판단하지 않습니다. 실제 HTTP와 기대 본문을 별도로 확인합니다. 시작 직후 연결 재설정이 한 번 관찰되어 제한된 재시도를 사용했습니다.

생성 서비스에 일반 파일처럼 systemctl --user enable lf-course28.service를 적용하는 방식은 사용하지 않습니다. Quadlet 생성기가 원본 파일의 [Install] 설정을 처리합니다. 부팅 때 사용자 관리자 자체가 시작되는 조건은 별도로 확인해야 합니다.

비정상 종료와 명시적인 중지를 비교

시험은 이 강좌에서 만든 컨테이너 하나만 대상으로 합니다. 시작 전 컨테이너 ID와 재시작 횟수를 기록하고, 강제 종료 신호인 SIGKILL로 비정상 종료를 재현합니다. 운영 서비스에 같은 명령을 그대로 적용하지 않습니다.

podman inspect lf-course28-web --format '{{.Id}}'
systemctl --user show lf-course28.service -p NRestarts
podman kill --signal KILL lf-course28-web
systemctl --user show lf-course28.service -p ActiveState -p SubState -p NRestarts
podman inspect lf-course28-web --format '{{.Id}}'
curl --retry 3 --retry-all-errors --retry-delay 1 --max-time 5 -fsS http://127.0.0.1:18028/

실습에서 이전 ID 01951ad831a1…는 새 ID 610769498aeb…로 바뀌었고, NRestarts=1과 같은 HTTP 본문을 확인했습니다. 중지 직후에는 재시작 대기나 컨테이너 교체 중이라 조회가 실패할 수 있으므로 서비스 로그와 상태가 안정된 뒤의 결과를 함께 봅니다. 이 설정은 같은 컨테이너의 프로세스만 살리는 것이 아니라 생성된 실행 조건으로 새 컨테이너를 만들 수 있습니다.

systemctl --user stop lf-course28.service
systemctl --user is-active lf-course28.service
podman container exists lf-course28-web
systemctl --user start lf-course28.service

명시적으로 stop한 뒤에는 inactive였으며 컨테이너 존재 검사는 종료 코드 1이었습니다. 3초 뒤에도 자동으로 다시 만들어지지 않았고, 직접 start한 뒤 다시 응답했습니다. 서비스 운영 중에는 Podman에 별도의 재시작 정책을 중복 적용하기보다 systemd의 정책과 상태를 기준으로 관리합니다. systemd.service 문서는 Restart 조건과 수동 중지의 동작을 설명합니다.

로그아웃 후 유지와 재부팅 자동 시작 검증

서비스를 시작한 뒤 SSH를 종료하고, 다시 접속했을 때 start를 다시 실행하지 않은 상태에서 확인합니다. 이 실습에서는 이전 시작 시각 02:30:56을 유지한 채 02:32:48에도 active와 같은 HTTP 본문을 확인했습니다. 새 로그인 자체가 서비스를 다시 시작한 결과인지 시작 시각을 함께 봅니다.

systemctl --user show lf-course28.service -p ActiveState -p ActiveEnterTimestamp -p ActiveEnterTimestampMonotonic
loginctl show-user "$(id -un)" -p Linger
curl -fsS http://127.0.0.1:18028/
cat /proc/sys/kernel/random/boot_id
sha256sum "$HOME/lf-course28/site/index.html"
sudo systemctl reboot

재부팅하면 SSH 연결이 끊깁니다. 콘솔 접근이 가능한 전용 실습 VM에서만 수행하고, 다시 접속한 뒤 서비스를 수동 시작하기 전에 새 부팅 ID와 상태를 확인합니다. 다음 명령은 첫 로그인보다 먼저 서비스가 시작됐는지도 비교하기 위한 조회입니다.

cat /proc/sys/kernel/random/boot_id
systemctl --user show lf-course28.service -p ActiveState -p SubState -p ActiveEnterTimestampMonotonic -p UnitFileState
loginctl show-session "$XDG_SESSION_ID" -p TimestampMonotonic
curl --retry 3 --retry-all-errors --retry-delay 1 --max-time 5 -fsS http://127.0.0.1:18028/
sha256sum "$HOME/lf-course28/site/index.html"
journalctl --user -u lf-course28.service -b -n 30 --no-pager

실제 검증에서 부팅 ID가 바뀌었고 서비스는 active/running이었습니다. 서비스의 부팅 후 경과를 비교하는 단조 증가 시각은 319329250마이크로초, 첫 SSH 세션 시작은 361617018마이크로초였습니다. 같은 부팅 안에서 비교하면 서비스가 로그인보다 약 42초 먼저 시작됐음을 알 수 있습니다. 문서와 Quadlet 파일의 해시도 같았으며 HTTP 본문은 유지됐습니다.

이번 VM의 재부팅은 커널 구간 약 4분 57초를 포함해 총 약 5분 22초가 걸렸고, cbc-aes-aesni 자체 검사에서 rc=-110 경고가 남았습니다. 부팅 지연 중 첫 SSH 시도는 실패했으며, 콘솔 응답 확인 뒤 접속이 준비된 상태에서 검증했습니다. Quadlet 자동 시작은 확인했지만 이 결과를 암호화 자체 검사까지 정상 통과한 환경이라고 해석하지 않습니다. 부팅 지연 원인을 서비스 자동 시작 설정과 섞어 판단하지 마세요.

생성되지 않는 서비스와 실행 실패 구분

Unit not found라면 컨테이너 실행 이전에 생성이 실패했을 수 있습니다. 파일 이름의 .container 확장자, 사용자 검색 경로, 구역 이름과 설치 버전에서 지원하는 키를 먼저 확인합니다. 생성 파일이 있는데 실행에 실패한다면 이미지 캐시·마운트 원본·포트·애플리케이션 로그를 확인합니다.

QUADLET_UNIT_DIRS="$HOME/.config/containers/systemd" /usr/lib/systemd/system-generators/podman-system-generator --user --dryrun
systemctl --user cat lf-course28.service
systemctl --user status lf-course28.service --no-pager
journalctl --user -u lf-course28.service -b -n 40 --no-pager
podman ps -a

실습에서는 실제 검색 경로 밖의 별도 시험 폴더에 잘못된 NotARealKey를 넣고 생성기 dry-run만 수행했습니다. 생성기는 종료 코드 1과 unsupported key를 반환했고 실행 명령을 만들지 않았습니다. 정상 원본으로 범위를 제한한 dry-run은 종료 코드 0이었으며 실행 중 서비스는 계속 active였습니다. 운영 파일을 일부러 손상시키지 않고도 별도 경로에서 구문을 진단할 수 있습니다.

원본 설정을 바꾼 뒤 daemon-reload는 서비스 정의를 다시 읽는 작업입니다. 이미 실행 중인 컨테이너를 새 설정으로 다시 만들려면 필요한 중단 시간을 고려해 systemctl --user restart lf-course28.service를 수행하고 상태·실제 응답·자료를 다시 확인해야 합니다. 잘못된 수정은 보관한 원본으로 되돌린 뒤 같은 순서로 재검증합니다.

자동 시작 해제와 실습 정리

실습을 제거할 때는 먼저 사용자 서비스를 중지합니다. 원본 Quadlet을 검색 경로 밖으로 옮긴 뒤 daemon-reload하면 생성 파일과 시작 대상 연결도 정리됩니다. 운영을 계속할 서비스라면 이 정리 명령을 실행하지 않습니다.

systemctl --user stop lf-course28.service
mv "$HOME/.config/containers/systemd/lf-course28.container" "$HOME/lf-course28/lf-course28.container.saved"
systemctl --user daemon-reload
systemctl --user show lf-course28.service -p LoadState
podman container exists lf-course28-web
restorecon -RFv "$HOME/lf-course28/site"
ss -lnt 'sport = :18028' 

실제 정리 결과는 LoadState=not-found, 컨테이너 존재 검사 종료 코드 1, 빈 18028번 리스너 목록이었습니다. 문서는 남겨 두고, 사용을 끝낸 전용 경로의 SELinux 문맥을 일반 홈 파일 문맥으로 돌렸습니다. 실습 전 없었던 빈 설정 디렉터리만 제거했으며 원래 사용자 설정은 유지했습니다.

sudo loginctl disable-linger "$(id -un)"
loginctl show-user "$(id -un)" -p Linger

위 linger 해제는 원래 no였고 다른 장기 실행 사용자 서비스가 필요하지 않은 이번 실습 계정에만 적용합니다. 실제 종료 후에는 no로 복원됐고 기존 SSH·방화벽·Nginx·hosts·fstab·사용자 ID 매핑과 SELinux 로컬 설정도 보존됐습니다. 서비스 정의와 자료는 전용 기록 디렉터리에 남겨 복원·검토에 사용할 수 있습니다.