nspawn 3.0, 호스트에 Docker API 제공해 systemd-nspawn 머신 관리
nspawn 3.0은 호스트 Unix 소켓에 Docker Engine API를 제공해 Docker CLI와 GitLab Runner의 Docker executor가 systemd-nspawn 머신을 관리하도록 합니다. API는 Docker 작업의 일부만 지원하며, 호스트에서 `org.nspawn.manage` 권한을 얻은 사용자는 root에 준하는 제어 권한을 갖습니다.
Eduard Tolosa는 2026년 11월 8일 Nspawn Org 블로그에서 nspawn 3.0의 호스트용 Docker Engine API를 소개했습니다. 호스트의 /run/nspawn/api.sock에 Docker CLI나 GitLab Runner의 Docker executor를 연결하면 Docker API를 사용하는 도구로 systemd-nspawn 머신을 실행하고 관리할 수 있습니다. nspawn 자체 관리에는 계속 nspawn 명령줄을 쓰며, API 서버는 명령줄과 마찬가지로 D-Bus 서비스의 org.nspawn 메서드를 호출합니다.
패키지는 nspawn-api.socket을 기본 비활성 상태로 설치합니다. 관리자가 소켓을 활성화하면 첫 연결 때 nspawn-api.service가 시작됩니다. Docker CLI는 DOCKER_HOST에 unix:///run/nspawn/api.sock을 지정해 연결합니다. GitLab Runner도 executor를 docker로 설정하고 Docker 설정의 host에 같은 경로를 넣으면 작업을 nspawn 머신에서 실행합니다.
컨테이너 생성 요청의 Docker 설정은 nspawn 머신 옵션으로 바뀝니다. nspawn에서 쓰이지 않는 항목은 응답의 Warnings에 표시하고, 컨테이너 동작을 바꿀 설정을 처리할 수 없으면 HTTP 400으로 요청을 거부합니다. API는 컨테이너 실행·중지·재시작·일시 정지 등을 지원합니다. attach는 클라이언트 입력을 프로그램에 전달하고 출력을 그대로 돌려줘 docker run -i, docker run -it, docker start -ai 같은 사용법을 받칩니다. exec에서는 터미널 사용 여부와 표준 출력·오류의 분리, 입력, 환경 변수, 작업 디렉터리, 실행 사용자를 지정할 수 있습니다.
docker cp는 실행 중이거나 멈춘 머신과 양방향으로 파일을 주고받으며 파일의 소유자와 권한을 보존합니다. 다만 머신이 멈추면 볼륨이 마운트되지 않으므로 볼륨 경로를 포함하는 복사는 머신을 다시 시작할 때까지 거부됩니다. 이미지 pull·삭제와 볼륨·네트워크의 생성·조회·정리도 API로 처리할 수 있습니다. 컨테이너를 네트워크에 연결하거나 해제할 때 별칭과 고정 주소를 지정할 수도 있습니다. API는 클라이언트가 요청하는 1.24부터 1.51까지의 버전 형식에 응답합니다.
호스트 소켓에 연결할 수 있는 사용자와 실제 작업 권한은 다릅니다. 모든 사용자가 소켓에 연결할 수 있지만, D-Bus 서비스의 polkit 규칙이 작업을 결정합니다. 조회와 대기에는 org.nspawn.inspect, 로그와 변경에는 org.nspawn.manage 권한이 필요합니다. 소켓은 대화형 인증 승인을 요청하지 않으므로 root가 아닌 사용자는 별도의 polkit 규칙이 있어야 합니다. Tolosa는 org.nspawn.manage 권한이 호스트 root에 준하는 권한이라고 설명합니다. 머신에서 명령을 root로 실행하고 호스트의 경로를 마운트할 수 있기 때문입니다.
머신 안에 마운트하는 API 소켓의 권한도 3.0에서 바뀌었습니다. 2.0에서는 Traefik이나 Dozzle 같은 도구가 머신을 찾을 수 있도록 소켓을 읽기 전용으로 제공했습니다. 3.0에서는 호스트의 /var/run/docker.sock, /run/docker.sock 또는 /run/nspawn/api.sock을 머신 안에 쓰기 가능하게 마운트하면 컨테이너 생성·실행·명령 실행·삭제, 이미지 pull·삭제, 볼륨과 네트워크 생성을 요청할 수 있습니다. :ro로 마운트하면 조회와 로그 확인, 컨테이너 종료 요청은 허용하지만 그 밖의 변경 요청은 HTTP 403으로 거부합니다.
머신 안에서는 root만 소켓에 연결할 수 있습니다. 연결한 클라이언트는 특정 머신에 한정되지 않고 전체 머신과 --secret 값을 제외한 환경 변수도 볼 수 있습니다. 따라서 쓰기 가능한 소켓 마운트는 해당 머신만 제어하는 권한에 그치지 않고 nspawn 서비스 전반의 관리 작업으로 이어집니다.
Docker 호환 API가 지원하는 작업은 일부입니다. 이미지 빌드·load·import·tag·push·commit, 컨테이너 이름 변경·export, swarm과 플러그인 작업은 HTTP 501을 반환합니다. 이미지 빌드에는 Docker 소켓 대신 nspawn build 명령을 사용합니다. 실험적이며 검증되지 않은 mstack 백엔드도 Docker API를 제공하지 않습니다.