Week 04: 模块化重构与 Collection 生态

# 初始化一个符合 Galaxy 标准的 Role
ansible-galaxy role init my_custom_role

# 生成的目录结构
my_custom_role/
├── defaults/
│   └── main.yml
├── files/
├── handlers/
│   └── main.yml
├── meta/
│   └── main.yml
├── tasks/
│   └── main.yml
├── templates/
├── tests/
│   ├── inventory
│   └── test.yml
├── vars/
│   └── main.yml
└── README.md

# tasks/main.yml
---
- name: Include OS-specific variables
  include_vars: "{{ item }}"
  with_first_found:
    - "{{ ansible_facts['distribution'] }}_{{ ansible_facts['distribution_major_version'] }}.yml"
    - "{{ ansible_facts['os_family'] }}.yml"
    - "default.yml"

- name: Include OS-specific tasks
  include_tasks: "{{ item }}"
  with_first_found:
    - "install_{{ ansible_facts['os_family'] | lower }}.yml"
    - "install_default.yml"

- name: Include common configuration
  import_tasks: configure.yml

- name: Include verification tasks
  import_tasks: verify.yml

roles/nginx/
├── tasks/
│   ├── main.yml
│   ├── install_redhat.yml
│   ├── install_debian.yml
│   ├── configure.yml
│   └── verify.yml
├── vars/
│   ├── RedHat.yml
│   ├── Debian.yml
│   └── default.yml
└── templates/
    └── nginx.conf.j2

# tasks/main.yml - 路由入口
---
- name: Preflight checks
  import_tasks: preflight.yml
  tags: [preflight]

- name: Install packages
  import_tasks: install.yml
  tags: [install]

- name: Configure application
  import_tasks: configure.yml
  tags: [configure]

- name: Manage service
  import_tasks: service.yml
  tags: [service]

- name: Verify deployment
  import_tasks: verify.yml
  tags: [verify]

# defaults/main.yml - 公开 API
---
nginx_http_port: 80
nginx_https_port: 443
nginx_worker_processes: auto
nginx_worker_connections: 1024
nginx_client_max_body_size: "10m"
nginx_keepalive_timeout: 65

nginx_enable_ssl: false
nginx_ssl_certificate: ""
nginx_ssl_certificate_key: ""

nginx_upstreams: []
# - name: backend
#   servers:
#     - address: 192.168.1.10
#       port: 8080
#       weight: 1

nginx_vhosts: []
# - server_name: example.com
#   root: /var/www/html
#   index: index.html

nginx_extra_configs: []

# vars/RedHat.yml - 私有常量
---
nginx_package_name: nginx
nginx_service_name: nginx
nginx_config_dir: /etc/nginx
nginx_log_dir: /var/log/nginx
nginx_user: nginx
nginx_group: nginx

# tasks/preflight.yml - 前置检查
---
- name: Check if ports are available
  wait_for:
    port: "{{ item }}"
    state: stopped
    timeout: 1
  loop:
    - "{{ nginx_http_port }}"
    - "{{ nginx_https_port }}"
  ignore_errors: yes
  register: port_check

- name: Fail if ports are in use
  fail:
    msg: "Port {{ item.item }} is already in use"
  loop: "{{ port_check.results }}"
  when: item.failed is defined and not item.failed
  loop_control:
    label: "{{ item.item }}"

- name: Gather disk space
  shell: df -m / | tail -1 | awk '{print $4}'
  register: disk_space
  changed_when: false

- name: Ensure sufficient disk space (minimum 500MB)
  assert:
    that:
      - disk_space.stdout | int > 500
    fail_msg: "Insufficient disk space: {{ disk_space.stdout }}MB available, 500MB required"

# tasks/install.yml - 安装逻辑
---
- name: Install NGINX package
  package:
    name: "{{ nginx_package_name }}"
    state: present
  notify: Restart nginx

- name: Install SSL dependencies
  package:
    name:
      - openssl
      - python3-cryptography
    state: present
  when: nginx_enable_ssl | bool

