콘텐츠로 이동






04.podman기반의 Harbor 설치가이드

Docker 대신 Podman 사용 시 설정

Info

중요: Harbor의 공식 Docker Compose 설치 전제는 Docker Engine과 Docker Compose다. Podman은 Docker API 및 Compose 호환 계층으로 실행을 시도할 수 있지만, 공식 지원 배포 방식으로 간주하지 않는다. 운영 적용 전에는 반드시 별도 환경에서 설치, HTTPS, Trivy, Push/Pull, 백업/복구, 업그레이드를 검증한다. Podman 기반 구성은 rootful Podman + Podman API socket + Docker Compose CLI 조합을 우선 검토한다.

패키지 설치

  1. Rocky Linux/RHEL 계열 예시다. 
    $> sudo dnf install -y \
  podman \
  podman-docker \
  podman-compose
  2. podman-docker는 docker 명령을 Podman 호환 명령으로 제공한다.

Rootful Podman API Socket 활성화

$> sudo systemctl enable --now podman.socket
$> sudo systemctl status podman.socket
$> sudo podman info | grep -i -A2 remotesocket

  1. 일반적인 rootful Podman socket 경로는 다음과 같다. 

    /run/podman/podman.sock

  2. Docker API 클라이언트가 Podman socket을 사용하도록 설정한다. 

    $> export DOCKER_HOST="unix:///run/podman/podman.sock"
$> sudo --preserve-env=DOCKER_HOST docker version

  3. 영구 적용 예시: 

    $> echo 'export DOCKER_HOST=unix:///run/podman/podman.sock' | \
  sudo tee /etc/profile.d/harbor-podman.sh

Compose 방식 선택

  1. 아래 방식은 혼용하지 않는다.

    방식 명령 특징
    Podman Compose podman-compose up -d Podman provider 기반
    Docker Compose + Podman Socket docker compose up -d Docker API 호환 socket 사용

  2. Harbor installer가 사용하는 Compose 명령과 일상 운영 명령은 동일하게 유지한다.
    예를 들어 podman-compose up -d로 시작한 컨테이너를 docker compose down으로 종료하지 않는다.

Podman 기반 운영 명령 예시

  1. Docker Compose CLI가 Podman socket을 사용하도록 구성한 경우의 예시다. 
    $> export DOCKER_HOST="unix:///run/podman/podman.sock"
$> cd /opt/harbor/harbor
$> sudo --preserve-env=DOCKER_HOST docker compose ps
$> sudo --preserve-env=DOCKER_HOST docker compose logs -f trivy-adapter
$> sudo --preserve-env=DOCKER_HOST docker compose down -v
$> sudo --preserve-env=DOCKER_HOST docker compose up -d

Podman 사용 시 주의사항

  • Harbor 버전 업그레이드 전, 동일한 Podman 및 Compose 버전의 스테이징 환경에서 검증한다.
  • docker-compose, docker compose, podman-compose 명령을 혼용하지 않는다.
  • sudo 실행 시 DOCKER_HOST가 사라질 수 있으므로 sudo --preserve-env=DOCKER_HOST를 사용한다.
  • SELinux 오류는 permissive 전환이 아니라 볼륨 경로 레이블 수정으로 해결한다.
  • Harbor installer 또는 특정 Compose 기능이 Podman API와 호환되지 않을 수 있다.
  • 운영 안정성과 장애 대응이 중요하면 Docker Engine 기반 설치를 사용한다.



작성일: 2026년 8월 11일 ,  마지막 업데이트: 2026년 8월 11일