[Docker] 파이썬 코드로 도커 제어하기: Docker SDK 활용 기초

일반적으로 도커를 사용할 때는 터미널에서 docker run, docker ps와 같은 CLI 명령어를 주로 사용한다.

하지만 복잡한 MSA(Microservices Architecture) 환경을 구축하거나, 자체적인 인프라 관리 도구를 개발해야 할 때는 쉘 스크립트만으로 제어하는 데 한계가 있다.

이때 유용한 것이 프로그래밍 언어를 통한 도커 제어다.

Docker는 Python, Go, Java 등 다양한 언어에 대한 SDK를 제공하며, 이를 통해 컨테이너의 생성, 실행, 종료 등을 프로그래밍 로직 안에서 처리할 수 있다.

 

이번에는 Python의 docker 라이브러리를 사용하여 Nginx 컨테이너를 생성하고 실행해보자.

1. 동작 원리 및 아키텍처

먼저 파이썬 코드가 어떻게 도커 데몬을 제어하는지 이해할 필요가 있다.

핵심은 Docker Socket이다.

일반적인 CLI 명령어도 실제로는 도커 데몬에게 API 요청을 보내는 클라이언트일 뿐이다.

Python 스크립트 역시 Docker SDK를 통해 이 데몬과 통신한다.

리눅스 환경에서는 주로 유닉스 소켓(unix://var/run/docker.sock)을 통해 이 통신이 이루어진다.

 

2. 환경 설정 (Prerequisites)

Python으로 도커를 제어하기 위해서는 먼저 Python 환경과 Docker SDK 라이브러리가 설치되어 있어야 한다.

우분투 환경을 기준으로 다음과 같이 진행한다.

2-1. pip 설치

Python 패키지 관리자인 pip가 없다면 먼저 설치한다.

apt -y install python3-pip

2-2. Docker SDK 설치

Python에서 도커 엔진과 통신하기 위한 공식 라이브러리인 docker를 설치한다.

pip3 install docker

 

이 라이브러리는 Docker Engine API를 래핑(Wrapping)하고 있어, 복잡한 HTTP 요청을 직접 날리지 않고도 직관적인 메소드 호출만으로 도커를 제어할 수 있게 해준다.

3. Python 스크립트 구현

이제 nano 편집기를 열어서 실제로 Nginx 컨테이너를 실행시키는 Python 스크립트를 작성한다.

파일명: nginx_run.py로 생성

import docker

# 1. Docker Client 생성 (로컬 도커 데몬과 연결)
client = docker.DockerClient(base_url='unix://var/run/docker.sock')

# 2. 컨테이너 실행
container = client.containers.run('nginx', detach=True, ports={'3010/tcp':3010})

# 3. 결과 출력
print("Created container is : {}, {}".format(container.name, container.id))

코드 분석

• base_url='unix://var/run/docker.sock' : 로컬 머신에 있는 도커 데몬을 제어하기 위해 유닉스 소켓 경로를 지정한다. 원격지의 도커를 제어하려면 이곳에 tcp://IP:PORT 형태의 주소를 입력할 수도 있다.
• client.containers.run(...) : CLI의 docker run 명령어와 정확히 매칭되는 함수다.
  • detach=True : docker run -d와 같다. 컨테이너를 백그라운드에서 실행한다.
  • ports={'3010/tcp': 3010} : docker run -p 3010:3010과 같다. 딕셔너리 형태로 포트 매핑을 정의한다.

4. 실행 및 검증

4-1. 스크립트 실행

작성한 스크립트에 실행 권한을 부여하고 실행한다.

chmod +x nginx_run.py
python3 nginx_run.py
Created container is : funny_benz, f3cb4d6263e6cbb5579adb0b7445ca0d865350e8db59ad4e3d2bd9b3eeb7431e

 

스크립트가 정상적으로 수행되면 생성된 컨테이너의 이름(Random name)과 ID가 출력된다. 

4-2. Docker 프로세스 확인

실제로 컨테이너가 떠 있는지 docker ps 명령어로 확인한다.

CONTAINER ID    IMAGE    COMMAND                   CREATED           STATUS           PORTS                               NAMES
f3cb4d6263e6    nginx    "/docker-entrypoint.…"    15 seconds ago    Up 14 seconds    80/tcp, 0.0.0.0:3010->3010/tcp      funny_benz

 

출력된 컨테이너 ID(f3cb4d6263e6)와 이름(funny_benz)이 Python 스크립트의 출력값과 일치하는 것을 볼 수 있다. 또한 포트 포워딩(0.0.0.0:3010->3010/tcp)도 코드로 설정한 대로 적용되었다.

 

5. 왜 CLI 대신 SDK인가?

단순히 터미널에서 docker run 한 줄이면 끝날 작업을 굳이 Python 스크립트로 구현하는 이유가 있을까?

그 답은 자동화(Automation)와 확장성(Scalability)에 있다.

텍스트에서 객체(Object)로의 전환: 자동화

CLI 명령어의 결과값은 '사람이 읽기 위한 문자열'이다.

따라서 쉘 스크립트로 자동화 도구를 만들려면, 출력된 텍스트에서 필요한 정보(IP 주소, 컨테이너 ID 등)를 잘라내고 가공하는 '텍스트 파싱' 과정이 필요하다.

 

반면, Python SDK는 결과값을 '컴퓨터가 이해하는 객체(Object)'로 반환한다.

 

• 안정성: container.id, container.status와 같이 객체의 속성에 직접 접근하므로, 출력 형식이 바뀌어도 코드는 깨지지 않는다.
• 논리 제어: "CPU 사용량이 80% 이상이면(if), 특정 컨테이너를 재시작하라(method)"와 같은 복잡한 조건부 로직을 Python의 문법으로 손쉽게 구현할 수 있다. 운영 자동화가 더 수월해지는 것이다.

 

if cpu_usage > 80:
    oldest_container.stop()

 

서비스로의 통합: 확장성

CLI는 관리자가 터미널 앞에 앉아있을 때 유용하지만, 대규모 시스템을 구축하기엔 한계가 명확하다.

SDK를 사용하면 도커를 외부 시스템과 유기적으로 결합할 수 있다.

• 웹 서비스 통합: Django나 Flask로 만든 웹 서버에서 사용자 요청에 따라 즉시 컨테이너를 생성해주는 PaaS(Platform as a Service)를 구축할 수 있다.
• 인프라 확장: 수천 개의 컨테이너를 관리해야 할 때, 쉘 스크립트는 한계에 부딪히지만 SDK는 멀티스레딩이나 비동기 처리를 통해 규모가 큰 인프라를 효율적으로 제어할 수 있다.

결국 Docker SDK를 익힌다는 것은 단순히 명령어를 코드로 옮기는 것을 넘어, '도커를 사용하는 운영자'에서 '도커를 제어하는 시스템 개발자'로 관점을 확장한다는 의미가 있다.