nickjj.docker

什么是 ansible-docker？

这是一个 Ansible 角色，用于：

• 安装 Docker（支持版本、频道和版本固定）
• 安装 Docker Compose v2 和 / 或 Docker Compose v1（支持版本固定）
• 安装 docker PIP 包，以使 Ansible 的 docker_* 模块正常工作
• 管理 Docker 注册中心登录凭据
• 配置一个或多个用户无需 root 权限即可运行 Docker
• 配置 Docker 守护进程的选项和环境变量
• 配置定时任务以运行 Docker 清理命令

为什么要使用这个角色？

如果你像我一样，可能会热爱 Docker。这个角色提供了一切必要的工具，让你快速启动一个准备投入生产的 Docker 主机。

顺便说一下，如果你不知道 Docker是什么，或者想成为它的专家，可以查看 Dive into Docker: The Complete Docker Course for Developers。

支持的平台

• Ubuntu 20.04 LTS (Focal Fossa)
• Ubuntu 22.04 LTS (Jammy Jellyfish)
• Debian 11 (Bullseye)
• Debian 12 (Bookworm)

之前的版本可能会工作，也可能不工作，但不被官方支持。

您正在查看主分支的文档，它可能领先于最新版本。切换到最新版本。

快速开始

我的所有角色的理念是让开始变得简单，但又提供几乎所有内容的定制方式。

默认配置了什么？

将安装最新稳定版本的 Docker CE 和 Docker Compose v2，每周会进行一次 Docker 磁盘清理，并将 Docker 容器日志发送到 journald。

示例剧本

---

# docker.yml

- name: 示例
  hosts: "所有"
  become: true

  roles:
    - role: "nickjj.docker"
      tags: ["docker"]

使用：ansible-playbook docker.yml

安装

$ ansible-galaxy install nickjj.docker

默认角色变量

安装 Docker

渠道

你想使用 "stable" 还是 "test" 渠道？你可以添加多个（顺序重要）。

docker__channel: ["stable"]

版本

• 设置为""时，将安装当前最新版本的 Docker
• 设置为特定版本时，将安装该特定版本的 Docker

docker__version: ""

# 例如，锁定为 25.0。
docker__version: "25.0"

# 例如，将其锁定为更精确的版本 25.0。
docker__version: "25.0.5"

版本后带有 * 的锁定表示，除非你锁定确切版本，否则将获得次要和安全补丁。

升级策略

• 设置为 "present"时，未来运行此角色不会安装更新版本（如果可用）
• 设置为 "latest"时，未来运行此角色会安装更新版本（如果可用）

docker__state: "present"

降级策略

降级的最简单方法是手动卸载 Docker 包，然后之后运行此角色并锁定你想要的特定 Docker 版本。

# 一个即席 Ansible 命令，用于停止并移除所有主机上的 Docker CE 包。
ansible all -m systemd -a "name=docker-ce state=stopped" \
  -m apt -a "name=docker-ce autoremove=true purge=true state=absent" -b

安装 Docker Compose v2

Docker Compose v2 将通过 Docker 管理的官方 docker-compose-plugin 安装。

版本

• 设置为""时，将安装当前最新版本的 Docker Compose v2
• 设置为特定版本时，将安装该特定版本的 Docker Compose v2

docker__compose_v2_version: ""

# 例如，锁定为 2.29。
docker__compose_v2_version: "2.29"

# 例如，锁定为更精确的版本 2.29.1。
docker__compose_v2_version: "2.29.1"

升级策略

它将重用同步中 Docker 部分解释的 docker__state 变量，规则相同。

降级策略

与 Docker 本身一样，卸载 Docker Compose v2 的最简单方法是手动运行以下命令，然后锁定特定 Docker Compose v2 版本。

# 一个即席 Ansible 命令，用于在所有主机上删除 Docker Compose 插件包。
ansible all -m apt -a "name=docker-compose-plugin autoremove=true purge=true state=absent" -b

安装 Docker Compose v1

默认情况下，此角色不安装 Docker Compose v1，因为它已被官方弃用，不再收到更新。不过该角色可以安装它。你只需要将 docker__pip_docker_compose_state 设置为 "present"，因为此角色默认设置为 absent。

技术上讲，两个版本可以一起安装，因为 v1 使用 docker-compose 访问，而 v2 使用 docker compose（注意缺少连字符）。

我建议你除非确实需要它，否则不要安装 v1。如果你决定安装，可以在下方配置安装的版本。如果没有设置要安装，这些版本将被忽略：