# tasks/configure.yml - 配置生成
---
- name: Ensure configuration directories exist
  file:
    path: "{{ item }}"
    state: directory
    owner: root
    group: root
    mode: '0755'
  loop:
    - "{{ nginx_config_dir }}/conf.d"
    - "{{ nginx_config_dir }}/sites-available"
    - "{{ nginx_config_dir }}/sites-enabled"

- name: Deploy main NGINX configuration
  template:
    src: nginx.conf.j2
    dest: "{{ nginx_config_dir }}/nginx.conf"
    owner: root
    group: root
    mode: '0644'
    validate: "nginx -t -c %s"
  notify: Reload nginx

- name: Deploy virtual host configurations
  template:
    src: vhost.conf.j2
    dest: "{{ nginx_config_dir }}/sites-available/{{ item.server_name }}.conf"
    owner: root
    group: root
    mode: '0644'
  loop: "{{ nginx_vhosts }}"
  notify: Reload nginx

- name: Enable virtual hosts
  file:
    src: "{{ nginx_config_dir }}/sites-available/{{ item.server_name }}.conf"
    dest: "{{ nginx_config_dir }}/sites-enabled/{{ item.server_name }}.conf"
    state: link
  loop: "{{ nginx_vhosts }}"
  notify: Reload nginx

# tasks/verify.yml - 验证逻辑
---
- name: Verify NGINX configuration syntax
  command: nginx -t
  register: nginx_syntax_check
  changed_when: false

- name: Wait for NGINX to be listening
  wait_for:
    port: "{{ nginx_http_port }}"
    state: started
    timeout: 30

- name: Verify NGINX responds to HTTP request
  uri:
    url: "http://localhost:{{ nginx_http_port }}/"
    status_code: [200, 301, 302, 403, 404]
  register: http_check
  retries: 3
  delay: 5

# handlers/main.yml
---
- name: Restart nginx
  service:
    name: "{{ nginx_service_name }}"
    state: restarted
  listen: "Restart nginx"

- name: Reload nginx
  service:
    name: "{{ nginx_service_name }}"
    state: reloaded
  listen: "Reload nginx"

# meta/main.yml
---
galaxy_info:
  author: Infrastructure Team
  description: Production-grade NGINX deployment role
  company: ACME Corp
  license: MIT
  
  min_ansible_version: "2.12"
  
  platforms:
    - name: EL
      versions:
        - "8"
        - "9"
    - name: Ubuntu
      versions:
        - focal    # 20.04
        - jammy    # 22.04
    - name: Debian
      versions:
        - bullseye  # 11
        - bookworm  # 12
  
  galaxy_tags:
    - web
    - nginx
    - loadbalancer
    - proxy

dependencies:
  # 简单依赖: 仅指定 Role 名
  - common-security
  
  # 带版本约束的依赖
  - role: common-monitoring
    version: ">=2.0.0,<3.0.0"
  
  # 带变量传递的依赖
  - role: common-firewall
    vars:
      firewall_allowed_ports:
        - 80
        - 443
  
  # 条件依赖
  - role: ssl-certificates
    when: nginx_enable_ssl | bool

ERROR! A recursive loop was detected involving role 'role_a' -> 'role_b' -> 'role_a'

# 不在 meta/main.yml 中声明依赖
# 而是在 tasks 中动态加载
- name: Conditionally include firewall role
  include_role:
    name: common-firewall
  vars:
    firewall_ports: "{{ my_ports }}"
  when: configure_firewall | bool

# requirements.yml
---
roles:
  - name: nginx
    src: git+https://gitlab.example.com/ansible/roles/nginx.git
    version: v2.3.1  # 精确版本锁定
    
  - name: common-security
    src: git+https://gitlab.example.com/ansible/roles/common-security.git
    version: ">=1.5.0,<2.0.0"  # 范围约束

# 安装依赖
ansible-galaxy install -r requirements.yml -p roles/

# 强制更新 (覆盖本地)
ansible-galaxy install -r requirements.yml -p roles/ --force

