docker-compose api（docker api文档）

文章前言

Docker作为最流行的容器化解决方案其API接口提供了强大的容器管理功能，通过Docker API我们可以实现自动化的容器lifecycle管理、数据管理、网络管理等，大大简化容器的使用难度，本篇文章我们主要介绍Docker API的基本使用

版本划分

Docker API分为三个版本：

• V1：Docker最初的API版本，目前已被废弃

• V2：Docker现在的稳定版本API，与Docker CLI和Docker Engine完全兼容

• V3：Docker的最新API版本(alpha 版本),提供Swarm、Network、Plugin等新特性的支持

调用方式

Docker API是Docker引擎提供的一组RESTful API，用于管理和操作Docker容器、镜像、网络和数据卷等资源，Docker API支持以下几种调用方式：

Docker CLI

Docker CLI是Docker命令行工具，可以通过命令行界面来管理和操作Docker引擎，Docker CLI实际上是对Docker API的一层封装，它可以直接调用Docker API来完成相应的操作，下面是一个使用Docker CLI启动一个新的Docker容器的示例：

docker run -d -p 8080:80 nginx:latest

Docker SDK

Docker SDK是一组编程语言特定的API，用于访问和管理Docker引擎，，Docker SDK提供了一组简单的API可以直接在程序中调用而无需手动构造HTTP请求和解析响应，Docker SDK支持多种编程语言，包括Python、Go、Java、JavaScript等，下面是一个使用Python Docker SDK创建一个新的Docker容器的示例：