版本

• 设置为""时，将安装当前最新版本的 Docker Compose v1
• 设置为特定版本时，将安装该特定版本的 Docker Compose v1

docker__compose_version: ""

# 例如，锁定为 1.29。
docker__compose_version: "1.29"

# 例如，锁定为更精确的版本 1.29。
docker__compose_version: "1.29.2"

升级和降级策略将在本 README 的其他部分进行解释。

配置用户以无需 root 权限运行 Docker

要添加到 docker 组的用户列表。

请记住，这个用户需要已经存在，此角色不会创建它。如果你想创建用户，请查看我的 用户角色。

此角色默认不配置用户命名空间或任何其他安全特性。如果你在这里添加的用户可以通过 SSH 访问你的服务器，那么你实际上是在给他们 root 访问权限，因为他们可以在没有 sudo 的情况下运行 Docker，并在你的文件系统上的任何路径中进行卷挂载。

在受控环境中这是安全的，但与安全相关的任何内容，提前了解这些信息都是非常重要的。你可以使用后面解释的 docker__daemon_json 变量启用用户命名空间和任何其他选项。

# 默认尝试使用 sudo 用户，如果没有则回退为 root。
docker__users: ["{{ ansible_env.SUDO_USER | d('root') }}"]

# 例如，如果你想设置的用户不同于 sudo 用户。
docker__users: ["admin"]

配置 Docker 注册中心登录

登录到一个或多个 Docker 注册中心（例如 Docker Hub）。

# 你的登录凭据将保存在该用户的主目录中。
docker__login_become_user: "{{ docker__users | first | d('root') }}"

# 0 个或多个注册中心进行登录。
docker__registries:
  - #registry_url: "https://index.docker.io/v1/"
    username: "你的_docker_hub用户名"
    password: "你的_docker_hub密码"
    #email: "你的[email protected]"
    #reauthorize: false
    #config_path: "$HOME/.docker/config.json"
    #state: "present"
docker__registries: []

以开头的属性是必需的。*

• registry_url 默认值为 https://index.docker.io/v1/
• *username 是你的 Docker 注册中心用户名
• *password 是你的 Docker 注册中心密码
• email 默认不使用（并不是所有注册中心都使用它）
• reauthorize 默认设置为 false，当 true 时更新你的凭据
• config_path 默认值为你的 docker__login_become_user 的 $HOME 目录
• state 默认值为 "present"，当设置为 "absent"，登录将被移除

配置 Docker 守护进程选项（json）

在 /etc/docker/daemon.json 中将以默认 Docker 守护进程选项的形式出现。

docker__default_daemon_json: |
  "log-driver": "journald",
  "features": {
    "buildkit": true
  }

# 额外添加你自己的守护进程选项，而不覆盖默认选项。
# 它遵循与默认选项相同的格式，无需担心
# 以逗号开头。模板将根据需要添加逗号。
docker__daemon_json: ""

配置 Docker 守护进程选项（标志）

启动 Docker 守护进程时设置的标志不能在 daemon.json 文件中更改。Docker 默认设置为 -H unix://，这意味着该选项无法通过 json 选项进行更改。

通过按命令行的方式提供它们来添加或更改启动 Docker 守护进程的标志。

# 每个命令行标志应作为列表中的单独项目。
#
# 使用 18.09 之前的 Docker 版本？
#   你必须设置 `-H fd://` 而不是 `-H unix://`。
docker__daemon_flags:
  - "-H unix://"

如果你不在此处提供某种 -H 标志，Docker 将无法启动。

配置 Docker 守护进程环境变量

docker__daemon_environment: []

# 例如，以下是如何设置几个代理环境变量。
docker__daemon_environment:
  - "HTTP_PROXY=http://proxy.example.com:80"
  - "HTTPS_PROXY=https://proxy.example.com:443"

配置高级 systemd 指令

此角色允许 Docker 包管理其自己的 systemd 单元文件，并使用系统覆盖模式调整 Docker 守护进程标志和环境变量。

如果你知道自己在做什么，可以通过设置此变量来覆盖或补充任何 Docker 的 systemd 指令。你在这个字符串中放置的任何内容都会原样写入 /etc/systemd/system/docker.service.d/custom.conf。

docker__systemd_override: ""

配置与 Docker 相关的定时任务

默认情况下，这将在每周日午夜安全清理 Docker 使用的磁盘空间。

# `a` 移除未使用的映像（在生产环境中很有用）。
# `f` 强制它在不提示你同意的情况下发生。
docker__cron_jobs_prune_flags: "af"

