基础设施即代码 / 系统课时
用 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。
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 组;主机地址请替换为实际值。
[web]
web1 ansible_host=<IP>Playbook 先确保 Nginx 已安装,再把模板渲染到目标目录。只有模板内容、属主或权限实际变化时任务才会标记为 changed,并通知 handler 重载服务。
- 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:
ansible-playbook -i inventory.ini render-nginx.yml预期输出中 failed=0、unreachable=0 表示执行成功;首次运行的 changed 数量会随主机当前状态变化。
PLAY RECAP
web1 : ok=<VALUE> changed=<VALUE> unreachable=0 failed=0 skipped=<VALUE> rescued=0 ignored=0验证渲染结果与幂等性
先直接读取远端文件,确认变量和 Fact 已经替换为具体值,而不是残留 {{ ... }} 表达式。
ansible web -i inventory.ini -b -m ansible.builtin.command -a "cat /etc/nginx/conf.d/ansible-demo.conf"预期输出会包含目标主机实际名称;下面的 <HOSTNAME> 代表运行时值。
web1 | CHANGED | rc=0 >>
server {
listen 8080;
server_name <HOSTNAME>;
location / {
return 200 "env=production host=web1";
}
}再次执行同一 Playbook:
ansible-playbook -i inventory.ini render-nginx.yml如果没有人为修改软件包或配置,模板任务应保持不变,最终通常看到 changed=0。
PLAY RECAP
web1 : ok=<VALUE> changed=0 unreachable=0 failed=0 skipped=<VALUE> rescued=0 ignored=0处理模板中的常见边界
template 默认会覆盖目标文件,因此目标机上的手工修改不是长期配置来源;需要保留的差异应回收到变量或模板。渲染依赖 Fact 时要为可能缺失的字段准备默认值,并避免把未经校验的任意字符串直接拼进配置语法。
修改模板前还要考虑服务是否能接受新配置。生产环境可在 template 任务上增加适合该服务的 validate 命令,或先在测试主机执行配置检查,再由 handler 重载。模板、变量和验证命令三者分工清楚,才能把“能生成文件”提升为“可维护地生成正确配置”。