Reading inherited with_* code · Ansible

with_items, with_dict, with_nested and the rest are still supported and still work on ansible-core 2.21. They are not removed and there is no deprecation warning. Upstream recommends loop for new code and continues to document the with_* forms precisely so that inherited code remains readable.

That combination — works fine, not recommended — is exactly the situation where a conversion project can do more harm than good, so this lesson covers reading before it covers converting.

What each form does

Every with_* keyword is backed by a lookup plugin. with_items uses the items lookup, with_fileglob uses fileglob, and so on. The keyword is with_ plus the plugin name, which is why there are so many of them and why third-party collections could add more.

Read-only / Safewith_items over a flat list— Legacy form. Iterates the elements of a list, binding each to item - the same as loop for this input.

$ ansible-playbook legacy.yml

TASK [with_items] **************************************************************
ok: [localhost] => (item=curl) => {
  "msg": "curl"
}
ok: [localhost] => (item=jq) => {
  "msg": "jq"
}

Read-only / Safewith_dict over a dictionary— Legacy form. Produces one item per key, each a dictionary with key and value - identical in shape to what dict2items produces.

$ ansible-playbook legacy.yml

TASK [with_dict] ***************************************************************
ok: [localhost] => (item={'key': 'api', 'value': 'https://api.example.com'}) => {
  "msg": "api -> https://api.example.com"
}
ok: [localhost] => (item={'key': 'metrics', 'value': 'https://metrics.example.com'}) => {
  "msg": "metrics -> https://metrics.example.com"
}

Read-only / Safewith_subelements over a list of records with nested lists— Legacy form. Produces one item per sub-element, where item.0 is the parent record and item.1 is the sub-element.

$ ansible-playbook legacy.yml

TASK [with_subelements] ********************************************************
ok: [localhost] => (item=[{'name': 'alice'}, 'adm']) => {
  "msg": "alice in adm"
}
ok: [localhost] => (item=[{'name': 'alice'}, 'sudo']) => {
  "msg": "alice in sudo"
}
ok: [localhost] => (item=[{'name': 'bob'}, 'docker']) => {
  "msg": "bob in docker"
}

with_subelements is the one that reads worst. item.0 is the parent, item.1 is the child, and the code around it will be full of item.0.name and item.1 with nothing naming what either is. That opacity is the strongest argument for converting this particular form.

The conversion table

Upstream documents the mapping. Every row below was confirmed by running both forms on ansible-core 2.21.3 and comparing the iterations.

Legacy	Modern equivalent
`with_list`	`loop`
`with_items`	`loop` + `flatten(levels=1)`
`with_flattened`	`loop` + `flatten`
`with_indexed_items`	`loop` + `flatten(levels=1)` + `index_var`
`with_together`	`loop` + `zip`
`with_dict`	`loop` + `dict2items` (or `dictsort`)
`with_sequence`	`loop` + `range`
`with_subelements`	`loop` + `subelements`
`with_nested` / `with_cartesian`	`loop` + `product`

Two of them verified side by side:

Read-only / Safewith_nested and loop + product produce identical iterations— Two users crossed with two databases. Both forms produce the same four items in the same order.

$ ansible-playbook conv.yml

TASK [with_nested equivalence] *************************************************
ok: [localhost] => (item=['alice', 'app'])  => { "msg": "alice/app" }
ok: [localhost] => (item=['alice', 'logs']) => { "msg": "alice/logs" }
ok: [localhost] => (item=['bob', 'app'])    => { "msg": "bob/app" }
ok: [localhost] => (item=['bob', 'logs'])   => { "msg": "bob/logs" }

TASK [loop + product equivalence] **********************************************
ok: [localhost] => (item=['alice', 'app'])  => { "msg": "alice/app" }
ok: [localhost] => (item=['alice', 'logs']) => { "msg": "alice/logs" }
ok: [localhost] => (item=['bob', 'app'])    => { "msg": "bob/app" }
ok: [localhost] => (item=['bob', 'logs'])   => { "msg": "bob/logs" }

Read-only / Safewith_together and loop + zip produce identical iterations— Two lists paired positionally. Both forms produce the same two items.

$ ansible-playbook conv.yml

TASK [with_together equivalence] ***********************************************
ok: [localhost] => (item=['alice', 'app'])  => { "msg": "alice=app" }
ok: [localhost] => (item=['bob', 'logs'])   => { "msg": "bob=logs" }

TASK [loop + zip equivalence] **************************************************
ok: [localhost] => (item=['alice', 'app'])  => { "msg": "alice=app" }
ok: [localhost] => (item=['bob', 'logs'])   => { "msg": "bob=logs" }

Note the item.0 / item.1 addressing survives both conversions — product and zip produce pairs exactly as with_nested and with_together did, so the task body does not change.

The conversion that changes behaviour

with_items flattens one level. loop does not. This is the single most important line in the lesson.

Read-only / Safethe same input, two different iteration counts— A list of lists. with_items produces three iterations over the inner strings; loop produces two iterations over the inner lists.

$ ansible-playbook legacy.yml

TASK [with_items flattens one level] *******************************************
ok: [localhost] => (item=a) => { "msg": "a" }
ok: [localhost] => (item=b) => { "msg": "b" }
ok: [localhost] => (item=c) => { "msg": "c" }

