Docker 指南

community.docker 集合提供了几个用于编排 Docker 容器和 Docker Swarm 的模块和插件。

要求 

community.docker 中的大多数模块和插件都需要 Docker Python SDK。SDK 需要安装在执行模块和插件的机器上，并且需要安装模块和插件所执行的 Python 版本。您可以使用 community.general.python_requirements_info 模块来确保 Docker Python SDK 安装在正确的机器上，并且使用 Ansible 使用的 Python 版本。

请注意，插件（清单插件和连接插件）始终在 Ansible 本身的上下文中执行。如果您使用需要 Docker Python SDK 的插件，则需要在运行 ansible 或 ansible-playbook 的机器上安装它，并且安装的版本需要是 Ansible 使用的 Python 解释器版本。要查看使用哪个 Python，请运行 ansible --version。

您可以按照以下方式为 Python 3.6 或更高版本安装 Docker Python SDK

$ pip install docker

对于 Python 2.7，您需要使用 2.0.0 到 4.4.4 之间的版本，因为 Docker 的 Python 包在 5.0.0 中删除了对 Python 2.7 的支持。您可以按照以下方式安装特定版本的 Docker Python SDK

$ pip install 'docker==4.4.4'

请注意，在 2.0.0 版本之前，Docker Python SDK 在 PyPi 上被称为 docker-py。请避免安装这个非常旧的版本，并确保不要同时安装 docker 和 docker-py。同时安装两者会导致安装损坏。如果发生这种情况，Ansible 会检测到它并通知您。如果发生这种情况，您必须卸载两者并重新安装正确的版本。如有疑问，请始终安装 docker，而不要安装 docker-py。

连接到 Docker API 

您可以使用传递给每个任务的参数或设置环境变量来连接到本地或远程 API。优先级顺序是命令行参数，然后是环境变量。如果未找到命令行选项或环境变量，Ansible 将使用参数下提供的默认值。

参数

大多数插件和模块可以通过以下参数配置

docker_host
用于连接到 Docker API 的 URL 或 Unix 套接字路径。默认为 unix:///var/run/docker.sock。要连接到远程主机，请提供 TCP 连接字符串（例如：tcp://192.0.2.23:2376）。如果使用 TLS 加密与 API 的连接，则模块会自动将连接 URL 中的 tcp 替换为 https。

api_version
在 Docker 主机上运行的 Docker API 版本。默认为安装的 Docker Python SDK 支持的最新 API 版本。

timeout
等待 API 响应的最大时间（以秒为单位）。默认为 60 秒。

tls
通过使用 TLS 而不验证 Docker 主机服务器的真实性来保护与 API 的连接。默认为 false。

validate_certs
通过使用 TLS 并验证 Docker 主机服务器的真实性来保护与 API 的连接。默认为 false。

ca_path
通过提供 CA 证书文件的路径，在使用服务器验证时使用 CA 证书。

cert_path
客户端 TLS 证书文件的路径。

key_path
客户端 TLS 密钥文件的路径。

tls_hostname
在验证 Docker 主机服务器的真实性时，请提供服务器的预期名称。默认为 localhost。

ssl_version
提供有效的 SSL 版本号。默认值由 Docker Python SDK 确定。

此选项不适用于基于 CLI 的插件。它主要用于旧系统，应避免使用。

模块默认组

为了避免在每个任务中为所有模块指定通用参数，您可以使用 community.docker.docker 模块默认组，或其短名称 docker。

注意

模块默认组仅适用于模块，不适用于插件（连接和清单插件）。

以下示例展示了如何在 playbook 中使用模块默认组

---
- name: Pull and image and start the container
  hosts: localhost
  gather_facts: false
  module_defaults:
    group/community.docker.docker:
      # Select Docker Daemon on other host
      docker_host: tcp://192.0.2.23:2376
      # Configure TLS
      tls: true
      validate_certs: true
      tls_hostname: docker.example.com
      ca_path: /path/to/cacert.pem
      # Increase timeout
      timeout: 120
  tasks:
    - name: Pull image
      community.docker.docker_image_pull:
        name: python
        tag: 3.12

    - name: Start container
      community.docker.docker_container:
        cleanup: true
        command: python --version
        detach: false
        image: python:3.12
        name: my-python-container
        output_logs: true

    - name: Show output
      ansible.builtin.debug:
        msg: "{{ output.container.Output }}"

