Layering group_vars across environments

Ansible has twenty-two variable precedence levels. Part XIII covers all of them and you should read it before you need it. This lesson is about the four that a repository layout actually controls, and about the only question that matters when deciding where a value goes.

That question is not “where does this fit”. It is who owns this value, and who has to approve a change to it.

Four layers, four owners

Read down that table and the reason for the ordering is obvious: each layer is narrower and better-informed than the one above, so each one wins over the one above. Read up it and you get the review rule — a change at a lower layer affects fewer hosts and needs fewer approvals, which is exactly why host_vars is where a “temporary” fix goes to become permanent.

A group_vars directory of several files

Any group_vars/<group>.yml file can become a group_vars/<group>/ directory instead, and every parseable file inside it is read. This is how you keep a large tier’s variables readable, and how the encrypted material sits beside the plaintext material without one file being half-encrypted.

inventories/production/group_vars/webservers/
  10-tuning.yml        # webserver_worker_processes: 4
                       # webserver_max_body_size: 16m
  20-limits.yml        # webserver_worker_processes: 16
  vault.yml            # encrypted, vault id: prod

Files inside the directory are read in lexicographic order and later files win. That is what the numeric prefixes are for, and it is why 20-limits.yml beats 10-tuning.yml:

$ ansible-inventory -i inventories/production --host web-prod-01.example.com

{
  "ansible_host": "192.0.2.11",
  "environment_name": "production",
  "ntp_servers": [
      "ntp1.example.com",
      "ntp2.example.com"
  ],
  "webserver_max_body_size": "16m",
  "webserver_worker_processes": 16
}

webserver_max_body_size survives from 10-tuning.yml because nothing later redefines it; webserver_worker_processes is 16 because 20-limits.yml was read after 10-tuning.yml. Add a host exception and it wins over both:

$ ansible-inventory -i inventories/production --host web-prod-02.example.com

{
  "ansible_host": "192.0.2.12",
  "environment_name": "production",
  "ntp_servers": [
      "ntp1.example.com",
      "ntp2.example.com"
  ],
  "webserver_max_body_size": "16m",
  "webserver_worker_processes": 32
}

Finding where a value came from

This is the question you will actually ask, usually at speed, usually because production has a value nobody expected. There is one command that answers most of it:

$ ansible-inventory -i inventories/production --vault-id prod@~/.vault/prod --graph --vars

@all:
|--@ungrouped:
|--@webservers:
|  |--web-prod-01.example.com
|  |  |--{ansible_host = 192.0.2.11}
|  |  |--{environment_name = production}
|  |  |--{ntp_servers = ['ntp1.example.com', 'ntp2.example.com']}
|  |  |--{webserver_max_body_size = 16m}
|  |  |--{webserver_worker_processes = 16}
|  |--web-prod-02.example.com
|  |  |--{ansible_host = 192.0.2.12}
|  |  |--{environment_name = production}
|  |  |--{webserver_max_body_size = 16m}
|  |  |--{webserver_worker_processes = 32}
|  |--{webserver_max_body_size = 16m}
|  |--{webserver_worker_processes = 16}
|--{environment_name = production}
|--{ntp_servers = ['ntp1.example.com', 'ntp2.example.com']}

Read it bottom-up. The lines hanging off @all came from group_vars/all/. The two hanging off @webservers came from group_vars/webservers/. The per-host lines are the fully resolved set, so web-prod-02 showing 32 while the group shows 16 tells you immediately that a host_vars file exists for that machine.

That attribution is the thing --host cannot give you: --host returns the resolved answer, --graph --vars returns the answer and the layer.

The same variable, three environments

The point of the whole arrangement is that one line in a role works everywhere. Same playbook, same role, two inventories:

$ ansible-playbook -i inventories/production playbooks/report.yml

ok: [web-prod-01.example.com] => {
  "msg": "env=production workers=16 tls=False"
}
ok: [web-prod-02.example.com] => {
  "msg": "env=production workers=32 tls=False"
}

$ ansible-playbook -i inventories/staging playbooks/report.yml

ok: [web-stg-01.example.com] => {
  "msg": "env=staging workers=2 tls=False"
}

Nothing failed. Both runs are green. And staging just tested a configuration production does not use — 2 workers against production’s 16 and 32.

That asymmetry is not always wrong; staging is smaller and a smaller worker count may be correct. It is wrong when the difference is accidental, which is the usual case, and it is the mechanism behind this part’s first break/fix: a change validated in staging behaved differently in production because the two environments resolved different values for the parameter the change was about. Lesson 4 is about the discipline that prevents it.

Knowledge check