- name: Remove server from load balancer before maintenance
  haproxy:
    state: disabled
    host: "{{ inventory_hostname }}"
    socket: /var/lib/haproxy/stats
  delegate_to: "{{ groups['loadbalancers'][0] }}"

- name: Perform maintenance on server
  package:
    name: "*"
    state: latest

- name: Re-add server to load balancer
  haproxy:
    state: enabled
    host: "{{ inventory_hostname }}"
    socket: /var/lib/haproxy/stats
  delegate_to: "{{ groups['loadbalancers'][0] }}"

# 方式 1: delegate_to localhost
- name: Generate local report
  template:
    src: report.j2
    dest: /tmp/deploy_report_{{ inventory_hostname }}.txt
  delegate_to: localhost
  become: no

# 方式 2: local_action (语法糖)
- name: Send deployment notification
  local_action:
    module: slack
    msg: "Deployed {{ app_version }} to {{ inventory_hostname }}"
    channel: "#deployments"
    token: "{{ slack_token }}"

- name: Initialize database schema
  command: /usr/bin/db_migrate.sh
  run_once: true
  delegate_to: "{{ groups['database'][0] }}"

- name: Generate shared SSL certificate
  command: certbot certonly --webroot -w /var/www/html -d example.com
  run_once: true
  delegate_to: "{{ groups['web'][0] }}"
  register: cert_result

- name: Distribute certificate to all nodes
  copy:
    src: /etc/letsencrypt/live/example.com/
    dest: /etc/ssl/certs/example.com/
    remote_src: yes
  delegate_to: "{{ groups['web'][0] }}"

- name: Rolling update web servers
  hosts: web_servers
  serial: 2  # 每次处理 2 台
  # 或者使用百分比
  # serial: "25%"
  # 或者使用递增策略
  # serial:
  #   - 1      # 第一批 1 台 (金丝雀)
  #   - 5      # 第二批 5 台
  #   - "50%"  # 后续每批 50%
  
  tasks:
    - name: Remove from LB
      haproxy:
        state: disabled
        host: "{{ inventory_hostname }}"
      delegate_to: lb01
    
    - name: Update application
      package:
        name: myapp
        state: latest
    
    - name: Wait for health check
      uri:
        url: "http://localhost:8080/health"
        status_code: 200
      retries: 10
      delay: 5
    
    - name: Add back to LB
      haproxy:
        state: enabled
        host: "{{ inventory_hostname }}"
      delegate_to: lb01

# 旧式写法 (仍兼容, 但不推荐)
- name: Install package
  apt:
    name: nginx
    state: present

# 新式写法 (推荐)
- name: Install package
  ansible.builtin.apt:
    name: nginx
    state: present

# 第三方 Collection
- name: Create AWS EC2 instance
  amazon.aws.ec2_instance:
    name: my-instance
    instance_type: t3.micro

# 初始化 Collection
ansible-galaxy collection init my_org.infra_utils

# 生成的目录结构
my_org/infra_utils/
├── docs/
├── galaxy.yml          # 元数据清单
├── meta/
│   └── runtime.yml     # 运行时配置 (重定向, 弃用声明)
├── plugins/
│   ├── modules/        # 自定义模块
│   ├── lookup/         # Lookup 插件
│   ├── filter/         # Filter 插件
│   ├── callback/       # Callback 插件
│   └── inventory/      # 动态 Inventory 插件
├── roles/              # 内含 Roles
├── playbooks/          # 可复用 Playbooks
└── README.md

# galaxy.yml
---
namespace: my_org
name: infra_utils
version: 1.2.0
readme: README.md

authors:
  - Infrastructure Team <infra@example.com>

description: |
  Production-grade infrastructure automation utilities.
  Includes modules for custom API integration and advanced filters.

license_file: LICENSE

tags:
  - infrastructure
  - automation
  - utilities

dependencies:
  ansible.utils: ">=2.0.0"
  community.general: ">=5.0.0,<7.0.0"
  