在这里，两个 community.docker 任务将使用为模块默认组设置的选项。

环境变量

您还可以通过设置以下环境变量来控制插件和模块如何连接到 Docker API。

对于插件，必须为 Ansible 本身运行的环境设置它们。对于模块，必须为模块执行的环境设置它们。对于在远程计算机上运行的模块，必须为用于执行模块的用户在该计算机上设置环境变量。

DOCKER_HOST: 用于连接到 Docker API 的 URL 或 Unix 套接字路径。

DOCKER_API_VERSION: 在 Docker 主机上运行的 Docker API 版本。默认为 Python 的 Docker SDK 支持的最新 API 版本。

DOCKER_TIMEOUT: 等待 API 响应的最大时间（以秒为单位）。

DOCKER_CERT_PATH: 包含客户端证书、客户端密钥和 CA 证书的目录路径。

DOCKER_SSL_VERSION: 提供有效的 SSL 版本号。

DOCKER_TLS: 通过使用 TLS 加密与 API 的连接，而不验证 Docker 主机的真实性。

DOCKER_TLS_HOSTNAME: 在验证 Docker 主机的真实性时，使用此主机名与主机的证书进行比较。

DOCKER_TLS_VERIFY: 通过使用 TLS 加密与 API 的连接并验证 Docker 主机的真实性。

普通 Docker 守护进程：镜像、网络、卷和容器 

为了使用普通的 Docker 守护进程（即没有 Swarm），可以使用连接插件、清单插件和多个模块

docker 连接插件
community.docker.docker 连接插件使用 Docker CLI 工具连接到 Docker 容器并在其中执行模块。它本质上是包装了 docker exec 和 docker cp。 ansible.posix.synchronize 模块支持此连接插件。

docker_api 连接插件
community.docker.docker_api 连接插件直接与 Docker 守护进程通信，以连接到 Docker 容器并在其中执行模块。

docker_containers 清单插件
community.docker.docker_containers 清单插件允许您将 Docker 守护进程中的 Docker 容器动态添加到 Ansible 清单中。有关动态清单的详细信息，请参阅使用动态清单。

docker 清单脚本已弃用。请改用清单插件。清单插件有多个兼容性选项。如果您需要从多个 Docker 守护进程收集 Docker 容器，则需要将每个 Docker 守护进程添加为单独的清单源。

docker_host_info 模块
community.docker.docker_host_info 模块允许您检索有关 Docker 守护进程的信息，例如所有容器、镜像、卷、网络等等。

docker_login 模块
community.docker.docker_login 模块允许您登录和注销远程注册表，例如 Docker Hub 或私有注册表。它提供了与 docker login 和 docker logout CLI 命令类似的功能。

docker_prune 模块
community.docker.docker_prune 模块允许您修剪不再需要的容器、镜像、卷等等。它提供了与 docker prune CLI 命令类似的功能。

docker_image 模块
community.docker.docker_image 模块提供对镜像的完全控制，包括：构建、拉取、推送、标记和删除。

docker_image_build
community.docker.docker_image_build 模块允许您使用 Docker buildx 构建 Docker 镜像。

docker_image_export 模块
community.docker.docker_image_export 模块允许您导出（归档）镜像。

docker_image_info 模块
community.docker.docker_image_info 模块允许您列出和检查镜像。

docker_image_load
community.docker.docker_image_load 模块允许您从 tarball 导入一个或多个镜像。

docker_image_pull
community.docker.docker_image_pull 模块允许您从注册表拉取 Docker 镜像。

docker_image_push
community.docker.docker_image_push 模块允许您将 Docker 镜像推送到注册表。

docker_image_remove
community.docker.docker_image_remove 模块允许您从 Docker 守护进程中删除和/或取消标记 Docker 镜像。

docker_image_tag
community.docker.docker_image_tag 模块允许您使用其他名称和/或标记标记 Docker 镜像。

docker_network 模块
community.docker.docker_network 模块提供对 Docker 网络的完全控制。

