Docker 指南

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

需求

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

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

您可以为 Python 3.6 或更高版本安装 Python 的 Docker SDK,方法如下:

$ pip install docker

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

$ pip install 'docker==4.4.4'

请注意,在 2.0.0 版本之前,Python 的 Docker SDK 在 PyPi 上称为 docker-py。请避免安装此非常旧的版本,并确保不要同时安装 dockerdocker-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 的版本。默认为已安装的 Python Docker SDK 支持的最新 API 版本。

timeout

等待 API 响应的最长时间(以秒为单位)。默认为 60 秒。

tls

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

validate_certs

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

ca_path

通过提供 CA 证书文件的路径来执行服务器验证时使用 CA 证书。

cert_path

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

key_path

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

tls_hostname

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

ssl_version

提供有效的 SSL 版本号。默认值由 Python 的 Docker 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 版本。默认为 Docker SDK for Python 支持的最新 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 execdocker 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 logindocker 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 模块。

要使用 Docker Compose v1 模块,需要在远程机器上安装旧版 Python docker-compose

Docker Machine

community.docker.docker_machine inventory 插件允许您动态地将 Docker Machine 主机添加到 Ansible 清单中。

Docker Swarm stack

community.docker.docker_stack 模块允许您控制 Docker Swarm stacks。可以使用community.docker.docker_stack_info 模块检索 Swarm stacks 信息,并可以使用community.docker.docker_stack_task_info 模块检索 Swarm stack 任务信息。

Docker Swarm

community.docker 集合提供了多个插件和模块来管理 Docker Swarms。

Swarm 管理

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

docker_swarm 清单插件

community.docker.docker_swarm inventory 插件允许您动态地将所有 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 模块查询有关它们的信息。