Docker Engine API

Docker Engine API

Docker는 Docker 데몬과 상호작용하기 위한 API(Docker Engine API)와 Go·Python용 SDK를 제공해요. SDK를 쓰면 Docker 앱과 솔루션을 효율적으로 빌드하고 확장할 수 있어요. Go나 Python이 맞지 않는다면 Docker Engine API를 직접 사용할 수도 있어요.

출처: 문서

본문

Docker는 Docker 데몬과 상호작용하는 API(Docker Engine API)와 Go·Python용 SDK를 제공해요. SDK를 이용하면 Docker 앱과 솔루션을 효율적으로 빌드하고 확장할 수 있어요. Go나 Python이 안 맞는다면 Docker Engine API를 직접 사용해도 돼요. Docker Engine SDK에 대한 내용은 Docker Engine SDK로 개발하기를 참고해요.

Docker Engine API는 wget이나 curl 같은 HTTP 클라이언트, 또는 대부분의 현대 프로그래밍 언어에 포함된 HTTP 라이브러리로 접근하는 RESTful API예요.

API 레퍼런스 보기

최신 버전 API 레퍼런스를 보거나, 특정 버전을 선택할 수 있어요.

버전이 지정된 API와 SDK

어떤 버전의 Docker Engine API를 써야 하는지는 Docker 데몬과 Docker 클라이언트의 버전에 따라 달라져요. Docker Engine SDK의 특정 버전은 특정 Docker Engine API 버전과 그 이전 버전을 모두 지원해요. 호환성이 깨지는 변경이 있으면 눈에 띄게 문서화돼요.

참고 Docker 데몬과 클라이언트가 항상 같은 버전일 필요는 없어요. 다만 다음을 기억해 두세요.

• 데몬이 클라이언트보다 새로우면, 클라이언트는 데몬의 새 기능이나 사용 중단된 API 엔드포인트를 알지 못해요.
• 클라이언트가 데몬보다 새로우면, 클라이언트는 데몬이 모르는 API 엔드포인트를 요청할 수 있어요.

새 기능이 추가될 때마다 API의 새 버전이 릴리스돼요. Docker API는 하위 호환(backward-compatible)이 유지되므로, 새 기능이 필요하지 않다면 API를 쓰는 코드를 업데이트할 필요가 없어요.

Docker 데몬과 클라이언트가 지원하는 API의 최고·최저 버전을 확인하려면 docker version을 실행해요.

$ docker version
Client: Docker Engine - Community
 Version:           29.8.1
 API version:       1.56
 ...

Server: Docker Engine - Community
 Engine:
  Version:          29.8.1
  API version:      1.56 (minimum version 1.40)
  ...

API 버전을 지정하는 방법은 다음과 같아요.

• SDK를 쓸 때는 최신 버전을 사용해요. 최소한 필요한 기능이 포함된 API 버전을 쓰는 버전을 사용해요.
• curl을 직접 쓸 때는 URL의 첫 부분에 버전을 지정해요. 예를 들어 엔드포인트가 /containers/라면 /v1.56/containers/처럼 써요.
• Docker CLI 또는 Docker Engine SDK가 docker version이 보고한 버전보다 오래된 API 버전을 쓰도록 강제하려면 환경 변수 DOCKER_API_VERSION에 올바른 버전을 설정해요. 이 방법은 Linux, Windows, macOS 클라이언트 모두에서 동작해요.

$ DOCKER_API_VERSION=1.55

환경 변수가 설정된 동안에는 Docker 데몬이 더 새로운 버전을 지원해도 해당 버전의 API가 사용돼요. 이 환경 변수는 API 버전 협상을 비활성화하므로, 꼭 특정 버전을 써야 하거나 디버깅 목적이 아니라면 쓰지 않는 게 좋아요.

• Docker Go SDK는 API 버전 협상을 활성화할 수 있는데, 사용 중인 클라이언트와 Docker Engine 양쪽이 지원하는 API 버전을 자동으로 선택해요.
• SDK에서도 client 객체의 파라미터로 API 버전을 프로그램적으로 지정할 수 있어요. Go 생성자와 Python SDK의 client 문서를 참고해요.

최소 API 버전

Docker Engine API 서버와 클라이언트는 API 버전 협상을 지원해요. 클라이언트가 더 오래된 Docker Engine에 연결하면, 클라이언트와 데몬 양쪽이 지원하는 API의 최고 버전을 협상하고 필요하면 더 오래된 API 버전으로 내려가요.

더 오래된 API 버전으로 내려갈 때, 이후 API 버전에서 도입된 기능은 비활성화되고 요청·응답은 협상된 API 버전에 맞게 조정돼요.

API 버전 협상 덕분에 최신 API 버전 스펙으로 업그레이드되지 않은 도구도 더 새로운 Docker Engine과 통신할 수 있어요(그 반대도 마찬가지예요). 다만 호환성은 "최선의 노력(best effort)"이며, Docker는 완전한 호환을 위해 노력하지만 일부 기능은 없을 수 있어요.

API 버전 매트릭스

사용 중단된 API 버전

v1.40 이전의 API 버전은 사용이 중단되었고 현재 버전의 Docker Engine과 CLI에서 더 이상 지원하지 않아요. 사용 중단된 버전의 보관(archived) 문서는 GitHub 코드 저장소에서 찾을 수 있어요.

더 알아보기

• Docker Engine API 버전 히스토리
• Docker Engine SDK로 개발하기
• docker version 명령