docker_network_info 模块
community.docker.docker_network_info 模块允许您检查 Docker 网络。

docker_volume_info 模块
community.docker.docker_volume_info 模块提供对 Docker 卷的完全控制。

docker_volume 模块
community.docker.docker_volume 模块允许您检查 Docker 卷。

docker_container 模块
community.docker.docker_container 模块通过提供创建、更新、停止、启动和销毁 Docker 容器的功能来管理容器生命周期。

docker_container_copy_into
community.docker.docker_container_copy_into 模块允许您将文件从控制节点复制到容器中。

docker_container_exec
community.docker.docker_container_exec 模块允许您在正在运行的容器中执行命令。

docker_container_info 模块
community.docker.docker_container_info 模块允许您检查 Docker 容器。

docker_plugin
community.docker.docker_plugin 模块允许您管理 Docker 插件。

Docker Compose 

Docker Compose v2

有两个模块用于处理 Docker compose 项目

community.docker.docker_compose_v2
community.docker.docker_compose_v2 模块允许您使用现有的 Docker compose 文件来协调单个 Docker 守护进程或 Swarm 上的容器。

community.docker.docker_compose_v2_pull
community.docker.docker_compose_v2_pull 模块允许您拉取 Docker compose 项目。

这些模块使用 Docker CLI “compose” 插件 (docker compose)，因此需要访问 Docker CLI 工具。除了 CLI 工具及其 Docker Compose 插件之外，不需要其他要求。

Docker Compose v1

已弃用的 community.docker.docker_compose 模块允许您使用现有的 Docker compose 文件来协调单个 Docker 守护进程或 Swarm 上的容器。此模块使用过时的 Docker Compose 1.x 版本（已终止生命周期）。它主要用于仍必须使用该版本的 Docker Compose 的旧系统。该模块已弃用，将从 community.docker 4.0.0 中删除。 请改用 Docker Compose v2 模块。

您需要在远程计算机上安装旧的 Python docker-compose 才能使用 Docker Compose v1 模块。

Swarm 管理

提供了一个清单插件和几个模块来管理 Docker Swarm

docker_swarm 清单插件
community.docker.docker_swarm 清单插件允许您动态地将所有 Docker Swarm 节点添加到您的 Ansible 清单中。

docker_swarm 模块
community.docker.docker_swarm 模块允许您全局配置 Docker Swarm 管理器节点来加入和离开 swarm，并更改 Docker Swarm 配置。

docker_swarm_info 模块
community.docker.docker_swarm_info 模块允许您检索关于 Docker Swarm 的信息。

docker_node 模块
community.docker.docker_node 模块允许您管理 Docker Swarm 节点。

docker_node_info 模块
community.docker.docker_node_info 模块允许您检索关于 Docker Swarm 节点的信息。

配置管理

community.docker 集合提供了管理 Docker Swarm 配置和密钥的模块

docker_config 模块
community.docker.docker_config 模块允许您创建和修改 Docker Swarm 配置。

docker_secret 模块
community.docker.docker_secret 模块允许您创建和修改 Docker Swarm 密钥。

Swarm 服务

可以使用 community.docker.docker_swarm_service 模块创建和更新 Docker Swarm 服务，并且可以使用 community.docker.docker_swarm_service_info 模块查询有关它们的信息。

Docker 指南

要求 

连接到 Docker API 

参数

模块默认组

环境变量

普通 Docker 守护进程：镜像、网络、卷和容器 

Docker Compose 

Docker Compose v2

Docker Compose v1

Docker Machine 

Docker Swarm 堆栈 

Docker Swarm 

Swarm 管理

配置管理

Swarm 服务

Docker 指南

要求

连接到 Docker API

参数

模块默认组

环境变量

普通 Docker 守护进程：镜像、网络、卷和容器

Docker Compose

Docker Compose v2

Docker Compose v1

Docker Machine

Docker Swarm 堆栈

Docker Swarm

Swarm 管理

配置管理

Swarm 服务

要求 

连接到 Docker API 

普通 Docker 守护进程：镜像、网络、卷和容器 

Docker Compose 

Docker Machine 

Docker Swarm 堆栈 

Docker Swarm 