TADS-Boilerplate Ansible角色详解：如何编写可复用的Docker Swarm服务模板

TADS-Boilerplate Ansible角色详解：如何编写可复用的Docker Swarm服务模板

【免费下载链接】tads-boilerplate Terraform + Ansible + Docker Swarm boilerplate = DevOps on :fire::fire::fire: | Infrastructure as Code 项目地址: https://gitcode.com/gh_mirrors/ta/tads-boilerplate

TADS-Boilerplate是一个集成Terraform、Ansible和Docker Swarm的基础设施即代码(IaC)项目，通过Ansible角色实现Docker Swarm服务的自动化部署与管理。本文将详细解析项目中的docker-stack角色，帮助开发者快速掌握可复用Docker Swarm服务模板的编写方法。

图1：TADS-Boilerplate项目核心组件架构（Terraform+Ansible+Docker Swarm）

认识docker-stack角色：核心功能与目录结构

docker-stack角色是TADS-Boilerplate实现Docker Swarm服务编排的核心组件，位于项目的ansible/roles/docker-stack/目录下。该角色通过标准化的任务流程，实现了从配置文件渲染到服务部署的全自动化过程，主要功能包括：

• 管理Docker Swarm secrets
• 渲染服务配置模板
• 复制资源文件到目标节点
• 部署和更新Docker Stack

角色的典型目录结构如下：

docker-stack/
├── defaults/          # 默认变量定义
│   └── main.yml
├── tasks/             # 核心任务逻辑
│   └── main.yml
└── molecule/          # 测试用例
    └── default/
        └── stacks/    # 示例服务模板

编写可复用模板的关键：变量设计与目录规范

核心变量定义与使用

在defaults/main.yml中定义了模板渲染的关键变量，这些变量决定了服务模板的路径和资源位置：

docker_stack_directory_local_path: "stacks/{{ docker_stack_name }}"
docker_stack_yaml_local_path: "{{ docker_stack_directory_local_path }}/{{ docker_stack_name }}.yml.j2"
docker_stack_resources_directory_name: "resources"
docker_stack_resources_local_path: "{{ docker_stack_directory_local_path }}/{{ docker_stack_resources_directory_name }}"

通过这些变量，角色能够自动定位服务模板文件和相关资源，实现了模板的标准化和可复用性。

标准目录布局

遵循以下目录结构组织服务模板和资源，可确保docker-stack角色正确识别和处理：

stacks/
└── [服务名称]/           # 服务名称作为目录名
    ├── [服务名称].yml.j2  # 主模板文件
    └── resources/        # 资源文件目录（可选）
        ├── configs/      # 配置文件
        └── assets/       # 静态资源

项目中提供了三个示例模板，位于ansible/roles/docker-stack/molecule/default/stacks/目录下，分别展示了基础服务、带资源文件服务和带密钥服务的实现方式。

任务执行流程：从模板到部署的全自动化

docker-stack角色的任务执行流程定义在tasks/main.yml中，包含六个关键步骤，共同构成了服务部署的完整生命周期：

1. 管理Docker Secrets

- name: Create secrets
  docker_secret:
    name: "{{ item.name }}"
    data: "{{ item.data }}"
    state: present
  with_items: "{{ docker_stack_secrets }}"
  no_log: True

该任务根据docker_stack_secrets变量创建Docker Swarm密钥，no_log: True确保敏感信息不会被记录。

2. 创建配置目录

- name: Create stack configuration directory
  file:
    path: "~/.tads/stacks/{{ docker_stack_name }}"
    state: directory
    recurse: yes

在目标节点上创建标准化的配置目录，确保后续文件操作有统一的位置。

3. 渲染模板文件

- name: Copy stack YAML
  template:
    src: "{{ docker_stack_yaml_local_path }}"
    dest: "~/.tads/stacks/{{ docker_stack_name }}/{{ docker_stack_name }}.yml"

使用Jinja2模板引擎渲染服务配置文件，将变量替换为实际值。

4. 复制资源文件（可选）

- name: Test stack resources existance
  stat:
    path: "{{ docker_stack_resources_local_path }}"
  delegate_to: localhost
  register: stat_result

- name: Copy stack resources
  copy:
    src: "{{ docker_stack_resources_local_path }}"
    dest: "~/.tads/stacks/{{ docker_stack_name }}"
  when: stat_result.stat.exists

检测并复制资源文件到目标节点，只有当资源目录存在时才执行此步骤。

5. 部署Docker Stack

- name: Deploy stack
  docker_stack:
    state: present
    name: "{{ docker_stack_name }}"
    compose:
    - "~/.tads/stacks/{{ docker_stack_name }}/{{ docker_stack_name }}.yml"
  register: stack_deploy

使用docker_stack模块部署服务栈，register参数捕获部署结果以便后续处理。

6. 输出部署差异（可选）

- debug:
    var: stack_deploy.stack_spec_diff
  when: stack_deploy.changed

当服务配置发生变化时，输出配置差异，帮助开发者了解部署变更内容。

实战案例：三种典型服务模板的实现

1. 基础服务模板（simple_stack）

基础模板展示了最小化的服务定义，位于ansible/roles/docker-stack/molecule/default/stacks/simple_stack/目录。该模板仅包含必要的服务配置，适合简单的无状态服务。

2. 带资源文件的服务模板（stack_with_resources）

该模板演示了如何包含静态资源文件，通过resources目录提供服务运行所需的配置文件或数据。角色会自动检测并复制这些资源到目标节点。

3. 带密钥的服务模板（stack_with_secrets）

安全敏感的服务可以使用此模板，通过docker_stack_secrets变量定义需要创建的密钥，实现敏感信息的安全管理。在molecule/default/playbook.yml中可以找到密钥定义的示例：

docker_stack_secrets:
  - name: db_password
    data: "secret_password"

最佳实践：编写高质量服务模板的5个技巧

1. 合理使用变量

将环境相关配置定义为变量，通过group_vars或host_vars进行环境隔离，提高模板的灵活性。例如在ansible/group_vars/目录下定义不同环境的配置。

2. 模块化设计

将复杂服务拆分为多个模板文件，通过include或import机制组合，提高代码复用性。可参考项目中ansible/stacks/traefik/目录的实现方式。

3. 添加健康检查

在模板中为每个服务添加健康检查，确保服务部署后处于可用状态：

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost/health"]
  interval: 30s
  timeout: 10s
  retries: 3

4. 版本控制

为所有镜像指定明确的版本标签，避免使用latest标签导致部署不一致。

5. 测试驱动开发

使用Molecule测试框架验证模板的正确性，项目中的molecule/default/verify.yml提供了测试示例。

快速开始：使用现有模板部署服务

要使用docker-stack角色部署服务，只需执行以下步骤：

1. 克隆项目仓库：

   git clone https://gitcode.com/gh_mirrors/ta/tads-boilerplate
   

2. 在ansible/stacks/目录下创建新的服务模板目录

3. 编写服务模板文件和资源（如有需要）

4. 通过Ansible Playbook部署：

   ./scripts/commands/ansible-playbook.sh deploy.yml -e "docker_stack_name=your_stack_name"
   

通过docker-stack角色，开发者可以快速构建标准化、可复用的Docker Swarm服务模板，实现基础设施即代码的最佳实践。无论是简单的Web服务还是复杂的微服务架构，该角色都能提供一致且可靠的部署体验。

【免费下载链接】tads-boilerplate Terraform + Ansible + Docker Swarm boilerplate = DevOps on :fire::fire::fire: | Infrastructure as Code 项目地址: https://gitcode.com/gh_mirrors/ta/tads-boilerplate