import docker
client = docker.from_env()container = client.containers.run(\\\'nginx:latest\\\', detach=True, ports={\\\'80/tcp\\\': \\\'8080\\\'})print(container.id)

上述示例使用Python Docker SDK创建了一个Docker客户端对象，然后调用containers.run()方法来创建一个新的容器，containers.run()方法的参数包括镜像名称、容器名称、命令、端口映射等，创建容器后，程序打印出容器的ID

HTTP RESTful API

HTTP RESTful API是Docker API最基本的调用方式，通过HTTP请求和响应来管理和操作Docker引擎，HTTP RESTful API使用标准的HTTP方法和URL路径来表示请求的操作并使用JSON格式的数据来传输请求和响应的参数和结果，下面是一个使用HTTP RESTful API列出所有Docker容器的示例，通过发送了一个HTTP GET请求到Docker引擎的/containers/json路径表示要列出所有的Docker容器，Docker引擎收到请求后返回一个JSON格式的数组，表示所有容器的信息，例如：容器ID、名称、状态等

GET /containers/json HTTP/1.1Host: localhost:2375

安全机制

为了保障Docker API的安全性，Docker引擎提供了以下几种安全机制：

认证授权

Docker API支持基于OAuth2.0的认证和授权机制，可以通过访问令牌(access token)来验证客户端的身份并授权客户端访问Docker API的特定资源，Docker引擎还支持基于TLS的X.509证书认证，可以使用客户端证书来验证客户端的身份并授权客户端访问Docker API的特定资源

Step 1：安装配置OAuth2.0认证插件

首先需要安装和配置一个OAuth2.0认证插件，例如：Docker OAuth2 Authentication Plugin，该插件支持基于OAuth 2.0的认证和授权机制并提供了一个简单的RESTful API用于管理和操作访问令牌和授权规则，我们可以使用以下命令来安装和启动OAuth2.0认证插件，CLIENT_ID和CLIENT_SECRET是OAuth2.0提供的客户端ID和客户端密钥，COOKIE_SECRET是用于加密访问令牌的秘钥

  docker run -d \\\\    --name oauth2_proxy \\\\    -p 4180:4180 \\\\    -e OAUTH2_PROXY_CLIENT_ID=<CLIENT_ID> \\\\    -e OAUTH2_PROXY_CLIENT_SECRET=<CLIENT_SECRET> \\\\    -e OAUTH2_PROXY_COOKIE_SECRET=<COOKIE_SECRET> \\\\    quay.io/oauth2-proxy/oauth2-proxy

Step 2：配置Docker API认证授权

接下来需要配置Docker API认证和授权机制以便使用OAuth 2.0认证插件验证客户端的身份并授权客户端访问Docker API的特定资源，我们可以使用以下命令来启动Docker引擎并将OAuth2.0认证插件作为Docker API的认证和授权服务，其中token_url和auth_url分别是OAuth2.0认证插件的访问令牌和授权URL，user_key是OAuth2.0提供的用户信息键名

  dockerd \\\\    --authorization-plugin=oauth2_proxy \\\\    --authorization-plugin-auth-config=token_url=http://localhost:4180/token,auth_url=http://localhost:4180/auth,user_key=email

Step 3：获取用户访问令牌

现在可以使用OAuth2.0认证插件提供的RESTful API来获取访问令牌并使用该访问令牌来访问Docker API的特定资源，我们可以使用以下命令来获取访问令牌，其中CLIENT_ID和CLIENT_SECRET是OAuth2.0提供的客户端ID和客户端密钥

 curl -X POST \\\\    -d \\\"client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&grant_type=client_credentials\\\" \\\\    http://localhost:4180/token

获取到访问令牌后可以将其作为Authorization请求头的值来访问Docker API的特定资源，如下所示：

 curl -H \\\"Authorization: Bearer <ACCESS_TOKEN>\\\" http://localhost:2375/containers/json

总的来说，使用OAuth2.0认证和授权机制可以帮助管理员保障Docker API的安全性，同时提供了灵活的认证和授权方案，管理员可以根据实际需求来选择合适的认证和授权插件并对其进行配置和调整以达到最佳的安全效果

TLS 加密

Docker API支持基于TLS的加密机制，可以通过HTTPS协议来加密Docker API的通信防止数据在传输过程中被篡改或窃取，Docker引擎还支持自签名证书和第三方证书的使用，可以根据实际需求来选择合适的证书

Step 1：生成证书和密钥

首先需要生成一个自签名的TLS证书和密钥用于加密Docker API的通信，可以使用以下命令来生成一个有效期为365天的自签名TLS证书和密钥，保存在cert.pem和key.pem文件中

openssl req -newkey rsa:4096 -nodes -keyout key.pem -x509 -days 365 -out cert.pem

Step 2：配置Docker引擎

接下来需要配置Docker引擎以便使用TLS加密机制加密Docker API的通信，我们可以使用以下命令来启动Docker引擎并将自签名TLS证书和密钥作为Docker API的加密证书和密钥：

  dockerd \\\\    --tlsverify \\\\    --tlscacert=ca.pem \\\\    --tlscert=cert.pem \\\\    --tlskey=key.pem \\\\    -H=0.0.0.0:2376

备注：--tlsverify表示开启TLS加密机制，--tlscacert、--tlscert和--tlskey分别是TLS证书的CA证书、公钥和私钥，-H是Docker API的监听地址和端口号

Step 3：配置Docker客户端

现在需要配置Docker客户端以便使用TLS加密机制连接Docker API，我们可以使用以下命令来配置Docker客户端并将自签名TLS证书和密钥作为Docker API的加密证书和密钥，其中的<SERVER_IP>是Docker引擎的IP地址或主机名，DOCKER_TLS_VERIFY表示开启TLS加密机制，DOCKER_CERT_PATH是TLS证书和密钥的路径

export DOCKER_HOST=tcp://<SERVER_IP>:2376 DOCKER_TLS_VERIFY=1 DOCKER_CERT_PATH=.

Step 4：测试TLS加密

现在可以使用Docker客户端连接到Docker API并测试TLS加密机制是否正常工作，可以使用以下命令来测试TLS加密，如果返回结果中包含Security Options: tls，则表示TLS加密机制已经成功启用

docker info

访问控制

Docker API支持基于IP地址和端口号的访问控制机制，用户可以限制特定IP地址或端口号的客户端访问Docker API的特定资源，Docker引擎还支持基于Docker网络的访问控制机制，可以根据网络名称或ID来限制客户端访问Docker API的特定资源

Step 1：配置Docker引擎

配置Docker引擎以便使用基于IP地址和端口的访问控制机制限制Docker API的访问，我们可以使用以下命令来启动Docker引擎并将允许访问的IP地址和端口作为Docker API的监听地址和端口号：

  dockerd \\\\    -H tcp://127.0.0.1:2375 \\\\    --ip=<ALLOWED_IP_ADDRESS> \\\\    --ip=<ANOTHER_ALLOWED_IP_ADDRESS> \\\\    --ip=<...> \\\\    --iptables=true \\\\    --iptables-chain=DOCKER-API \\\\    --iptables-rule=\\\'--proto tcp --dport 2375 -j DOCKER-API\\\' \\\\    --iptables-rule=\\\'--proto tcp --dport 2376 -j DOCKER-API\\\' \\\\    --iptables-rule=\\\'--proto tcp --dport 2377 -j DOCKER-API\\\'

参数说明：

• -H：Docker API的监听地址和端口号

• --ip：指定允许访问的IP地址，可以多次使用该选项来指定多个IP地址

• --iptables=true：启用iptables规则

• --iptables-chain=DOCKER-API：指定iptables规则的链名称

• --iptables-rule：指定iptables规则的内容，可以多次使用该选项来指定多个iptables规则

Step 2：配置iptables规则

接下来需要配置iptables规则以便将允许访问的IP地址和端口添加到iptables规则中，我们可以使用以下命令来添加iptables规则：

$ iptables -N DOCKER-API$ iptables -A DOCKER-API -s <ALLOWED_IP_ADDRESS> -j ACCEPT$ iptables -A DOCKER-API -s <ANOTHER_ALLOWED_IP_ADDRESS> -j ACCEPT$ iptables -A DOCKER-API -j DROP

命令说明：

• iptables -N DOCKER-API：创建一个名为DOCKER-API的新链

• iptables -A DOCKER-API -s <ALLOWED_IP_ADDRESS> -j ACCEPT：添加一个允许访问的IP地址到DOCKER-API链中

• iptables -A DOCKER-API -j DROP：将所有其他IP地址的访问都拒绝

Step 3：测试基于IP地址和端口的访问控制

现在可以使用Docker客户端连接到Docker API并测试基于IP地址和端口的访问控制机制是否正常工作，可以使用以下命令来测试，如果返回结果正常，则表示基于IP地址和端口的访问控制机制已经成功启用

$ docker -H tcp://<ALLOWED_IP_ADDRESS>:2375 info

日志记录

Docker API支持日志记录机制，可以记录所有的API请求和响应信息并将其保存到Docker引擎的日志文件中，日志记录可以帮助管理员追踪和分析Docker API的使用情况以及发现和解决安全问题，下面是一个使用日志记录机制的Docker API示例：

Step 1：配置Docker引擎的日志记录

首先需要配置Docker引擎的日志记录以便记录Docker引擎的操作、容器的状态、事件的信息等，我们可以使用以下命令来启动Docker引擎并将日志输出到指定的文件中：

$ dockerd \\\\    --log-driver=json-file \\\\    --log-opt max-file=5 \\\\    --log-opt max-size=10m \\\\    --log-opt labels=docker \\\\    --log-opt env=NODE \\\\    --log-opt env=DEV \\\\    --log-opt env=PROD \\\\    -H tcp://0.0.0.0:2375

参数说明：

• --log-driver=json-file：指定使用json-file作为日志记录驱动

• --log-opt max-file=5：指定最多保存5个日志文件

• --log-opt max-size=10m：指定每个日志文件的最大大小为10MB

• --log-opt labels=docker：指定记录具有docker标签的日志条目

• --log-opt env=NODE、--log-opt env=DEV、--log-opt env=PROD：指定只记录指定环境变量的日志条目

• -H tcp://0.0.0.0:2375：Docker API的监听地址和端口号

Step 2：查看Docker引擎的日志记录

接下来可以使用以下命令来查看Docker引擎的日志记录

$ journalctl -u docker.service -f

Step 3：查看容器的日志记录

除了记录Docker引擎的操作、事件等信息外，Docker API还可以记录容器的状态、日志等信息，可以使用以下命令来查看容器的日志记录，下面的命令会输出容器的日志信息，包括容器启动的日志、应用程序的输出等

$ docker logs <CONTAINER_NAME>

使用实例

系统信息

curl -X GET http://192.168.17.140:2375/info

版本信息

curl -X GET http://192.168.17.140:2375/version

容器列表

获取所有容器的清单：

curl http://192.168.17.140:2375/containers/json

容器信息

curl http://192.168.17.140:2375/containers/18729864daa3/json

进程列表

curl http://192.168.17.140:2375/containers/18729864daa3/top

镜像列表

curl -X GET http://192.168.17.140:2375/images/json

镜像信息

curl -X GET http://192.168.17.140:2375/images/c059bfaa849c/json

参考链接

https://docs.docker.com/engine/api/v1.29/