도커 API
1. 개요
1. 개요
도커 API는 도커 엔진과 상호작용하기 위한 프로그래밍 인터페이스이다. 이 API는 도커 데몬을 원격으로 제어하고, 도커 컨테이너, 이미지, 네트워크, 볼륨 등의 생명주기 관리를 가능하게 하는 핵심 도구 역할을 한다.
이 API는 REST 아키텍처 스타일을 따르며, HTTP 요청과 JSON 형식의 응답을 기본 통신 방식으로 사용한다. 사용자는 HTTP 메서드를 통해 특정 엔드포인트에 요청을 보내고, 도커 데몬은 해당 작업을 수행한 결과를 JSON으로 반환한다.
도커 API를 이용하면 도커 클라이언트를 거치지 않고도 애플리케이션이나 스크립트에서 직접 도커 엔진의 모든 기능을 자동화하고 통제할 수 있다. 이는 지속적 통합 및 지속적 배포 파이프라인 구축이나 대규모 컨테이너 오케스트레이션 시스템 개발에 필수적인 기반을 제공한다.
2. 기본 개념
2. 기본 개념
2.1. Docker 데몬
2.1. Docker 데몬
도커 데몬은 도커 엔진의 핵심 구성 요소로, 호스트 시스템에서 백그라운드 서비스로 실행된다. 이 데몬은 컨테이너의 생성, 시작, 중지, 삭제와 같은 모든 작업을 실제로 처리하는 책임을 진다. 또한 이미지 풀, 빌드, 네트워크 및 볼륨 관리와 같은 도커 엔진의 핵심 기능을 수행한다.
도커 데몬은 기본적으로 유닉스 도메인 소켓(Unix domain socket)을 통해 로컬에서만 통신하도록 설정되어 있다. 그러나 보안 설정을 통해 TCP 소켓을 열어 원격에서 접근할 수 있도록 구성할 수 있으며, 이때 도커 API가 활성화된다. 이 API는 REST 기반의 HTTP 인터페이스를 제공하여, 도커 클라이언트나 다른 외부 도구 및 스크립트가 데몬에 명령을 전달하고 결과를 받을 수 있게 한다.
따라서 도커 데몬은 도커 시스템의 실제 실행 엔진이자, 도커 API를 통해 외부와 상호작용하는 서버 역할을 한다. 도커 클라이언트는 사용자의 명령을 받아 이 API를 호출하고, 데몬은 해당 요청을 실행하여 결과를 JSON 형식으로 반환하는 구조이다.
2.2. Docker 클라이언트
2.2. Docker 클라이언트
도커 클라이언트는 사용자나 애플리케이션이 도커 엔진과 상호작용하기 위한 주요 인터페이스이다. 이 클라이언트는 명령줄 인터페이스 도구인 docker 명령어를 실행하는 프로그램이다. 사용자가 터미널에서 docker run, docker build 등의 명령을 입력하면, 도커 클라이언트는 이 명령을 해석하여 적절한 API 요청으로 변환한 후 도커 데몬에게 전달한다.
도커 클라이언트는 기본적으로 같은 시스템의 도커 데몬과 유닉스 소켓을 통해 통신하도록 설정되어 있다. 그러나 환경 변수나 명령어 옵션을 통해 원격에 위치한 도커 데몬의 REST API 엔드포인트를 지정할 수 있다. 이를 통해 사용자는 로컬 머신의 클라이언트를 사용하여 네트워크 상의 다른 서버에 설치된 도커 엔진을 원격으로 제어할 수 있다. 이 기능은 분산 시스템 환경이나 클라우드 서버 관리에 유용하게 활용된다.
도커 클라이언트의 핵심 역할은 사용자 친화적인 명령어를 HTTP 기반의 API 호출로 변환하는 것이다. 예를 들어, docker ps 명령은 내부적으로 데몬의 /containers/json API 엔드포인트에 GET 요청을 보내고, 데몬으로부터 받은 JSON 형식의 응답을 가독성 좋은 테이블 형태로 터미널에 출력한다. 따라서 모든 도커 작업은 궁극적으로 도커 데몬이 제공하는 REST API를 통해 이루어진다고 볼 수 있다.
2.3. REST API 엔드포인트
2.3. REST API 엔드포인트
도커 API의 핵심은 도커 데몬이 제공하는 REST 기반의 HTTP 엔드포인트이다. 이 엔드포인트들은 도커 클라이언트나 다른 외부 도구가 도커 엔진과 통신하여 컨테이너와 이미지, 네트워크, 볼륨 등의 생명주기를 프로그래밍 방식으로 관리할 수 있게 해준다. 기본적으로 도커 데몬은 유닉스 도메인 소켓(/var/run/docker.sock)이나 TCP 포트를 통해 이 API 서비스를 제공한다.
API는 HTTP 메서드를 사용하여 자원을 조작한다. 주요 엔드포인트는 /containers, /images, /networks, /volumes 등 관리 대상별로 구성되어 있으며, 각 엔드포인트 아래에 생성, 조회, 수정, 삭제를 위한 세부 경로가 존재한다. 예를 들어, 새로운 컨테이너를 생성하려면 POST /containers/create 엔드포인트를 호출하고, 실행 중인 컨테이너 목록을 얻으려면 GET /containers/json을 호출한다.
모든 요청과 응답은 JSON 형식을 따른다. 클라이언트는 HTTP 요청의 본문에 JSON 데이터를 담아 보내고, 도커 데몬은 작업 결과나 요청된 정보를 JSON 형식으로 응답한다. 이를 통해 다양한 프로그래밍 언어와 도구에서 쉽게 통합할 수 있는 표준화된 인터페이스를 제공한다.
이 REST API는 도커 데몬에 대한 원격 제어를 가능하게 하는 근간이다. 도커 컴포즈나 쿠버네티스와 같은 오케스트레이션 도구들도 내부적으로 이 API를 사용하여 다수의 컨테이너를 관리한다. 또한, 사용자는 cURL 명령어나 파이썬, 고 (프로그래밍 언어) 등의 공식 SDK를 통해 직접 API를 호출하여 자동화 스크립트나 맞춤형 관리 도구를 개발할 수 있다.
3. API 주요 기능
3. API 주요 기능
3.1. 이미지 관리
3.1. 이미지 관리
도커 API의 이미지 관리 기능은 도커 이미지의 생명주기를 프로그래밍 방식으로 제어할 수 있게 한다. 이 기능을 통해 사용자는 원격 도커 데몬에 저장된 이미지 목록을 조회하거나, 새로운 이미지를 레지스트리에서 가져오고, 로컬에 저장된 이미지를 삭제하는 작업을 수행할 수 있다. 또한 이미지의 상세 정보를 확인하거나 태그를 지정하는 작업도 API 호출을 통해 자동화할 수 있다.
주요 엔드포인트로는 이미지 목록을 가져오는 GET /images/json, 특정 이미지를 풀(Pull)하는 POST /images/create, 그리고 이미지를 삭제하는 DELETE /images/{name} 등이 있다. 이미지를 빌드하는 POST /build 엔드포인트를 사용하면 Dockerfile과 컨텍스트를 전송하여 새로운 이미지를 생성할 수도 있다. 이러한 모든 작업은 표준 HTTP 요청과 JSON 형식의 응답으로 이루어진다.
이미지 관리 API는 지속적 통합 및 지속적 배포 파이프라인에서 중요한 역할을 한다. 예를 들어, 애플리케이션의 새 버전이 빌드되면 API를 호출하여 해당 이미지를 레지스트리에 푸시하고, 프로덕션 환경의 도커 데몬에게 최신 이미지를 풀하도록 지시할 수 있다. 이를 통해 컨테이너 오케스트레이션 시스템과 연동하거나 사용자 정의 관리 도구를 개발하는 데 필수적인 기반을 제공한다.
3.2. 컨테이너 관리
3.2. 컨테이너 관리
도커 API의 컨테이너 관리 기능은 도커 컨테이너의 전 생명주기를 프로그래밍 방식으로 제어할 수 있게 한다. 이는 도커 데몬에 HTTP 요청을 보내어 컨테이너를 생성, 시작, 중지, 삭제하고, 실행 중인 컨테이너의 상태를 모니터링하며, 내부 프로세스나 로그를 조회하는 등의 작업을 수행한다. REST 기반의 설계 덕분에 다양한 클라이언트 도구나 스크립트를 통해 자동화된 컨테이너 오케스트레이션이 가능해진다.
주요 엔드포인트는 /containers, /exec, /logs 등이 있으며, 각 요청에는 필요한 매개변수가 JSON 형식으로 포함된다. 예를 들어, 새로운 컨테이너를 생성할 때는 기존 도커 이미지의 이름과 컨테이너 설정을 지정하며, 실행 중인 컨테이너 목록을 필터링하여 조회할 수도 있다. 또한, 컨테이너 내부에서 명령어를 실행하거나 파일 시스템의 변경 사항을 확인하는 기능도 제공한다.
컨테이너 관리 API를 통해 얻을 수 있는 정보와 수행 가능한 작업은 다음과 같다.
작업 범주 | 주요 기능 (엔드포인트 예시) | 설명 |
|---|---|---|
생명주기 제어 |
| 컨테이너 생성, 시작, 중지, 삭제 |
상태 정보 조회 |
| 컨테이너 목록, 상세 정보, 실시간 리소스 사용량(통계) 조회 |
로그 및 출력 |
| 컨테이너의 표준 출력(stdout) 및 표준 오류(stderr) 로그 스트림 조회 또는 실시간 연결 |
내부 작업 실행 |
| 실행 중인 컨테이너 내부에서 별도의 프로세스(명령어) 실행 |
이러한 API는 도커 클라이언트 명령어(docker run, docker ps 등)의 백엔드 기능을 그대로 제공하며, 더 세밀한 제어와 통합을 가능하게 한다. 따라서 CI/CD 파이프라인이나 컨테이너 플랫폼을 구축할 때 핵심적인 역할을 한다.
3.3. 네트워크 관리
3.3. 네트워크 관리
도커 API의 네트워크 관리 기능은 도커 호스트 상의 가상 네트워크를 생성, 구성, 조회 및 삭제할 수 있게 해준다. 이를 통해 컨테이너 간의 통신을 격리하거나 연결하는 복잡한 네트워크 토폴로지를 프로그래밍 방식으로 구축할 수 있다. 주요 관리 대상에는 사용자 정의 브리지 네트워크, 오버레이 네트워크, 호스트 네트워크, 맥블란 네트워크 등이 포함된다.
네트워크 관리 API는 /networks 엔드포인트를 중심으로 구성된다. GET /networks 요청을 통해 시스템에 존재하는 모든 네트워크 목록을 조회할 수 있으며, POST /networks/create를 사용해 새로운 네트워크를 생성할 수 있다. 네트워크 생성 시에는 네트워크 이름, 드라이버 종류(bridge, overlay 등), 서브넷 및 게이트웨이 설정, IP 주소 관리 방식 등 세부 구성을 JSON 형식의 요청 본문으로 전달한다.
특정 네트워크에 대한 세부 작업은 /networks/{network-id} 엔드포인트를 통해 수행된다. GET 요청으로 해당 네트워크의 상세 정보를 확인하고, DELETE 요청으로 네트워크를 제거할 수 있다. 또한, POST /networks/{network-id}/connect와 POST /networks/{network-id}/disconnect를 사용하면 실행 중인 컨테이너를 네트워크에 연결하거나 연결을 해제하는 작업이 가능하다. 이는 마이크로서비스 애플리케이션에서 서비스별 네트워크 정책을 동적으로 적용할 때 유용하다.
이러한 기능들은 오케스트레이션 도구나 CI/CD 파이프라인에서 컨테이너 네트워킹을 자동화하는 데 핵심적이다. 예를 들어, 특정 애플리케이션 스택을 위한 독립적인 네트워크를 생성하고, 필요한 데이터베이스 컨테이너나 백엔드 서비스 컨테이너만 해당 네트워크에 연결함으로써 보안과 통신 효율성을 높일 수 있다.
3.4. 볼륨 관리
3.4. 볼륨 관리
도커 API의 볼륨 관리 기능은 도커 호스트에 존재하는 데이터 볼륨의 생명주기를 프로그래밍 방식으로 제어할 수 있게 한다. 이 API를 통해 사용자는 JSON 형식의 HTTP 요청을 보내 볼륨을 생성, 조회, 삭제할 수 있으며, 특정 컨테이너에 볼륨을 연결하거나 연결을 해제하는 작업도 수행할 수 있다. 볼륨은 컨테이너의 생명주기와 독립적으로 데이터를 유지하는 핵심 메커니즘으로, 데이터베이스의 영구 저장소나 애플리케이션의 구성 파일을 관리할 때 필수적이다.
볼륨 관리 API의 주요 엔드포인트는 /volumes 경로를 중심으로 구성된다. 예를 들어, POST /volumes/create 요청을 통해 새로운 볼륨을 생성하고, GET /volumes 요청으로 현재 시스템에 존재하는 모든 볼륨 목록을 조회할 수 있다. 또한 GET /volumes/{volume_name}을 사용하면 특정 볼륨의 상세 정보를 확인할 수 있으며, 사용하지 않는 볼륨은 DELETE /volumes/{volume_name} 요청으로 제거할 수 있다. 이러한 API 호출은 도커 데몬이 수신하여 처리한다.
볼륨을 생성할 때는 드라이버 유형, 라벨, 마운트 옵션 등을 지정할 수 있어 다양한 스토리지 백엔드나 클라우드 서비스에 맞춰 유연하게 구성이 가능하다. 또한, POST /containers/{id}/attach나 컨테이너 생성 시의 설정을 통해 특정 볼륨을 컨테이너의 특정 경로에 마운트할 수 있다. 이를 통해 여러 컨테이너가 동일한 볼륨을 공유하여 데이터를 교환하거나, 컨테이너가 삭제된 후에도 데이터를 안전하게 보존하는 지속성을 보장받을 수 있다.
HTTP 메서드 | 엔드포인트 | 주요 기능 |
|---|---|---|
POST |
| 새로운 도커 볼륨 생성 |
GET |
| 볼륨 목록 조회 |
GET |
| 특정 볼륨 정보 조회 |
DELETE |
| 특정 볼륨 삭제 |
4. 인증 및 보안
4. 인증 및 보안
도커 API는 기본적으로 도커 데몬에 대한 원격 제어를 가능하게 하므로, 적절한 인증과 보안 설정이 필수적이다. 도커 데몬은 기본적으로 유닉스 도메인 소켓(/var/run/docker.sock)을 통해 로컬에서 통신하도록 설정되어 있으며, 이 경우 파일 시스템 권한이 주요한 보안 수단이 된다. 그러나 원격 접근을 위해 TCP 소켓을 열어둘 경우, 무단 접근을 방지하기 위한 강력한 보안 조치가 필요하다.
도커 데몬에 TLS를 적용하는 것이 권장되는 보안 방식이다. 이를 위해서는 공개 키 기반 구조를 사용하여 서버 인증서, 클라이언트 인증서, CA 인증서를 생성하고 구성해야 한다. 이렇게 설정하면 모든 API 호출은 HTTPS를 통해 암호화되며, 클라이언트는 유효한 인증서를 제시해야만 도커 데몬과 통신할 수 있다. 이는 네트워크 상에서의 도청 및 중간자 공격을 방지하는 데 핵심적이다.
보다 간소화된 환경이나 내부 테스트를 위해, 도커는 --tlsverify 플래그 없이 TCP 바인딩만을 사용하는 불안전한 모드도 제공하지만, 이는 프로덕션 환경에서 사용해서는 안 된다. 또한, 도커 허브와 같은 레지스트리에 접근할 때는 별도의 인증 토큰이 필요하며, Docker CLI는 사용자의 로그인 정보를 기반으로 이 토큰을 자동으로 관리한다. API를 직접 사용할 경우에는 docker login 명령으로 얻은 설정 파일(~/.docker/config.json) 내의 인증 정보를 HTTP 요청의 헤더에 포함시켜야 한다.
보안 강화를 위한 추가 조치로는 방화벽 규칙을 통해 API 포트에 대한 접근을 특정 IP 주소로 제한하거나, 역할 기반 접근 제어 시스템과 도커를 통합하는 방법이 있다. 최신 버전의 도커 엔진과 API는 지속적으로 발견되는 취약점에 대응하여 보안을 개선하고 있으므로, 정기적인 업데이트 역시 중요한 보안 관행이다.
5. 사용 예시
5. 사용 예시
5.1. cURL을 이용한 호출
5.1. cURL을 이용한 호출
도커 REST API는 HTTP 요청을 통해 직접 호출할 수 있으며, cURL은 이를 위한 대표적인 명령줄 인터페이스 도구이다. 기본적으로 도커 데몬은 유닉스 소켓(/var/run/docker.sock) 또는 네트워크 포트(TCP/HTTP)를 통해 API 엔드포인트를 노출한다. cURL을 사용할 때는 요청 메서드(GET, POST, DELETE 등)와 적절한 JSON 형식의 데이터를 지정해야 한다.
가장 일반적인 사용 예는 로컬의 도커 데몬 소켓을 통해 API를 호출하는 것이다. 예를 들어, 실행 중인 모든 컨테이너 목록을 조회하려면 curl --unix-socket /var/run/docker.sock http://localhost/v1.45/containers/json 명령을 사용한다. 여기서 v1.45는 사용 중인 도커 엔진의 API 버전을 나타낸다. 새로운 컨테이너를 생성하려면 POST 요청과 함께 컨테이너 설정을 담은 JSON 데이터를 --data 옵션으로 전송해야 한다.
원격 도커 호스트의 API를 호출하는 경우에는 TCP 주소와 포트를 지정하며, 보안을 위해 TLS 인증서를 사용하는 것이 권장된다. cURL 명령어에 --cert, --key, --cacert 옵션을 추가하여 인증을 구성할 수 있다. 이 방식을 통해 스크립트나 간단한 테스트에서 도커 SDK 없이도 도커 엔진의 모든 기능을 프로그래밍적으로 제어할 수 있다.
5.2. 공식 SDK 활용
5.2. 공식 SDK 활용
도커는 다양한 프로그래밍 언어를 위한 공식 SDK를 제공하여, 개발자가 REST API를 직접 호출하는 번거로움 없이 도커 엔진의 기능을 쉽게 활용할 수 있도록 돕는다. 이러한 SDK들은 HTTP 요청과 JSON 응답을 추상화하여, 각 언어의 관용적인 방식으로 도커 데몬과 상호작용할 수 있는 클라이언트 라이브러리를 제공한다.
주요 공식 SDK로는 Python용 docker-py, Go용 docker/client, Java용 docker-java 등이 있다. 예를 들어, docker-py를 사용하면 파이썬 코드 내에서 컨테이너를 실행하거나 이미지를 빌드하는 작업을 마치 네이티브 객체를 다루듯이 수행할 수 있다. 이러한 SDK들은 도커 클라이언트의 명령어 기능 대부분을 프로그래밍 방식으로 구현할 수 있게 해준다.
공식 SDK를 활용하면 코드의 가독성과 유지보수성이 향상되며, 인증 처리나 에러 핸들링과 같은 보일러플레이트 코드를 줄일 수 있다. 또한, SDK는 도커 API 버전 호환성을 관리하는 데 도움을 주어, 애플리케이션이 다른 버전의 도커 엔진과도 안정적으로 통신할 수 있도록 한다.
사용 예시로, 파이썬에서 docker-py 라이브러리를 설치한 후, 간단한 코드로 로컬의 도커 데몬에 연결하여 컨테이너 목록을 가져오거나 새로운 이미지를 풀(pull)하는 작업을 수행할 수 있다. 이는 cURL을 이용해 직접 엔드포인트를 호출하는 방식보다 직관적이고 효율적이다.
6. 버전 관리
6. 버전 관리
도커 API는 시간이 지남에 따라 기능이 추가되고 변경되며, 이를 체계적으로 관리하기 위해 버전 관리 체계를 도입한다. 도커 엔진의 각 주요 릴리스는 특정 API 버전과 연결되어 있으며, 클라이언트는 요청 시 사용할 API 버전을 명시해야 한다. 이는 하위 호환성을 유지하면서 새로운 기능을 안정적으로 도입하기 위한 핵심 메커니즘이다.
API 버전은 일반적으로 요청 헤더(Docker-API-Version)나 URL 경로(/v{version_number}/)를 통해 지정된다. 예를 들어, 최신 도커 엔진이 여러 API 버전을 지원할 수 있으며, 클라이언트는 자신이 호환되는 버전을 명시적으로 선택하여 호출한다. 이 방식은 새로운 API가 도입되어도 기존에 작성된 스크립트나 애플리케이션이 깨지지 않고 계속 작동하도록 보장한다.
도커는 API 버전을 연도-월 형식(예: v1.41)으로 관리하며, 이 버전 번호는 도커 엔진의 릴리스 버전과 밀접한 연관이 있다. 공식 도커 문서나 GitHub의 릴리스 노트를 통해 각 엔진 버전별로 지원하는 API 버전과 새로 추가되거나 사용 중단(deprecated)된 엔드포인트에 대한 정보를 확인할 수 있다. 사용자는 지속 가능한 통합을 위해 특정 API 버전에 의존하는 대신, 가능한 최신 안정 버전을 목표로 개발하는 것이 권장된다.
이러한 버전 관리 정책은 마이크로서비스 아키텍처나 CI/CD 파이프라인에서 도커 API를 자동화 도구로 사용할 때 특히 중요하다. 쿠버네티스나 다양한 오케스트레이션 도구들도 내부적으로 특정 도커 API 버전과 상호작용하므로, 도커 엔진을 업그레이드할 때는 호환되는 API 버전을 확인해야 한다.