TASK [loop does NOT flatten] ***************************************************
ok: [localhost] => (item=['a', 'b']) => {
  "msg": [
      "a",
      "b"
  ]
}
ok: [localhost] => (item=['c']) => {
  "msg": [
      "c"
  ]
}

Three iterations became two, and item changed from a string to a list. That is why the conversion table says loop + flatten(levels=1) and not just loop:

Read-only / Safeflatten(levels=1) restores the with_items behaviour— Applying the documented filter to the nested list reproduces exactly what with_items iterated.

$ ansible-playbook conv.yml

TASK [with_items flatten equivalence] ******************************************
ok: [localhost] => {
  "msg": "with_items -> ['a', 'b', 'c']"
}

This is the conversion that breaks production quietly

A with_items over a variable that usually holds a flat list works identically under loop — for every input you tested.

Then it meets a host where the variable is assembled from two group_vars files, or comes back from a map filter, or is a registered result, and holds a list of lists. Under with_items it iterated the leaves. Under loop it iterates the branches, item is a list where the task expects a string, and one of two things happens:

the module rejects it with a type error, which is the good outcome; or
the module accepts it and does something unintended, such as creating a file literally named ['a', 'b'].

The safe conversion rule: when converting with_items, either add flatten(levels=1) or prove the input can never be nested. For a literal list in the same file, proving it is trivial. For a variable assembled elsewhere, add the filter.

`with_fileglob` and the controller-side forms

Some with_* forms have no plain-data equivalent because they are doing I/O:

Read-only / Safelegacy: with_fileglob, and the modern form— Both read the controller filesystem. The conversion is mechanical because the lookup does the work either way.

# Legacy
- name: Deploy every config fragment
ansible.builtin.copy:
  src: "{{ item }}"
  dest: "/etc/app/conf.d/{{ item | basename }}"
  mode: '0644'
with_fileglob:
  - files/conf.d/*.conf

# Modern - the same lookup, called explicitly
- name: Deploy every config fragment
ansible.builtin.copy:
  src: "{{ item }}"
  dest: "/etc/app/conf.d/{{ item | basename }}"
  mode: '0644'
loop: "{{ query('ansible.builtin.fileglob', 'files/conf.d/*.conf') }}"
loop_control:
  label: "{{ item | basename }}"

The pattern generalises: with_<plugin> becomes loop: "{{ query('<plugin>', ...) }}". Use query rather than lookup here, because query always returns a list, whereas lookup returns a comma-joined string by default and iterating that gives you one very strange item.

fileglob reads the controller, not the target. It always did, and that surprises people who assume a loop over files is looking at the managed node. find is the module that inspects the target.

Should you convert?

Not automatically, and not as a project of its own.

Convert when you are already editing the task. The risk is bounded by a change you are testing anyway.

Convert with_subelements and with_nested on sight. These are the ones whose item.0 / item.1 addressing makes surrounding code unreadable, and the conversion lets you add a loop_var and a label that name what the values are.

Convert with_dict where a label is needed. A with_dict over credentials prints them, exactly as lesson 4 described, and adding loop_control is a good enough reason on its own.

Leave a working with_items over a literal list alone. It works, it is readable, converting it has a nonzero chance of introducing the flattening bug, and the benefit is stylistic.

Under the hood

with_X and loop are the same iteration machinery with different front ends.

with_X names a lookup plugin. The executor calls that plugin with the supplied arguments, gets a list back, and iterates it. loop takes a list directly — and because Jinja can call query(), anything a lookup can produce is reachable from loop too. That is the whole relationship, and it is why every conversion in the table is possible.

The differences are in what the lookups do to their input before returning. The items lookup flattens one level, which is where the with_items behaviour comes from — it is a property of the plugin, not of looping. The list lookup does not flatten, which is why with_list maps to bare loop.

loop was introduced as the recommended form precisely because with_X conflated two concerns: where the data comes from, and the fact that the task iterates. Splitting them means the loop keyword always means the same thing and the data source is an ordinary expression you can read, test in debug, and compose with filters.

Both are lookups executing on the controller, before the task runs on the target. That is true of with_fileglob, with_file, with_lines and every other form, and it is why none of them can see the managed node’s filesystem.

What happens if a task has both loop and with_items?

The play fails to parse. They are mutually exclusive, and the error names the conflict directly rather than picking one.

That is helpful, because the alternative — silently preferring one — would make a half-finished conversion behave in a way nobody could predict from reading the task.

The related situation that does not error is a task with loop and a stray loop_control referencing a variable the loop does not set. A loop_control.label naming item.name on a loop that renamed the loop variable to site fails at iteration time on an undefined attribute — which, as lesson 4 noted, is a run stopped by display metadata.

When converting, change the loop keyword, the loop expression, and the loop_control block together, and read the task body for every reference to item before moving on.

Knowledge check

Why this matters

Most Ansible you will be paid to work on already exists, and a great deal of it was written when with_items was the normal way to write a loop. Refusing to read it is not an option, and misreading it is how a maintenance change becomes an incident.

The specific thing worth carrying away is the flattening difference, because it is the one conversion that is silently wrong. Everything else in the table is an exact substitution you can verify in a debug task in thirty seconds; that one changes iteration count for inputs you may not have tested.

And the meta-lesson is about restraint. Legacy code that works is not a defect. The temptation to modernise a repository wholesale is strong, the diff is unreviewable, and the payoff is style. Convert what you touch, convert what is genuinely unreadable, and leave the rest to the next person who has a real reason to open the file.