Ansible Inventory（主机清单）YAML 格式

参考文档:

如何编写yaml格式的Ansible主机清单(inventory)及清单变量使用Demo

🔥 目录

什么是 Ansible Inventory
YAML 格式 Inventory 基础写法
分组、子组、嵌套结构
主机变量 / 组变量写法
组变量优先级
host_vars / group_vars
动态 Inventory（简要）
生产级 YAML Inventory 模板（含多环境、多机房、多角色）
最佳实践十条
常见坑（以及怎么避免）

1. 📌 什么是 Inventory？

Inventory 是 Ansible 连接目标主机的“清单”，包含：

主机 IP / Hostname
组（group）与子组（children）
变量（host_vars / group_vars）
SSH 参数、端口、认证方式
自定义变量（业务变量）

YAML 格式（inventory.yml）比 INI 格式更直观、层级清晰，是生产推荐格式。

2. 📘 YAML Inventory 最基础格式

all:
  hosts:
    web1:
      ansible_host: 10.1.1.11
    web2:
      ansible_host: 10.1.1.12

最小结构：

all:
  hosts:

3. 📦 分组 / 子组 / 嵌套结构

3.1 定义组（group）

all:
  children:
    web:
      hosts:
        web1:
          ansible_host: 10.1.1.11
        web2:
          ansible_host: 10.1.1.12

3.2 多层嵌套（children）

all:
  children:
    prod:
      children:
        web:
          hosts:
            web1:
              ansible_host: 10.1.1.11
        db:
          hosts:
            db1:
              ansible_host: 10.1.1.21

在 playbook 或 ad-hoc 中可以用：

ansible web -m ping
ansible db -m ping
ansible prod -m ping

4. 📌 主机变量（host vars）与组变量（group vars）

4.1 主机变量

all:
  hosts:
    node1:
      ansible_host: 192.168.1.10
      ansible_port: 2222
      ansible_user: deploy

4.2 组变量

all:
  children:
    web:
      vars:
        nginx_port: 80
        ansible_user: www
      hosts:
        web1:
          ansible_host: 10.1.1.11
        web2:
          ansible_host: 10.1.1.12

5. 🧊 组变量优先级（很重要）

Ansible 变量优先级（高 -> 低）：

Extra vars（-e）
Host vars（inventory 主机变量）
Host vars（host_vars/ 目录）
Group vars（group_vars/ 目录）
Group vars（inventory）
Role defaults

👉 越“具体”优先级越高
👉 ad-hoc 的 -e 永远最高

6. 📁 host_vars / group_vars 目录结构（强烈推荐）

主机：

host_vars/web1.yml
host_vars/db1.yml

组：

group_vars/all.yml
group_vars/web.yml
group_vars/db.yml

示例

group_vars/web.yml

nginx_port: 80
ansible_user: nginx

host_vars/web1.yml

nginx_port: 8080

host_vars 会覆盖 group_vars。

7. ⚙️ 动态 Inventory（简略说明）

如果你的主机是动态生成（Kubernetes、OpenStack、AWS、自动扩缩），使用：

inventory.aws_ec2.yml
inventory.k8s.yml
inventory.gcp.yml

例如 EC2：

plugin: amazon.aws.ec2
regions:
  - ap-east-1
hostnames:
  - tag:Name

执行：

ansible-inventory -i inventory.aws.yml --graph

8. 🎯 生产级 YAML Inventory 模板

下面给你企业级推荐结构模板（支持多环境 + 多机房 + 多角色）。

8.1 目录结构（生产推荐）

inventory/
  ├── prod/
  │     ├── inventory.yml
  │     ├── group_vars/
  │     │     ├── all.yml
  │     │     ├── web.yml
  │     │     └── db.yml
  │     └── host_vars/
  │           ├── web1.yml
  │           └── db1.yml
  ├── staging/
  └── dev/

8.2 inventory/prod/inventory.yml（完整示例）

all:
  vars:
    ansible_user: deploy
    ansible_ssh_private_key_file: ~/.ssh/id_rsa
    timezone: Asia/Shanghai

  children:

    # ------------------ 多机房结构 ------------------
    idc_a:
      children:
        web:
          hosts:
            web1:
              ansible_host: 10.10.1.11
            web2:
              ansible_host: 10.10.1.12
        db:
          hosts:
            db1:
              ansible_host: 10.10.1.21

    idc_b:
      children:
        web:
          hosts:
            web3:
              ansible_host: 10.20.1.11
        cache:
          hosts:
            redis1:
              ansible_host: 10.20.1.31

    # ------------------ 按角色分组 ------------------
    web:
      vars:
        service_port: 8080
        nginx_worker: 4

    db:
      vars:
        mysql_port: 3306

    cache:
      vars:
        redis_port: 6379

8.3 group_vars/all.yml

timezone: Asia/Shanghai
ulimit_nofile: 65535

8.4 group_vars/web.yml

nginx_port: 80
nginx_user: www

8.5 host_vars/web1.yml

nginx_port: 8081

9. 🏆 Inventory 最佳实践（企业级）

✅ 1. 把密码全部移除，使用密钥

ansible_user + ansible_ssh_private_key_file

✅ 2. 生产环境必须拆多环境（prod/staging/dev）

✅ 3. 明确分层

环境层：prod/staging/dev
地域层：idc_a / idc_b
角色层：web/db/cache

✅ 4. 通用变量放 group_vars/all.yml

例如：

timezone
mirrors
ntp servers

✅ 5. 角色变量放 group_vars/{group}.yml

如：group_vars/web.yml 放 nginx 变量

✅ 6. 个性化变量放 host_vars/{host}.yml

如 web1 端口不同

✅ 7. inventory.yml 不要放大量变量

只放主机结构、主机 IP

✅ 8. 多角色 host 使用 children，而不是重复写

例如：

common:
  children:
    web:
    db:

✅ 9. 大量服务器推荐用动态 Inventory

AWS/阿里云/K8s 工具自动同步

✅ 10. 用 ansible-inventory 检查

ansible-inventory -i inventory/prod --graph

10. ❗常见坑（重点）

❌ 1. ansible_host 与主机名混用

错误：

web1: 10.1.1.11

正确：

web1:
  ansible_host: 10.1.1.11

❌ 2. 变量写错位置

变量不能写在 hosts 下：

❌ 错误：

hosts:
  vars:

❌ 3. children 与 hosts 不能混级写

❌：

children:
  web:
    web1:

必须：

children:
  web:
    hosts:
      web1:

❌ 4. host_vars 覆盖 group_vars 不生效

注意名称必须和 inventory 主机名一致。