Ansible when条件判断原理与七种安全写法

1. 别再把when当成“if语句”来用Ansible条件判断的真实工作逻辑刚接触 Ansible 的人看到when:这个关键字第一反应几乎都是“哦这是 Ansible 的 if 判断”。然后兴冲冲地写- name: Install nginx only on Ubuntu apt: name: nginx state: present when: ansible_distribution Ubuntu结果发现——它确实能跑通但很快就会在更复杂的场景里栽跟头。我第一次在生产环境部署一个跨 CentOS/RHEL/Ubuntu 的中间件集群时就因为这个认知偏差连续三天没搞明白为什么某台 RHEL 主机上的服务启动任务总被跳过日志里却只显示skipping: [host03]连个具体原因都不给。后来才彻底搞清楚when不是“运行时分支”而是“任务级预编译过滤器”。它根本不是在 Playbook 执行到那一行时才去计算布尔值而是在整个 Playbook 加载解析阶段就根据当前主机的ansible_facts或你定义的变量对每个任务做一次“是否纳入执行队列”的静态判定。如果判定为false那个任务压根就不会进入执行流水线连debug都不会触发。这直接导致两个关键后果第一when无法响应任务执行过程中的动态变化。比如你写- name: Get current user command: whoami register: current_user - name: Do something only if user is root debug: msg: Running as root! when: current_user.stdout root # ❌ 错误current_user 还没注册成功这段代码会直接报错The conditional check current_user.stdout root failed. The error was: error while evaluating conditional (current_user.stdout root): dict object has no attribute stdout。因为register是任务执行后才赋值的而when在任务执行前就要求current_user已存在。这不是语法错误是执行时序的根本错位。第二when的上下文是“单主机、单任务”它天然不具备跨任务、跨主机的状态感知能力。你不能指望用when去判断“上一个任务是否失败了”也不能用它来实现“只要集群里有一台机器满足条件就执行某个全局操作”。这些需求必须交给blockrescue、failed_when、ignore_errors或者set_factloop等组合拳来解决。所以真正理解when首先要扔掉“编程语言 if”的思维惯性。把它看作一个声明式过滤开关你不是在告诉 Ansible “如果满足条件就执行”而是在告诉它 “请把这条任务从待执行列表里筛出去除非满足条件”。这个视角的切换是写出健壮 Playbook 的第一道门槛。提示when的底层实现其实是 Jinja2 模板引擎在 Playbook 解析阶段的一次求值。Ansible 把所有 facts、vars、hostvars 都注入 Jinja2 上下文然后对when后面的表达式做一次渲染。如果渲染结果是trueJinja2 的 truthy该任务保留否则丢弃。这也是为什么when: my_var is defined and my_var ! 是安全写法而when: my_var ! 在my_var未定义时会直接报错——Jinja2 对未定义变量求值失败。2.when表达式的七种写法与避坑指南从基础比较到复杂嵌套when后面的表达式表面看只是个布尔判断但实际写法千差万别。很多新手卡在when上并非逻辑想不通而是被各种写法的细节和陷阱绊倒。下面我把实践中最常遇到的七种模式结合真实踩过的坑一条条拆解。2.1 最基础的字符串/数值比较和!的隐式类型转换陷阱最简单的写法- name: Restart service on Debian-based systems systemd: name: nginx state: restarted when: ansible_os_family Debian看起来没问题。但问题出在ansible_os_family这个 fact 的值上。Ansible 2.10 版本中ansible_os_family返回的是字符串Debian但如果你在旧版本如 2.5上运行它可能返回的是debian小写。更隐蔽的是某些定制镜像或容器环境这个 fact 可能压根没被收集或者被覆盖成了其他值。避坑方案永远使用lower()或upper()进行标准化处理when: ansible_os_family | lower debian # 或者更保险的写法 when: ansible_os_family is defined and ansible_os_family | lower debian同理数值比较也容易翻车。比如你想判断内存是否大于 4G# ❌ 危险ansible_memtotal_mb 是整数但有时会是字符串 when: ansible_memtotal_mb 4096在某些 Ansible 版本或特定模块如setup模块被禁用时ansible_memtotal_mb可能是字符串8192而 Jinja2 对字符串和数字的比较行为是不确定的Python 3 中会报错。正确做法是显式转换when: (ansible_memtotal_mb | int) 40962.2 多条件组合and/or/not的优先级与括号强制写多个条件时新手常犯的错误是忽略运算符优先级。比如# ❌ 错误not 会先作用于整个 and 表达式逻辑完全反了 when: not ansible_distribution CentOS and ansible_distribution_major_version 7 # ✅ 正确用括号明确分组 when: not (ansible_distribution CentOS and ansible_distribution_major_version 7) # 或者更清晰的写法 when: ansible_distribution ! CentOS or ansible_distribution_major_version ! 7另一个常见陷阱是or的“短路”特性被误用。比如你想说“如果是 Ubuntu 或 Debian”写成# ❌ 如果 ansible_distribution 是 undefined整个表达式会因第一个条件失败而报错 when: ansible_distribution Ubuntu or ansible_distribution Debian正确写法是when: (ansible_distribution is defined) and (ansible_distribution in [Ubuntu, Debian])2.3 成员关系判断in和not in的高效用法判断一个值是否在列表中in是最简洁的方式- name: Configure firewall for web servers ufw: rule: allow port: {{ item }} loop: - 80 - 443 when: inventory_hostname in groups[webservers]这里groups[webservers]是一个主机列表inventory_hostname是当前主机名。这个写法非常高效且可读性强。但要注意in只能用于判断“是否在序列中”不能用于子字符串匹配。比如你想判断ansible_hostname是否包含prod不能写when: prod in ansible_hostname因为ansible_hostname是字符串而in在 Jinja2 中对字符串是“子串包含”操作这本身没错但风险在于如果ansible_hostname是undefined就会报错。所以必须加保护when: ansible_hostname is defined and prod in ansible_hostname2.4 空值与定义性检查is defined,is not none,| default的分工这是when里最容易混淆的一组操作。它们解决的是不同层面的问题is defined: 检查变量是否在当前作用域中被声明即使值为null或空字符串也算 defined。is not none: 检查变量的值是否不等于 Python 的None即null。| default(...): 是一个过滤器用于提供默认值它本身不是条件判断但常和when配合使用。举个典型例子你有一个可选变量app_config_path想在它被设置时才执行配置文件拷贝任务# ❌ 错误如果 app_config_path 是 空字符串这个条件为 true但 cp 会失败 when: app_config_path is defined # ✅ 正确既要定义又要非空 when: app_config_path is defined and app_config_path ! # 更优雅的写法利用 Jinja2 的 truthy 规则 when: app_config_path # 因为 Jinja2 中None, , [], {} 都是 falsy只有非空值才是 truthy但如果app_config_path可能是nullYAML 的~那么when: app_config_path就不行了因为null是 falsy但is defined是 true。这时就需要when: app_config_path is defined and app_config_path is not none and app_config_path ! 不过这种写法太啰嗦。更推荐的实践是在 Playbook 开头就用set_fact统一处理- name: Normalize app_config_path set_fact: app_config_path_final: - {{ app_config_path | default(/etc/myapp/config.yml) }} when: app_config_path is defined and app_config_path | length 0 - name: Copy config file copy: src: templates/app.conf.j2 dest: {{ app_config_path_final }} when: app_config_path_final is defined2.5 复杂嵌套结构判断selectattr,map,json_query的实战价值当你的条件需要基于嵌套数据结构比如 JSON API 返回的结果、复杂的 facts 字典时光靠和in就不够了。这时候selectattr和map过滤器就派上大用场。假设你通过uri模块调用了一个 API返回了如下 JSON{ services: [ {name: nginx, status: running, port: 80}, {name: redis, status: stopped, port: 6379}, {name: mysql, status: running, port: 3306} ] }你想只对状态为running的服务执行健康检查任务。你可以这样写- name: Get service status from API uri: url: http://localhost:8000/api/services return_content: yes register: api_result - name: Check health of running services command: curl -f http://localhost:{{ item.port }}/health loop: - {{ api_result.json.services | selectattr(status, equalto, running) | list }} when: api_result is succeeded这里selectattr(status, equalto, running)就是从services列表中筛选出所有status字段等于running的字典。equalto是一个比较器还有search,match,contains等适用于不同场景。再比如你想提取所有运行中服务的端口号组成一个列表用于后续防火墙配置- name: Get running service ports set_fact: running_ports: - {{ api_result.json.services | selectattr(status, equalto, running) | map(attributeport) | list }} when: api_result is succeeded - name: Open firewall for running services ufw: rule: allow port: {{ item }} loop: {{ running_ports }}map(attributeport)就是把筛选后的每个字典的port字段值提取出来形成一个纯数字列表[80, 3306]。2.6 基于执行结果的条件is succeeded,is failed,is skipped的精准控制前面讲的都是基于 facts 和变量的静态判断。但很多时候你的条件要依赖上一个任务的执行结果。Ansible 提供了专门的测试器test来实现这一点is succeeded: 任务成功完成rc 0且未被跳过is failed: 任务执行失败rc ! 0is skipped: 任务被when跳过或loop中某次迭代被跳过这是一个极其强大的能力能让你的 Playbook 具备“自适应”能力。例如你想在安装软件包失败时尝试从另一个源安装- name: Try to install package from main repo apt: name: myapp state: present register: install_result ignore_errors: yes - name: Fallback to backports repo if main install failed apt: name: myapp state: present default_release: buster-backports when: install_result is failed注意ignore_errors: yes是必须的否则第一个任务失败会直接中断整个 Playbook。when: install_result is failed就是精准捕获这个失败事件。另一个经典场景是“仅当文件不存在时才创建”。很多人会写# ❌ 错误file 模块没有 state: absent 的返回值无法用 when 判断 - name: Create config dir if not exists file: path: /etc/myapp state: directory mode: 0755 when: not (lookup(file, /etc/myapp) | bool) # lookup 在这里不适用正确做法是用stat模块先探测- name: Check if config dir exists stat: path: /etc/myapp register: config_dir_stat - name: Create config dir if not exists file: path: /etc/myapp state: directory mode: 0755 when: not config_dir_stat.stat.exists2.7 使用json_query进行高级数据筛选JMESPath 的威力当你的数据结构非常复杂嵌套层级很深或者需要进行多条件联合筛选时json_query过滤器就是终极武器。它背后是 JMESPath 查询语言功能堪比 SQL。假设你有一个facts变量里面存着所有网络接口的详细信息来自setup模块ansible_all_ipv4_addresses: [192.168.1.10, 10.0.2.15] ansible_interfaces: [lo, eth0, eth1] ansible_eth0: { ipv4: {address: 192.168.1.10, netmask: 255.255.255.0}, ipv6: [{address: fe80::a00:27ff:fe4e:66a1, prefix: 64}], macaddress: 08:00:27:4e:66:a1 } ansible_eth1: { ipv4: {address: 10.0.2.15, netmask: 255.255.255.0}, macaddress: 08:00:27:b7:2c:1d }你想找出所有 IPv4 地址以192.168.开头的网卡名称。用传统selectattr很难写但用json_query一行搞定- name: Find private network interfaces set_fact: private_ifaces: - {{ ansible_facts | json_query(keys()[?starts_with(, ansible_) contains(ipv4.address, 192.168.)]) }} # 这个查询的意思是获取所有 key筛选出以 ansible_ 开头、且其值中包含 ipv4.address 字段且该字段值以 192.168. 开头的 key虽然这个例子有点绕但它展示了json_query的强大。在处理云平台元数据如 AWS EC2 的instance_facts、Kubernetes 的kubectl get nodes -o json输出时json_query几乎是必备技能。3.when的替代方案什么情况下不该用whenwhen是最常用的条件控制但它绝不是万能的。在很多场景下强行用when会导致 Playbook 变得臃肿、难以维护甚至引入逻辑漏洞。下面这四种替代方案是我在线上环境反复验证后总结出的最佳实践。3.1 用failed_when替代when做“反向断言”failed_when的作用是让一个本应成功的任务在满足特定条件时主动失败。这听起来和when相反但它的价值在于将“错误预期”显式化。比如你运行一个命令期望它的输出中不包含某个关键词比如你不希望看到ERROR- name: Run health check script command: /usr/local/bin/health.sh register: health_result - name: Fail if health check reports ERROR fail: msg: Health check failed: {{ health_result.stdout }} when: ERROR in health_result.stdout这段代码逻辑是对的但它把“失败”这个关键业务语义藏在了一个独立的fail任务里。阅读 Playbook 时你需要来回跳转才能理解“这个脚本的成败标准是什么”。更好的写法是- name: Run health check script (fail on ERROR) command: /usr/local/bin/health.sh register: health_result failed_when: ERROR in health_result.stdout现在“失败条件”和“执行动作”被绑定在同一个任务里语义清晰一目了然。而且failed_when的优先级高于ignore_errors这意味着即使你设置了ignore_errors: yesfailed_when依然会生效这给了你更精细的错误控制粒度。3.2 用ignore_errorschanged_when实现“静默执行”与“变更感知”的分离ignore_errors的作用是让任务在失败时不中断 Playbook。但很多人忽略了changed_when它才是控制“Ansible 是否认为这个任务引起了系统变更”的开关。一个典型场景是你想清理一个可能不存在的日志文件。file模块删除不存在的文件会报错所以你加了ignore_errors- name: Remove old log file (may not exist) file: path: /var/log/myapp/old.log state: absent ignore_errors: yes但问题来了这个任务无论文件存不存在Ansible 都会报告changed1因为它执行了删除操作哪怕目标不存在。这会污染你的changed统计让你无法准确知道哪些任务真正改变了系统状态。解决方案是- name: Remove old log file (may not exist) file: path: /var/log/myapp/old.log state: absent ignore_errors: yes changed_when: falsechanged_when: false明确告诉 Ansible“这个任务无论成功与否都不代表系统状态发生了有意义的变更”。这在编写幂等性极强的 Playbook 时至关重要。另一个更高级的用法是让changed_when基于命令的输出来判断- name: Reload nginx config only if syntax is OK command: nginx -t changed_when: false failed_when: Configuration file test failed in nginx_test.stdout - name: Actually reload nginx systemd: name: nginx state: reloaded when: nginx_test is succeeded这里nginx -t任务本身不产生变更changed_when: false但它用failed_when精准捕获了配置错误然后由后续的when来决定是否执行真正的 reload。职责分离逻辑清晰。3.3 用blockrescuealways构建“事务式”任务流when是单任务级别的开关而block是一组任务级别的容器。当你需要对一组任务进行条件控制或者需要实现“try/catch/finally”语义时block就是唯一选择。比如你想在目标主机上部署一个应用但这个应用的安装包可能需要从内网 Nexus 下载也可能需要从公网 GitHub 下载。你希望优先尝试内网失败后再 fallback 到公网- name: Deploy application with fallback block: - name: Download package from internal Nexus get_url: url: https://nexus.internal/artifactory/libs-release/myapp-1.0.0.jar dest: /tmp/myapp.jar register: download_result - name: Install package from Nexus command: java -jar /tmp/myapp.jar --install args: creates: /opt/myapp/bin/start.sh rescue: - name: Download package from GitHub (fallback) get_url: url: https://github.com/myorg/myapp/releases/download/v1.0.0/myapp-1.0.0.jar dest: /tmp/myapp.jar - name: Install package from GitHub command: java -jar /tmp/myapp.jar --install args: creates: /opt/myapp/bin/start.sh always: - name: Cleanup temp file file: path: /tmp/myapp.jar state: absent这个block结构完美模拟了编程语言中的异常处理block里的任务按顺序执行任何一个失败都会立即跳转到rescue。rescue里的任务是“错误处理逻辑”只在block失败时执行。always里的任务是“最终清理”无论block成功还是失败都会执行。这比用一堆when和ignore_errors堆砌出来的逻辑要健壮和易懂得多。3.4 用include_tasks/import_tasks实现“条件化任务导入”当你的条件逻辑非常复杂或者需要复用一大段条件判断逻辑时把条件判断和任务内容解耦是更高阶的实践。import_tasks是静态导入在 Playbook 解析时就确定要加载哪些任务文件include_tasks是动态导入在运行时才根据条件决定是否加载。例如你有一个通用的数据库初始化 Playbook但 MySQL 和 PostgreSQL 的初始化步骤完全不同。你可以这样做- name: Import database init tasks based on type include_tasks: init_{{ db_type }}.yml when: db_type in [mysql, postgresql]然后你创建两个文件init_mysql.yml包含mysql_db,mysql_user等任务。init_postgresql.yml包含postgresql_db,postgresql_user等任务。这样Playbook 的主干逻辑就变得极其清爽所有具体的、易变的实现细节都被封装到了独立的.yml文件里。这不仅提高了可读性还极大方便了单元测试和团队协作——不同成员可以并行开发init_mysql.yml和init_postgresql.yml而无需修改主 Playbook。4. 生产环境中的when实战一个跨平台 Java 应用部署案例理论讲完我们来一个完整的、经过生产环境验证的实战案例。这个案例涵盖了前面提到的所有核心知识点并展示了如何将它们有机地组合起来构建一个健壮、可维护、可扩展的 Playbook。4.1 业务需求与环境约束我们要部署一个名为payment-gateway的 Java Spring Boot 应用。它需要运行在以下三种环境中开发环境devUbuntu 20.04使用openjdk-11-jdk应用以普通用户appuser身份运行配置文件放在/home/appuser/config/。测试环境testCentOS 7使用java-11-openjdk-devel应用以appuser身份运行配置文件放在/opt/payment-gateway/config/。生产环境prodRHEL 8使用java-11-openjdk-headless无 GUI应用以专用服务账户pgw身份运行配置文件放在/etc/payment-gateway/并且需要配置 systemd 服务。此外还有一个硬性要求部署过程必须是幂等的且任何一步失败都不能导致部分部署half-deployed状态。4.2 Playbook 结构设计与核心变量我们采用角色Role结构主 Playbookdeploy-payment-gateway.yml如下--- - name: Deploy Payment Gateway Application hosts: payment_servers become: yes vars: # 根据 inventory group 自动推导环境类型 env_type: - {{ dev if dev in group_names else test if test in group_names else prod if prod in group_names else unknown }} # 根据 env_type 和 os_family 推导 JDK 包名 jdk_package: - {{ openjdk-11-jdk if env_type dev and ansible_os_family Debian else java-11-openjdk-devel if env_type test and ansible_os_family RedHat else java-11-openjdk-headless if env_type prod and ansible_os_family RedHat else openjdk-11-jre }} # 应用用户和路径 app_user: - {{ appuser if env_type in [dev, test] else pgw }} app_home: - {{ /home/appuser if env_type dev else /opt/payment-gateway if env_type test else /opt/payment-gateway }} config_path: - {{ /home/appuser/config if env_type dev else /opt/payment-gateway/config if env_type test else /etc/payment-gateway }} pre_tasks: - name: Validate environment type assert: that: - env_type ! unknown msg: Inventory host {{ inventory_hostname }} is not assigned to any of the groups: dev, test, prod roles: - role: common - role: java - role: payment-gateway这里的关键点是vars部分。我们没有用when去控制每个任务的执行而是在 Playbook 开始时就通过一系列if/else表达式预先计算出所有环境相关的变量值。这样后续所有任务都可以用统一的变量名如app_user,config_path来引用大大简化了逻辑。4.3java角色中的when实战精准安装 JDKroles/java/tasks/main.yml是when应用的典范--- - name: Ensure Java is installed (Debian) apt: name: {{ jdk_package }} state: present when: ansible_os_family Debian - name: Ensure Java is installed (RedHat) yum: name: {{ jdk_package }} state: present when: ansible_os_family RedHat - name: Verify Java installation command: java -version register: java_version changed_when: false failed_when: java_version.rc ! 0 - name: Set JAVA_HOME lineinfile: path: /etc/environment line: JAVA_HOME{{ ansible_facts[java_home] | default(/usr/lib/jvm/default-java) }} create: yes when: ansible_facts[java_home] is not defined or ansible_facts[java_home] 第一个when根据ansible_os_family选择包管理器这是最基础的 OS 分支。第二个whenfailed_when确保java -version命令必须成功否则整个 Playbook 失败。changed_when: false表明这个验证任务不引起系统变更。第三个whenlineinfile任务只在JAVA_HOME未被正确设置时才执行避免了重复写入/etc/environment。4.4payment-gateway角色中的block与when协同安全的部署流程roles/payment-gateway/tasks/main.yml展示了block和when如何协同工作--- - name: Prepare application directory structure file: path: {{ item }} state: directory owner: {{ app_user }} group: {{ app_user }} mode: 0755 loop: - {{ app_home }} - {{ app_home }}/lib - {{ config_path }} - name: Download and deploy application JAR block: - name: Download JAR from Artifactory get_url: url: https://artifactory.internal/artifactory/libs-release/payment-gateway-{{ app_version }}.jar dest: /tmp/payment-gateway-{{ app_version }}.jar checksum: sha256:{{ app_checksum }} register: jar_download - name: Copy JAR to app home copy: src: /tmp/payment-gateway-{{ app_version }}.jar dest: {{ app_home }}/lib/payment-gateway.jar owner: {{ app_user }} group: {{ app_user }} mode: 0644 rescue: - name: Fail with clear message on download failure fail: msg: - Failed to download payment-gateway-{{ app_version }}.jar from Artifactory. Please check network connectivity and Artifactory credentials. always: - name: Cleanup temp JAR file: path: /tmp/payment-gateway-{{ app_version }}.jar state: absent - name: Deploy configuration files template: src: config/application-{{ env_type }}.yml.j2 dest: {{ config_path }}/application.yml owner: {{ app_user }} group: {{ app_user }} mode: 0600 - name: Start or restart service (prod only) systemd: name: payment-gateway state: started enabled: yes daemon_reload: yes when: env_type prodblock/rescue/always确保了 JAR 文件的下载和部署是一个原子操作要么全部成功要么在失败时给出清晰的错误信息并且无论如何都会清理临时文件。最后一个when: env_type prod是典型的“环境特有操作”只在生产环境才启动 systemd 服务开发和测试环境由开发者手动启动符合 DevOps 的最佳实践。4.5 关键经验与避坑总结这个案例在生产环境跑了两年期间我们总结出几条血泪经验永远不要在when中写硬编码的主机名或 IP。上面的env_type推导逻辑是基于group_names而不是inventory_hostname。因为主机名可能变化但它所属的 inventory groupdev,test,prod是稳定的、有业务含义的标签。when的条件越简单越好越早计算越好。把复杂的if/elif/else逻辑放在vars里而不是分散在几十个when里。这样一旦逻辑出错你只需要改一处而不是 grep 整个代码库。对所有外部依赖API、Artifactory、GitHub都必须有 fallback 和清晰的错误提示。rescue块里的fail任务不是为了阻止错误而是为了把模糊的 Ansible 报错比如Connection refused转化成运维人员一眼就能看懂的业务错误比如Failed to download from Artifactory。changed_when是衡量 Playbook 健康度的黄金指标。一个设计良好的 Playbook在多次运行后应该只有第一次报告changed1后续运行全部是ok1。如果每次运行都有changed1说明你的幂等性没做好很可能存在when条件判断不准或者file模块的mode、owner设置不一致等问题。最后也是最重要的一点when是工具不是目的。不要为了用when而用when。如果一个条件判断让 Playbook 变得难以理解和维护那就停下来想想有没有更好的架构方式——比如拆分成多个 Role或者用include_tasks动态加载。Ansible 的强大不在于它能写多复杂的when而在于它能让你用最清晰、最接近人类语言的方式描述基础设施的最终状态。