ansible.builtin.sequence lookup – generate a list based on a number sequence

Note

This lookup plugin is part of ansible-core and included in all Ansible installations. In most cases, you can use the short plugin name sequence. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.sequence for easy linking to the plugin documentation and to avoid conflicting with other collections that may have the same lookup plugin name.

Synopsis

  • generates a sequence of items. You can specify a start value, an end value, an optional “stride” value that specifies the number of steps to increment the sequence, and an optional printf-style format string.

  • Arguments can be specified as key=value pair strings or as a shortcut form of the arguments string is also accepted: [start-]end[/stride][:format].

  • Numerical values can be specified in decimal, hexadecimal (0x3f8) or octal (0600).

  • Starting at version 1.9.2, negative strides are allowed.

  • Generated items are strings. Use Jinja2 filters to convert items to preferred type, e.g. {{ 1 + item|int }}.

  • See also Jinja2 range filter as an alternative.

Keyword parameters

This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following examples: lookup('ansible.builtin.sequence', key1=value1, key2=value2, ...) and query('ansible.builtin.sequence', key1=value1, key2=value2, ...)

Parameter

Comments

count

integer

number of elements in the sequence, this is not to be used with end

Default: 0

end

integer

number at which to end the sequence, dont use this with count

Default: 0

format

string

return a string with the generated number formatted in

start

integer

number at which to start the sequence

Default: 0

stride

integer

increments between sequence numbers, the default is 1 unless the end is less than the start, then it is -1.

Examples

- name: create some test users
  ansible.builtin.user:
    name: "{{ item }}"
    state: present
    groups: "evens"
  with_sequence: start=0 end=32 format=testuser%02x

- name: create a series of directories with even numbers for some reason
  ansible.builtin.file:
    dest: "/var/stuff/{{ item }}"
    state: directory
  with_sequence: start=4 end=16 stride=2

- name: a simpler way to use the sequence plugin create 4 groups
  ansible.builtin.group:
    name: "group{{ item }}"
    state: present
  with_sequence: count=4

- name: the final countdown
  ansible.builtin.debug:
    msg: "{{item}} seconds to detonation"
  with_sequence: start=10 end=0 stride=-1

- name: Use of variable
  ansible.builtin.debug:
    msg: "{{ item }}"
  with_sequence: start=1 end="{{ end_at }}"
  vars:
    - end_at: 10

Return Value

Key

Description

Return value

list / elements=string

A list containing generated sequence of items

Returned: success

Authors

  • Jayson Vantuyl

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.