repository: https://gitlab.example.com/ansible/collections/infra_utils
documentation: https://docs.example.com/ansible/infra_utils
homepage: https://example.com/ansible
issues: https://gitlab.example.com/ansible/collections/infra_utils/-/issues

build_ignore:
  - "*.pyc"
  - "__pycache__"
  - ".git"
  - "tests/"

# meta/runtime.yml
---
requires_ansible: ">=2.12.0"

plugin_routing:
  modules:
    # 模块重命名: 旧名称 -> 新名称
    old_module_name:
      redirect: my_org.infra_utils.new_module_name
    
    # 弃用声明
    deprecated_module:
      deprecation:
        removal_version: "2.0.0"
        warning_text: |
          This module is deprecated. Use 'new_module' instead.
    
    # 移除声明
    removed_module:
      tombstone:
        removal_version: "1.5.0"
        warning_text: |
          This module was removed. Please use 'alternative' instead.

action_groups:
  # 定义模块组, 便于批量应用配置
  my_infra:
    - custom_api
    - custom_db
    - custom_notify

# ansible.cfg
[galaxy]
server_list = automation_hub, galaxy

[galaxy_server.automation_hub]
url = https://hub.example.com/api/galaxy/
token = <your-token>

[galaxy_server.galaxy]
url = https://galaxy.ansible.com/

# requirements.yml
---
collections:
  - name: my_org.infra_utils
    source: git+https://gitlab.example.com/ansible/collections/infra_utils.git
    type: git
    version: v1.2.0

  - name: my_org.security
    source: https://nexus.example.com/repository/ansible-collections/
    type: galaxy
    version: ">=2.0.0"

roles:
  - name: nginx
    src: git+https://gitlab.example.com/ansible/roles/nginx.git
    version: v3.1.0

# .gitlab-ci.yml
stages:
  - lint
  - test
  - build
  - publish

variables:
  COLLECTION_NAMESPACE: my_org
  COLLECTION_NAME: infra_utils

lint:
  stage: lint
  script:
    - ansible-lint roles/
    - yamllint .

test:
  stage: test
  script:
    - ansible-galaxy collection build --force
    - ansible-galaxy collection install *.tar.gz -p ./test_collections
    - ansible-test sanity --docker

build:
  stage: build
  script:
    - |
      # 从 git tag 提取版本号
      VERSION=$(git describe --tags --abbrev=0 | sed 's/v//')
      sed -i "s/^version:.*/version: ${VERSION}/" galaxy.yml
    - ansible-galaxy collection build
  artifacts:
    paths:
      - "*.tar.gz"
  only:
    - tags

publish:
  stage: publish
  script:
    - |
      ansible-galaxy collection publish \
        --api-key "${AUTOMATION_HUB_TOKEN}" \
        --server automation_hub \
        *.tar.gz
  only:
    - tags
  when: manual

# requirements.lock.yml (生成并提交至 Git)
---
collections:
  - name: ansible.netcommon
    version: 5.1.2
    source: https://galaxy.ansible.com
  - name: community.general
    version: 7.3.0
    source: https://galaxy.ansible.com
  - name: my_org.infra_utils
    version: 1.2.0
    source: https://gitlab.example.com/ansible/collections/infra_utils

roles:
  - name: nginx
    version: 3.1.0
    src: git+https://gitlab.example.com/ansible/roles/nginx.git

# 安装锁定版本
ansible-galaxy collection install -r requirements.lock.yml --force
ansible-galaxy role install -r requirements.lock.yml --force

# 更新锁定文件
./scripts/update-deps.sh > requirements.lock.yml

#!/bin/bash
# scripts/impact-analysis.sh

# 查找所有引用该 Role 的 Playbook
grep -r "role: nginx" playbooks/ inventory/

# 查找所有依赖该 Role 的其他 Roles
find roles/ -name "main.yml" -path "*/meta/*" -exec grep -l "nginx" {} \;

# 检查变量兼容性
diff <(git show main:roles/nginx/defaults/main.yml) \
     roles/nginx/defaults/main.yml