Docker 플러그인 API

Docker 플러그인 API (Docker Plugin API)

Docker 플러그인은 Docker Engine에 기능을 추가하는 아웃오브프로세스 확장이에요.

이 문서는 Docker Engine 플러그인 API를 설명해요. Docker Engine이 관리하는 플러그인에 대한 정보는 Docker Engine 플러그인 시스템을 참고하세요.

이 페이지는 자신의 Docker 플러그인을 개발하려는 사람들을 위한 것이에요. Docker 플러그인에 대해 배우거나 사용하려면 여기를 보세요.

출처: 문서

본문

플러그인이란 무엇인가 (What plugins are)

플러그인은 Docker 데몬과 같거나 다른 호스트에서 실행되는 프로세스로, Plugin discovery에 설명된 플러그인 디렉토리 중 하나에 파일을 배치해 스스로 등록해요.

플러그인은 사람이 읽을 수 있는 짧은 소문자 문자열 이름을 가져요. 예를 들어 myplugin.

플러그인은 컨테이너 안에서도 밖에서도 실행될 수 있어요. 현재는 컨테이너 밖에서 실행하는 것이 권장돼요.

플러그인 발견 (Plugin discovery)

Docker는 사용자나 컨테이너가 이름으로 플러그인을 사용하려 할 때마다 플러그인 디렉토리에서 찾아 플러그인을 발견해요.

플러그인 디렉토리에 넣을 수 있는 세 가지 유형의 파일이 있어요.

.sock 파일은 Unix 도메인 소켓.
.spec 파일은 unix:///other.sock 또는 tcp://localhost:8080 같은 URL을 담는 텍스트 파일.
.json 파일은 플러그인의 전체 json 스펙을 담는 텍스트 파일.

Unix 도메인 소켓 파일을 가진 플러그인은 Docker 데몬과 같은 호스트에서 실행되어야 해요. .spec 또는 .json 파일을 가진 플러그인은 원격 URL을 지정하면 다른 호스트에서 실행될 수 있어요.

Unix 도메인 소켓 파일은 /run/docker/plugins 아래에 있어야 하고, spec 파일은 /etc/docker/plugins 또는 /usr/lib/docker/plugins 아래에 있을 수 있어요.

파일의 이름(확장자 제외)이 플러그인 이름을 결정해요.

예를 들어 myplugin이라는 플러그인은 /run/docker/plugins/myplugin.sock에 Unix 소켓을 만들 수 있어요.

정의를 서로 격리하고 싶다면 각 플러그인을 분리된 하위 디렉토리에 정의할 수 있어요. 예를 들어 /run/docker/plugins/myplugin/myplugin.sock 아래에 myplugin 소켓을 만들고 myplugin 컨테이너 안에 /run/docker/plugins/myplugin만 마운트할 수 있어요.

Docker는 항상 /run/docker/plugins에서 Unix 소켓을 먼저 검색해요. 소켓이 없으면 /etc/docker/plugins와 /usr/lib/docker/plugins 아래에서 spec 또는 json 파일을 확인해요. 디렉토리 스캔은 주어진 이름의 첫 플러그인 정의를 찾는 즉시 중지돼요.

JSON 스펙 (JSON specification)

플러그인의 JSON 형식은 다음과 같아요:

{
  "Name": "plugin-example",
  "Addr": "https://example.com/docker/plugin",
  "TLSConfig": {
    "InsecureSkipVerify": false,
    "CAFile": "/usr/shared/docker/certs/example-ca.pem",
    "CertFile": "/usr/shared/docker/certs/example-cert.pem",
    "KeyFile": "/usr/shared/docker/certs/example-key.pem"
  }
}

TLSConfig 필드는 선택 사항이며, 이 구성이 있으면 TLS가 검증돼요.

플러그인 수명주기 (Plugin lifecycle)

플러그인은 Docker보다 먼저 시작하고 Docker 이후에 중지해야 해요. 예를 들어 systemd를 지원하는 플랫폼용 플러그인을 패키징할 때 systemd 의존성을 사용해 시작·종료 순서를 관리할 수 있어요.

플러그인을 업그레이드할 때는 먼저 Docker 데몬을 중지하고 플러그인을 업그레이드한 다음 Docker를 다시 시작해야 해요.

플러그인 활성화 (Plugin activation)

플러그인이 처음 참조될 때 — 사용자가 이름으로 참조하거나(예: docker run --volume-driver=foo) 플러그인을 사용하도록 이미 구성된 컨테이너가 시작될 때 — Docker는 플러그인 디렉토리에서 이름이 있는 플러그인을 찾고 핸드셰이크로 활성화해요. 아래 Handshake API 참고.

플러그인은 Docker 데몬 시작 시 자동으로 활성화되지 않아요. 대신 필요할 때 지연(lazily) 또는 주문형(on-demand)으로만 활성화돼요.

Systemd 소켓 활성화 (Systemd socket activation)

플러그인은 systemd로 소켓 활성화될 수도 있어요. 공식 Plugins helpers는 소켓 활성화를 네이티브 지원해요. 플러그인이 소켓 활성화되려면 service 파일과 socket 파일이 필요해요.

service 파일(예: /lib/systemd/system/your-plugin.service):

[Unit]
Description=Your plugin
Before=docker.service
After=network.target your-plugin.socket
Requires=your-plugin.socket docker.service

[Service]
ExecStart=/usr/lib/docker/your-plugin

[Install]
WantedBy=multi-user.target

socket 파일(예: /lib/systemd/system/your-plugin.socket):

[Unit]
Description=Your plugin

[Socket]
ListenStream=/run/docker/plugins/your-plugin.sock

[Install]
WantedBy=sockets.target

이것은 Docker 데몬이 플러그인이 수신 대기하는 소켓에 연결할 때(예: 데몬이 처음 사용할 때나 플러그인 하나가 우연히 다운되었을 때) 플러그인이 실제로 시작될 수 있게 해줘요.

API 설계 (API design)

Plugin API는 웹훅과 비슷하게 HTTP 위의 RPC 스타일 JSON이에요.

요청은 Docker 데몬에서 플러그인으로 흘러가요. 플러그인은 HTTP 서버를 구현하고 "plugin discovery" 섹션에서 언급한 Unix 소켓에 이것을 바인드해야 해요.

모든 요청은 HTTP POST 요청이에요.

API는 Accept 헤더로 버전이 매겨지며, 현재 항상 application/vnd.docker.plugins.v1+json으로 설정돼요.

핸드셰이크 API (Handshake API)

플러그인은 다음 "핸드셰이크" API 호출로 활성화돼요.

/Plugin.Activate

Request: empty body Response:

{
    "Implements": ["VolumeDriver"]
}

이 플러그인이 구현하는 Docker 하위 시스템 목록으로 응답해요. 활성화 후 플러그인은 이 하위 시스템에서 이벤트를 받게 돼요.

가능한 값은:

플러그인 재시도 (Plugin retries)

플러그인의 메서드를 호출하려는 시도는 최대 30초 동안 지수 백오프로 재시도돼요. 플러그인을 컨테이너로 패키징할 때 도움이 될 수 있는데, 사용자 컨테이너를 실패시키기 전에 플러그인 컨테이너가 시작할 기회를 주기 때문이에요.

플러그인 헬퍼 (Plugins helpers)

플러그인 개발을 쉽게 하기 위해 Docker가 현재 지원하는 각 플러그인 유형에 대한 sdk를 docker/go-plugins-helpers에서 제공하고 있어요.

Docker 플러그인 API