Docker 엔진은 사용자가 필요 없이 컨테이너를 제어하는 데 사용할 수 있는 REST API를 제공합니다. docker CLI. API는 HTTP 네트워크 호출을 사용하여 동등한 기능을 노출합니다. 선호하는 프로그래밍 언어를 사용하여 일반적인 Docker 작업을 스크립팅하거나 호스트 중 하나를 원격으로 제어할 수 있습니다. CLI는 내부적으로 동일한 API에 의존하여 내장 명령을 제공합니다.
이 기사에서는 API를 활성화하고 사용하는 기본 사항을 살펴보겠습니다. 특정 사용 사례를 염두에 둔 경우 API 참조 문서를 참조하여 필요한 엔드포인트를 식별하십시오.
Docker 엔진의 API 활성화
API는 Docker 엔진과 통합됩니다. 작동하는 모든 Docker 호스트는 이미 API 상호 작용을 수용할 준비가 되어 있습니다. 서비스를 노출하려면 Docker 데몬을 TCP 소켓과 기본 Unix 소켓 대신에 바인딩해야 합니다. 시작 dockerd 이랑 -H 수신 대기할 소켓을 지정하는 플래그:
sudo dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375
이 명령은 포트 2375에서 API를 노출합니다. 기본 Unix 소켓은 유지되므로 Docker CLI는 재구성 없이 계속 작동합니다. 포트 2375는 규칙에 따라 Docker에 사용됩니다. 환경에 맞게 자유롭게 변경하십시오.
Docker를 편집하여 항상 이러한 설정으로 시작하도록 할 수 있습니다. systemd 서비스 구성 파일. 편집 또는 생성 /etc/systemd/system/docker.service.d/options.conf찾기 ExecStart 추가 플래그를 포함하도록 수정합니다.
[Service] ExecStart=/usr/bin/dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375
새로고침 systemd 변경 사항을 적용하기 위한 구성:
sudo systemctl daemon-reload
이제 다음에서 Docker Engine API와 상호 작용할 준비가 되었습니다. 127.0.0.1:2375.
보안에 대한 참고 사항
위의 단계는 보호 기능이 전혀 없는 API를 노출합니다. 호스트의 포트 2375에 액세스할 수 있는 사람은 누구나 Docker 데몬에 임의의 명령을 보내 새 컨테이너를 시작하거나 디스크를 이미지로 채우거나 기존 워크로드를 파괴할 수 있습니다.
네트워크에서 의도적으로 Docker를 노출하지 않는 한 포트에 대한 연결을 차단하도록 방화벽을 설정해야 합니다. 원격 액세스를 활성화하려면 인증된 클라이언트에 대한 액세스를 제한하도록 데몬 소켓에 대한 TLS를 구성해야 합니다.
TLS가 활성화되면 각 클라이언트에 데몬의 인증 기관을 설치해야 합니다. 요청할 때마다 클라이언트 인증서와 클라이언트 키를 제공해야 합니다. 수행할 단계는 사용 중인 도구에 따라 다릅니다. 다음은 에 대한 예입니다. curl:
curl https://127.0.0.1:2375/v1.41/containers/json --cert client-cert.pem --key client-key.pem
사용 사례에 따라 TCP 소켓을 전혀 바인딩할 필요가 없을 수도 있습니다. 클라이언트가 Unix 소켓을 지원하는 경우 Docker의 기존 소켓을 사용하여 연결할 수 있습니다.
curl --unix-socket /var/run/docker.sock http://localhost/v1.41/containers
이는 의도하지 않은 TCP 소켓 노출 위험을 감수하는 것보다 안전한 선택이 될 수 있습니다.
API 사용
API는 버전이 지정된 엔드포인트를 사용하므로 특정 버전의 요청 및 응답 형식에 고정할 수 있습니다. 각 끝점 URL의 시작 부분에 사용 중인 버전을 지정해야 합니다. v1.41은 작성 당시 프로덕션 Docker 빌드에 있는 최신 릴리스입니다.
http://127.0.0.1:2375/v1.41
API 엔드포인트는 REST 기능 단위로 그룹화됩니다. 이는 컨테이너, 이미지 및 볼륨과 같은 Docker의 기본 개체 유형에 매핑됩니다. 일반적으로 이름으로 시작하는 기본 URL 내에서 특정 객체 유형에 대한 API를 찾을 수 있습니다.
# APIs related to container operations http://127.0.0.1:2375/v1.41/containers
API는 HTTP 클라이언트와의 모든 데이터 교환에 JSON을 사용합니다. 엔드포인트는 JSON 요청 본문을 수락하고 그 대가로 JSON 응답을 발행합니다. 이렇게 하면 프로그래밍 환경에 포함된 JSON 라이브러리를 사용할 수 있으므로 애플리케이션 내부의 데이터 처리가 간소화됩니다. 다음과 같은 도구 jq 터미널에서 실험하는 경우 응답을 압축, 필터링 및 정렬하는 데 사용할 수 있습니다.
공통 엔드포인트
API가 Docker CLI의 기능을 복제하기 때문에 여기에서 모두 처리하기에는 가능한 엔드포인트가 너무 많습니다. 대신 Docker의 핵심 기능과 관련하여 가장 일반적으로 사용되는 몇 가지 옵션을 보여줍니다.
컨테이너 나열
호스트의 전체 컨테이너 목록은 다음에서 얻을 수 있습니다. /containers/json 끝점:
curl http://127.0.0.1:2375/v1.41/containers/json
기본적으로 실행 중인 컨테이너만 표시하도록 설정됩니다. 추가하다 all=true 중지된 컨테이너도 포함하도록 쿼리 문자열에 추가합니다. 와 함께 반환되는 총 컨테이너 수를 제한합니다. limit 매개변수(예: limit=10. 가장 최근에 생성된 10개의 컨테이너만 포함됩니다.
특정 속성이 있는 컨테이너로 목록을 정리하는 데 여러 가지 필터를 사용할 수 있습니다. 다음 구문으로 설정됩니다.
curl http://127.0.0.1:2375/v1.41/containers/json?filters={"name":"demo"}
이 URL은 demo 컨테이너. 다른 필터는 다음과 같은 유사한 방식으로 표현될 수 있습니다. {"status":["running","paused"]} 실행 및 일시 중지된 컨테이너를 가져오거나 {"health=["healthy"]} 건강한 용기만을 위해.
새 컨테이너 시작
API를 사용할 때 컨테이너 시작은 2단계 프로세스입니다. 먼저 컨테이너를 생성한 다음 별도의 API 호출에서 컨테이너를 시작해야 합니다.
다음을 만들어 컨테이너를 만듭니다. POST 에 요청 /containers/create 끝점. 여기에는 다음에서 허용하는 플래그에 해당하는 필드가 있는 JSON 본문이 필요합니다. docker run CLI 명령.
다음은 컨테이너를 만드는 최소한의 예입니다.
curl http://127.0.0.1:2375/v1.41/containers/create
-X POST
-H "Content-Type: application/json"
-d '{"Image": "example-image:latest"}'
JSON 응답에는 새 컨테이너의 ID와 생성 시 발생하는 모든 경고가 포함됩니다. 전화로 ID를 보내십시오. /containers/:id/start 끝점:
curl http://127.0.0.1:2375/v1.41/containers/abc123/start -X POST
이제 컨테이너가 Docker 호스트에서 실행됩니다.
컨테이너 정리
다음을 발행하여 중지된 컨테이너를 제거합니다. POST 에 요청 /containers/prune 끝점:
curl http://127.0.0.1:2375/v1.41/containers/prune -X POST
다음과 같은 JSON 응답이 발행됩니다. ContainersDeleted 그리고 SpaceReclaimed 필드. ContainersDeleted 성공적으로 제거된 컨테이너 ID의 배열입니다. SpaceReclaimed 해제된 총 저장 공간을 바이트 단위로 알려줍니다.
이 끝점은 작업을 제한하기 위해 두 개의 쿼리 문자열 매개 변수를 허용합니다. 그만큼 until 매개변수는 다음과 같이 지정된 시간 이전에 생성된 컨테이너로 삭제를 제한합니다. until=10m 또는 until=2022-03-01. 그만큼 label 주어진 레이블이 있거나 없는 컨테이너에 대한 옵션 필터; 환경 label=demo=example 다음이 포함된 컨테이너만 제거합니다. demo=example 상표.
이미지 나열
그만큼 /images/json 엔드포인트는 Docker 호스트에 저장된 이미지를 열거하는 데 사용됩니다.
curl http://127.0.0.1:2375/v1.41/images/json
필터를 사용하여 응답 내용을 변경할 수 있습니다. 이들은 JSON 객체로 제공됩니다. filters 컨테이너 목록 API와 유사하게 쿼리 문자열 매개변수입니다. 주목할만한 옵션 중 하나는 reference 주어진 태그가 있는 이미지를 선택합니다. filters={"reference":"hello-world:latest"}.
건물 이미지
API를 사용하여 Dockerfiles에서 새 Docker 이미지를 빌드할 수 있습니다. 그만큼 /build 엔드포인트를 보내야 합니다. tar 보관소. 이 아카이브의 내용은 이미지의 빌드 컨텍스트로 사용됩니다. 아카이브에는 빌드 지침이 포함된 Dockerfile이 포함되어야 합니다.
cat context.tar | curl http://127.0.0.1:2375/v1.41/build?t=example-image:latest -X POST
위의 명령은 context.tar Docker 데몬에 연결하고 다음을 사용하여 이미지를 빌드합니다. Dockerfile 이내에. 이미지는 다음과 같이 태그됩니다. example-image:latest Docker 호스트에 저장됩니다.
이 끝점은 기능과 일치하는 많은 추가 쿼리 문자열 매개 변수를 허용합니다. docker build CLI. 여기에는 다음이 포함됩니다. dockerfile=path/to/dockerfile빌드 컨텍스트의 Dockerfile에 대한 경로를 지정하려면, rm=true빌드에 의해 생성된 중간 컨테이너를 삭제하고, pull=true Dockerfile에서 참조하는 이미지의 업데이트된 버전을 시도하고 획득합니다.
API를 사용하려면 빌드가 완료될 때까지 클라이언트가 연결된 상태를 유지해야 합니다. 네트워크가 끊기고 연결이 닫히면 빌드가 취소됩니다.
데몬 이벤트 로그 나열
그만큼 /events API는 다음으로도 액세스할 수 있는 데몬 이벤트 로그 데이터를 표시합니다. docker events CLI 명령. 이 끝점은 발생하는 이벤트를 실시간으로 스트리밍합니다.
curl http://127.0.0.1:2375/v1.41/events
컨테이너 생성, 이미지 태그, 볼륨 마운트, 네트워크 변경 등 다양한 종류의 이벤트가 노출됩니다. 다음을 사용하여 특정 종류의 이벤트로 필터링할 수 있습니다. type 분야 filters 쿼리 매개변수:
# Only get container events
curl http://127.0.0.1:2375/v1.41/events?filters={'type':'container'}
특정 객체와 관련된 이벤트로 제한할 수도 있습니다.
# Get events pertaining to the container with ID abc123
curl http://127.0.0.1:2375/v1.41/events?filters={'container':'id'}
두 개의 다른 쿼리 문자열 매개변수, since 그리고 until타임스탬프 범위를 지정하여 기록 이벤트를 표시할 수 있습니다.
시스템 정보 얻기
Docker Engine API를 사용하여 실행 중인 물리적 호스트에 대한 정보를 얻을 수 있습니다.
curl http://127.0.0.1:2375/v1.41/info
이 끝점은 호스트 및 Docker 데몬의 현재 상태와 구성을 설명하는 광범위한 세부 정보를 제공합니다. 응답의 필드에는 실행, 일시 중지 및 중지된 컨테이너 수, Docker 설치 디렉터리 경로, 하드웨어 및 OS 세부 정보, 클러스터 내에서 작동 중일 때 서버의 Swarm 구성이 포함됩니다.
결론
Docker Engine API는 HTTP를 통해 호스트의 Docker 데몬에 명령을 보내는 방법을 제공합니다. 이를 통해 특정 Docker CLI 동작에 의존하지 않고 프로그래밍 방식의 상호 작용을 더 간단하게 스크립팅할 수 있습니다. API를 사용하여 모니터링을 강화하고 유지 관리를 쉽게 하기 위해 Docker 서버를 원격으로 관리할 수도 있습니다.
API를 호출하는 것은 간단해야 하지만 TCP 소켓 주변의 보안 보호에 주의를 기울여야 합니다. 승인된 클라이언트만 연결할 수 있도록 TLS로 보호되지 않는 한 네트워크에 소켓을 노출하지 마십시오. 침입자가 데몬 인스턴스를 발견하고 명령을 내리기 시작하면 이 추가 설정 단계를 생략하면 비용이 많이 들 수 있습니다.
SDK 중 하나를 채택하여 자체 애플리케이션 내에서 API를 훨씬 더 쉽게 사용할 수 있습니다. 공식 또는 커뮤니티 제공 옵션은 C, C#, C++, Go, Java, NodeJS, PHP, Python 및 Ruby를 포함한 모든 인기 있는 프로그래밍 언어에 사용할 수 있습니다. SDK는 API의 끝점을 코드에서 호출할 수 있는 편리한 클래스와 함수로 래핑하여 Docker 설치와 상호 작용하는 데 필요한 상용구의 양을 줄입니다.