# 控制 Docker 系统清理的调度。
docker__cron_jobs_prune_schedule: ["0", "0", "*", "*", "0"]

docker__cron_jobs:
  - name: "Docker 磁盘清理"
    job: "docker system prune -{{ docker__cron_jobs_prune_flags }} > /dev/null 2>&1"
    schedule: "{{ docker__cron_jobs_prune_schedule }}"
    cron_file: "docker-disk-clean-up"
    #user: "{{ (docker__users | first) | d('root') }}"
    #state: "present"

以开头的属性是必需的。*

• *name 是定时任务的描述
• *job 是在定时任务中运行的命令
• *schedule 是每周日午夜的标准定时任务格式
• *cron_file 将定时任务写入 /etc/cron.d 而不是某个用户的个人 crontab
• user 默认是第一个 docker__users 用户，或者如果不可用则为 root
• state 默认值为 "present"，设为 "absent" 时将移除该定时任务文件

配置 APT 包管理器

Docker 运行需要安装一些依赖项。你不应该需要编辑这些变量。

# 要安装的包列表。
docker__package_dependencies:
  - "apt-transport-https"
  - "ca-certificates"
  - "cron"
  - "gnupg2"
  - "software-properties-common"

# Ansible 与 Docker 识别 CPU 架构的方式不同。
docker__architecture_map:
  "x86_64": "amd64"
  "aarch64": "arm64"
  "aarch": "arm64"
  "armhf": "armhf"
  "armv7l": "armhf"

# Docker GPG 密钥 URL。
docker__apt_repository_url: "https://download.docker.com/linux/{{ ansible_distribution | lower }}"

# Docker GPG 密钥校验值。
docker__apt_key_checksum: "sha256:1500c1f56fa9e26b9b8f42452a553675796ade0807cdce11975eb98170b3a570"

# Docker 上游 APT 仓库。
docker__apt_repository: >
  deb [arch={{ docker__architecture_map[ansible_architecture] }}
  signed-by=/etc/apt/keyrings/docker.asc]
  {{ docker__apt_repository_url }}
  {{ ansible_distribution_release }} {{ docker__channel | join(' ') }}

使用 Virtualenv 和 PIP 安装 Python 包

配置 Virtualenv

为了避免污染服务器的 Python 版本，所有 PIP 包都将安装到你选择的 Virtualenv 中。

docker__pip_virtualenv: "/usr/local/lib/docker/virtualenv"

安装 PIP 及其依赖

此角色将安装 PIP，因为 Docker Compose v1 是通过 docker-compose PIP 包安装，而 Ansible 的 docker_* 模块使用 docker PIP 包。

docker__pip_dependencies:
  - "gcc"
  - "python3-setuptools"
  - "python3-dev"
  - "python3-pip"
  - "virtualenv"

安装 PIP 包

docker__default_pip_packages:
  - name: "docker"
    state: "{{ docker__pip_docker_state }}"
  - name: "docker-compose"
    version: "{{ docker__compose_version }}"
    path: "/usr/local/bin/docker-compose"
    src: "{{ docker__pip_virtualenv + '/bin/docker-compose' }}"
    state: "{{ docker__pip_docker_compose_state }}"

# 添加你的 PIP 包，属性与上面相同。
docker__pip_packages: []

以开头的属性是必需的。*

• *name 是包名
• version 是要安装的包版本（如果没有定义则为 ""）
• path 是符号链接的目标路径
• src 是要链接的源路径
• state 默认设置为 "present"，其他值可以为 "forcereinstall" 或 "absent"

PIP 包状态

• 设置为 "present"时，包将被安装，但未来不会更新
• 设置为 "forcereinstall"时，包将始终在未来的运行中重新安装和更新
• 设置为 "absent"时，包将被跳过或移除

docker__pip_docker_state: "present"
docker__pip_docker_compose_state: "absent"

与 Ansible 的 docker_* 模块配合使用

此角色使用 docker_login 登录到 Docker 注册中心，但你也可以在自己的角色中使用其他 docker_* 模块。除非你指示 Ansible 使用此角色的 Virtualenv，否则它们将无法工作。

在清单、剧本或任务级别，你需要设置 ansible_python_interpreter: "/usr/local/bin/python3-docker"。这之所以可行，是因为该角色会创建一个从 Virtualenv 的 Python 二进制文件到 python3-docker 的代理脚本。

你可以参考该角色的 docker_login 任务，了解如何在任务级别实现这一点。

许可证

MIT