基础设施即代码 / 系统课时

用 Template 渲染配置文件

用 Template 渲染配置文件

template 模块适合把环境差异、Inventory 变量和主机 Facts 组合成最终配置文件。本课以 Nginx 虚拟主机为例,完成变量设计、Jinja2 渲染、幂等下发与结果验证,并说明哪些值不应该直接写进模板。

学习目标

  • 使用 Jinja2 表达式把变量与主机 Facts 写入配置文件
  • 用 ansible.builtin.template 控制目标路径、权限和服务重载
  • 通过重复执行与远端检查验证模板任务的幂等性

划清模板与变量的职责

模板应该描述“配置长什么样”,环境差异则留在变量中。不要为生产、测试分别复制两份几乎相同的模板,否则字段新增时很容易只改到其中一份。Facts 适合注入主机名、地址、CPU 等机器属性,但不能假定所有 Fact 永远存在。

下面的模板生成一个 Nginx server 块。deploy_environment 和 nginx_listen_port 来自 Playbook 变量,主机名优先使用收集到的 FQDN,缺失时退回 inventory_hostname。

jinja2
server {
    listen {{ nginx_listen_port }};
    server_name {{ ansible_facts['fqdn'] | default(inventory_hostname, true) }};

    location / {
        return 200 "env={{ deploy_environment }} host={{ inventory_hostname }}";
    }
}

将它保存为 templates/ansible-demo.conf.j2。这是配置模板,不独立执行;真正的生效行为由后面的 template 任务完成。

渲染并触发服务重载

下面示例假设目标主机可由当前控制端 SSH 登录。Inventory 只需要定义 web 组;主机地址请替换为实际值。

ini
[web]
web1 ansible_host=<IP>

Playbook 先确保 Nginx 已安装,再把模板渲染到目标目录。只有模板内容、属主或权限实际变化时任务才会标记为 changed,并通知 handler 重载服务。

yaml
- name: Render nginx configuration
  hosts: web
  become: true
  gather_facts: true
  vars:
    # Environment differences remain data instead of being copied into templates.
    deploy_environment: production
    nginx_listen_port: 8080

  tasks:
    - name: Ensure nginx is installed
      ansible.builtin.package:
        name: nginx
        state: present

    - name: Render virtual host from Jinja2 template
      ansible.builtin.template:
        src: templates/ansible-demo.conf.j2
        dest: /etc/nginx/conf.d/ansible-demo.conf
        owner: root
        group: root
        mode: "0644"
      # Reload only when the rendered file actually changes.
      notify: Reload nginx

    - name: Ensure nginx is running
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true

  handlers:
    - name: Reload nginx
      ansible.builtin.service:
        name: nginx
        state: reloaded

运行 Playbook:

bash
ansible-playbook -i inventory.ini render-nginx.yml

预期输出中 failed=0、unreachable=0 表示执行成功;首次运行的 changed 数量会随主机当前状态变化。

text
PLAY RECAP
web1 : ok=<VALUE> changed=<VALUE> unreachable=0 failed=0 skipped=<VALUE> rescued=0 ignored=0

验证渲染结果与幂等性

先直接读取远端文件,确认变量和 Fact 已经替换为具体值,而不是残留 {{ ... }} 表达式。

bash
ansible web -i inventory.ini -b -m ansible.builtin.command -a "cat /etc/nginx/conf.d/ansible-demo.conf"

预期输出会包含目标主机实际名称;下面的 <HOSTNAME> 代表运行时值。

text
web1 | CHANGED | rc=0 >>
server {
    listen 8080;
    server_name <HOSTNAME>;

    location / {
        return 200 "env=production host=web1";
    }
}

再次执行同一 Playbook:

bash
ansible-playbook -i inventory.ini render-nginx.yml

如果没有人为修改软件包或配置,模板任务应保持不变,最终通常看到 changed=0。

text
PLAY RECAP
web1 : ok=<VALUE> changed=0 unreachable=0 failed=0 skipped=<VALUE> rescued=0 ignored=0

处理模板中的常见边界

template 默认会覆盖目标文件,因此目标机上的手工修改不是长期配置来源;需要保留的差异应回收到变量或模板。渲染依赖 Fact 时要为可能缺失的字段准备默认值,并避免把未经校验的任意字符串直接拼进配置语法。

修改模板前还要考虑服务是否能接受新配置。生产环境可在 template 任务上增加适合该服务的 validate 命令,或先在测试主机执行配置检查,再由 handler 重载。模板、变量和验证命令三者分工清楚,才能把“能生成文件”提升为“可维护地生成正确配置”。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 Template 渲染配置文件

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通