docs: add fqcn to module examples (#73546)

Co-authored-by: Felix Fontein <felix@fontein.de>
pull/76858/head
Syed Ali Haider 2 years ago committed by GitHub
parent 29de2cccba
commit 6bca0a5dc2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -343,6 +343,13 @@ In a playbook, you can control the collections Ansible searches for modules and
The ``collections`` keyword merely creates an ordered 'search path' for non-namespaced plugin and role references. It does not install content or otherwise change Ansible's behavior around the loading of plugins or roles. Note that an FQCN is still required for non-action or module plugins (for example, lookups, filters, tests).
When using the ``collections`` keyword, it is not necessary to add in ``ansible.builtin`` as part of the search list. When left omitted, the following content is available by default:
1. Standard ansible modules and plugins available through ``ansible-base``/``ansible-core``
2. Support for older 3rd party plugin paths
In general, it is preferable to use a module or plugin's FQCN over the ``collections`` keyword and the short name for all content in ``ansible-core``
Using a playbook from a collection
==================================

@ -54,31 +54,31 @@ seealso:
EXAMPLES = r'''
- hosts: localhost
tasks:
- debug:
- ansible.builtin.debug:
msg: play1
- name: Include a play after another play
include: otherplays.yaml
ansible.builtin.include: otherplays.yaml
- hosts: all
tasks:
- debug:
- ansible.builtin.debug:
msg: task1
- name: Include task list in play
include: stuff.yaml
ansible.builtin.include: stuff.yaml
- debug:
- ansible.builtin.debug:
msg: task10
- hosts: all
tasks:
- debug:
- ansible.builtin.debug:
msg: task1
- name: Include task list in play only if the condition is true
include: "{{ hostvar }}.yaml"
ansible.builtin.include: "{{ hostvar }}.yaml"
static: no
when: hostvar is defined
'''

@ -73,41 +73,41 @@ author:
EXAMPLES = r'''
- name: Add host to group 'just_created' with variable foo=42
add_host:
ansible.builtin.add_host:
name: '{{ ip_from_ec2 }}'
groups: just_created
foo: 42
- name: Add host to multiple groups
add_host:
ansible.builtin.add_host:
hostname: '{{ new_ip }}'
groups:
- group1
- group2
- name: Add a host with a non-standard port local to your machines
add_host:
ansible.builtin.add_host:
name: '{{ new_ip }}:{{ new_port }}'
- name: Add a host alias that we reach through a tunnel (Ansible 1.9 and older)
add_host:
ansible.builtin.add_host:
hostname: '{{ new_ip }}'
ansible_ssh_host: '{{ inventory_hostname }}'
ansible_ssh_port: '{{ new_port }}'
- name: Add a host alias that we reach through a tunnel (Ansible 2.0 and newer)
add_host:
ansible.builtin.add_host:
hostname: '{{ new_ip }}'
ansible_host: '{{ inventory_hostname }}'
ansible_port: '{{ new_port }}'
- name: Ensure inventory vars are set to the same value as the inventory_hostname has (close to pre Ansible 2.4 behaviour)
add_host:
ansible.builtin.add_host:
hostname: charlie
inventory_dir: '{{ inventory_dir }}'
- name: Add all hosts running this playbook to the done group
add_host:
ansible.builtin.add_host:
name: '{{ item }}'
groups: done
loop: "{{ ansible_play_hosts }}"

@ -206,102 +206,102 @@ notes:
EXAMPLES = '''
- name: Install apache httpd (state=present is optional)
apt:
ansible.builtin.apt:
name: apache2
state: present
- name: Update repositories cache and install "foo" package
apt:
ansible.builtin.apt:
name: foo
update_cache: yes
- name: Remove "foo" package
apt:
ansible.builtin.apt:
name: foo
state: absent
- name: Install the package "foo"
apt:
ansible.builtin.apt:
name: foo
- name: Install a list of packages
apt:
ansible.builtin.apt:
pkg:
- foo
- foo-tools
- name: Install the version '1.00' of package "foo"
apt:
ansible.builtin.apt:
name: foo=1.00
- name: Update the repository cache and update package "nginx" to latest version using default release squeeze-backport
apt:
ansible.builtin.apt:
name: nginx
state: latest
default_release: squeeze-backports
update_cache: yes
- name: Install the version '1.18.0' of package "nginx" and allow potential downgrades
apt:
ansible.builtin.apt:
name: nginx=1.18.0
state: present
allow_downgrade: yes
- name: Install zfsutils-linux with ensuring conflicted packages (e.g. zfs-fuse) will not be removed.
apt:
ansible.builtin.apt:
name: zfsutils-linux
state: latest
fail_on_autoremove: yes
- name: Install latest version of "openjdk-6-jdk" ignoring "install-recommends"
apt:
ansible.builtin.apt:
name: openjdk-6-jdk
state: latest
install_recommends: no
- name: Update all packages to their latest version
apt:
ansible.builtin.apt:
name: "*"
state: latest
- name: Upgrade the OS (apt-get dist-upgrade)
apt:
ansible.builtin.apt:
upgrade: dist
- name: Run the equivalent of "apt-get update" as a separate step
apt:
ansible.builtin.apt:
update_cache: yes
- name: Only run "update_cache=yes" if the last one is more than 3600 seconds ago
apt:
ansible.builtin.apt:
update_cache: yes
cache_valid_time: 3600
- name: Pass options to dpkg on run
apt:
ansible.builtin.apt:
upgrade: dist
update_cache: yes
dpkg_options: 'force-confold,force-confdef'
- name: Install a .deb package
apt:
ansible.builtin.apt:
deb: /tmp/mypackage.deb
- name: Install the build dependencies for package "foo"
apt:
ansible.builtin.apt:
pkg: foo
state: build-dep
- name: Install a .deb package from the internet
apt:
ansible.builtin.apt:
deb: https://example.com/python-ppq_0.1-1_all.deb
- name: Remove useless packages from the cache
apt:
ansible.builtin.apt:
autoclean: yes
- name: Remove dependencies that are no longer required
apt:
ansible.builtin.apt:
autoremove: yes
'''

@ -105,7 +105,7 @@ EXAMPLES = '''
# Use armored file since utf-8 string is expected. Must be of "PGP PUBLIC KEY BLOCK" type.
- name: Add a key from a file on the Ansible server
ansible.builtin.apt_key:
data: "{{ lookup('file', 'apt.asc') }}"
data: "{{ lookup('ansible.builtin.file', 'apt.asc') }}"
state: present
- name: Add an Apt signing key to a specific keyring file

@ -73,15 +73,15 @@ author:
'''
EXAMPLES = r'''
- assert: { that: "ansible_os_family != 'RedHat'" }
- ansible.builtin.assert: { that: "ansible_os_family != 'RedHat'" }
- assert:
- ansible.builtin.assert:
that:
- "'foo' in some_command_result.stdout"
- number_of_the_counting == 3
- name: After version 2.7 both 'msg' and 'fail_msg' can customize failing assertion message
assert:
ansible.builtin.assert:
that:
- my_param <= 100
- my_param >= 0
@ -89,14 +89,14 @@ EXAMPLES = r'''
success_msg: "'my_param' is between 0 and 100"
- name: Please use 'msg' when ansible version is smaller than 2.7
assert:
ansible.builtin.assert:
that:
- my_param <= 100
- my_param >= 0
msg: "'my_param' must be between 0 and 100"
- name: Use quiet to avoid verbose output
assert:
ansible.builtin.assert:
that:
- my_param <= 100
- my_param >= 0

@ -56,7 +56,7 @@ author:
EXAMPLES = r'''
---
- name: Asynchronous yum task
yum:
ansible.builtin.yum:
name: docker-io
state: present
async: 1000
@ -64,7 +64,7 @@ EXAMPLES = r'''
register: yum_sleeper
- name: Wait for asynchronous job to end
async_status:
ansible.builtin.async_status:
jid: '{{ yum_sleeper.ansible_job_id }}'
register: job_result
until: job_result.finished

@ -111,7 +111,7 @@ attributes:
EXAMPLES = r'''
# Before Ansible 2.3, option 'dest' or 'name' was used instead of 'path'
- name: Insert/Update "Match User" configuration block in /etc/ssh/sshd_config
blockinfile:
ansible.builtin.blockinfile:
path: /etc/ssh/sshd_config
block: |
Match User ansible-agent
@ -119,7 +119,7 @@ EXAMPLES = r'''
- name: Insert/Update eth0 configuration stanza in /etc/network/interfaces
(it might be better to copy files into /etc/network/interfaces.d/)
blockinfile:
ansible.builtin.blockinfile:
path: /etc/network/interfaces
block: |
iface eth0 inet static
@ -127,14 +127,14 @@ EXAMPLES = r'''
netmask 255.255.255.0
- name: Insert/Update configuration using a local file and validate it
blockinfile:
block: "{{ lookup('file', './local/sshd_config') }}"
ansible.builtin.blockinfile:
block: "{{ lookup('ansible.builtin.file', './local/sshd_config') }}"
path: /etc/ssh/sshd_config
backup: yes
validate: /usr/sbin/sshd -T -f %s
- name: Insert/Update HTML surrounded by custom markers after <body> line
blockinfile:
ansible.builtin.blockinfile:
path: /var/www/html/index.html
marker: "<!-- {mark} ANSIBLE MANAGED BLOCK -->"
insertafter: "<body>"
@ -143,13 +143,13 @@ EXAMPLES = r'''
<p>Last updated on {{ ansible_date_time.iso8601 }}</p>
- name: Remove HTML as well as surrounding markers
blockinfile:
ansible.builtin.blockinfile:
path: /var/www/html/index.html
marker: "<!-- {mark} ANSIBLE MANAGED BLOCK -->"
block: ""
- name: Add mappings to /etc/hosts
blockinfile:
ansible.builtin.blockinfile:
path: /etc/hosts
block: |
{{ item.ip }} {{ item.name }}

@ -94,6 +94,6 @@ EXAMPLES = r'''
- name: Prints two lines of messages, but only if there is an environment value set
ansible.builtin.debug:
msg:
- "Provisioning based on YOUR_KEY which is: {{ lookup('env', 'YOUR_KEY') }}"
- "Provisioning based on YOUR_KEY which is: {{ lookup('ansible.builtin.env', 'YOUR_KEY') }}"
- "These servers were built using the password of '{{ password_used }}'. Please retain this for later use."
'''

@ -279,80 +279,80 @@ author:
EXAMPLES = '''
- name: Install the latest version of Apache
dnf:
ansible.builtin.dnf:
name: httpd
state: latest
- name: Install Apache >= 2.4
dnf:
ansible.builtin.dnf:
name: httpd>=2.4
state: present
- name: Install the latest version of Apache and MariaDB
dnf:
ansible.builtin.dnf:
name:
- httpd
- mariadb-server
state: latest
- name: Remove the Apache package
dnf:
ansible.builtin.dnf:
name: httpd
state: absent
- name: Install the latest version of Apache from the testing repo
dnf:
ansible.builtin.dnf:
name: httpd
enablerepo: testing
state: present
- name: Upgrade all packages
dnf:
ansible.builtin.dnf:
name: "*"
state: latest
- name: Install the nginx rpm from a remote repo
dnf:
ansible.builtin.dnf:
name: 'http://nginx.org/packages/centos/6/noarch/RPMS/nginx-release-centos-6-0.el6.ngx.noarch.rpm'
state: present
- name: Install nginx rpm from a local file
dnf:
ansible.builtin.dnf:
name: /usr/local/src/nginx-release-centos-6-0.el6.ngx.noarch.rpm
state: present
- name: Install Package based upon the file it provides
dnf:
ansible.builtin.dnf:
name: /usr/bin/cowsay
state: present
- name: Install the 'Development tools' package group
dnf:
ansible.builtin.dnf:
name: '@Development tools'
state: present
- name: Autoremove unneeded packages installed as dependencies
dnf:
ansible.builtin.dnf:
autoremove: yes
- name: Uninstall httpd but keep its dependencies
dnf:
ansible.builtin.dnf:
name: httpd
state: absent
autoremove: no
- name: Install a modularity appstream with defined stream and profile
dnf:
ansible.builtin.dnf:
name: '@postgresql:9.6/client'
state: present
- name: Install a modularity appstream with defined stream
dnf:
ansible.builtin.dnf:
name: '@postgresql:9.6'
state: present
- name: Install a modularity appstream with defined profile
dnf:
ansible.builtin.dnf:
name: '@postgresql/client'
state: present
'''

@ -43,7 +43,7 @@ notes:
'''
EXAMPLES = '''
- name: Prevent python from being upgraded
dpkg_selections:
ansible.builtin.dpkg_selections:
name: python
selection: hold
'''

@ -90,7 +90,7 @@ author: "Matt Martz (@sivel)"
EXAMPLES = r'''
- name: Case insensitive password string match
ansible.builtin.expect:
command: passwd username
ansible.builtin.command: passwd username
responses:
(?i)password: "MySekretPa$$word"
# you don't want to show passwords in your logs
@ -98,7 +98,7 @@ EXAMPLES = r'''
- name: Generic question with multiple different responses
ansible.builtin.expect:
command: /path/to/custom/command
ansible.builtin.command: /path/to/custom/command
responses:
Question:
- response1

@ -57,7 +57,7 @@ author:
EXAMPLES = r'''
- name: Example using fail and when together
fail:
ansible.builtin.fail:
msg: The system may not be provisioned according to the CMDB status.
when: cmdb_status != "to-be-staged"
'''

@ -144,41 +144,41 @@ seealso:
EXAMPLES = r'''
- name: Recursively find /tmp files older than 2 days
find:
ansible.builtin.find:
paths: /tmp
age: 2d
recurse: yes
- name: Recursively find /tmp files older than 4 weeks and equal or greater than 1 megabyte
find:
ansible.builtin.find:
paths: /tmp
age: 4w
size: 1m
recurse: yes
- name: Recursively find /var/tmp files with last access time greater than 3600 seconds
find:
ansible.builtin.find:
paths: /var/tmp
age: 3600
age_stamp: atime
recurse: yes
- name: Find /var/log files equal or greater than 10 megabytes ending with .old or .log.gz
find:
ansible.builtin.find:
paths: /var/log
patterns: '*.old,*.log.gz'
size: 10m
# Note that YAML double quotes require escaping backslashes but yaml single quotes do not.
- name: Find /var/log files equal or greater than 10 megabytes ending with .old or .log.gz via regex
find:
ansible.builtin.find:
paths: /var/log
patterns: "^.*?\\.(?:old|log\\.gz)$"
size: 10m
use_regex: yes
- name: Find /var/log all directories, exclude nginx and mysql
find:
ansible.builtin.find:
paths: /var/log
recurse: no
file_type: directory
@ -186,14 +186,14 @@ EXAMPLES = r'''
# When using patterns that contain a comma, make sure they are formatted as lists to avoid splitting the pattern
- name: Use a single pattern that contains a comma formatted as a list
find:
ansible.builtin.find:
paths: /var/log
file_type: file
use_regex: yes
patterns: ['^_[0-9]{2,4}_.*.log$']
- name: Use multiple patterns that contain a comma formatted as a YAML list
find:
ansible.builtin.find:
paths: /var/log
file_type: file
use_regex: yes

@ -60,5 +60,5 @@ RETURN = """
EXAMPLES = """
# Display facts from all hosts and store them indexed by hostname at /tmp/facts.
# ansible all -m gather_facts --tree /tmp/facts
# ansible all -m ansible.builtin.gather_facts --tree /tmp/facts
"""

@ -206,19 +206,19 @@ author:
EXAMPLES = r'''
- name: Download foo.conf
get_url:
ansible.builtin.get_url:
url: http://example.com/path/file.conf
dest: /etc/foo.conf
mode: '0440'
- name: Download file and force basic auth
get_url:
ansible.builtin.get_url:
url: http://example.com/path/file.conf
dest: /etc/foo.conf
force_basic_auth: yes
- name: Download file with custom HTTP headers
get_url:
ansible.builtin.get_url:
url: http://example.com/path/file.conf
dest: /etc/foo.conf
headers:
@ -226,31 +226,31 @@ EXAMPLES = r'''
key2: two
- name: Download file with check (sha256)
get_url:
ansible.builtin.get_url:
url: http://example.com/path/file.conf
dest: /etc/foo.conf
checksum: sha256:b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
- name: Download file with check (md5)
get_url:
ansible.builtin.get_url:
url: http://example.com/path/file.conf
dest: /etc/foo.conf
checksum: md5:66dffb5228a211e61d6d7ef4a86f5758
- name: Download file with checksum url (sha256)
get_url:
ansible.builtin.get_url:
url: http://example.com/path/file.conf
dest: /etc/foo.conf
checksum: sha256:http://example.com/path/sha256sum.txt
- name: Download file from a file path
get_url:
ansible.builtin.get_url:
url: file:///tmp/afile.txt
dest: /tmp/afilecopy.txt
- name: < Fetch file that requires authentication.
username/password only available since 2.8, in older versions you need to use url_username/url_password
get_url:
ansible.builtin.get_url:
url: http://example.com/path/file.conf
dest: /etc/foo.conf
username: bar

@ -63,39 +63,39 @@ author:
EXAMPLES = '''
- name: Get root user info
getent:
ansible.builtin.getent:
database: passwd
key: root
- debug:
- ansible.builtin.debug:
var: ansible_facts.getent_passwd
- name: Get all groups
getent:
ansible.builtin.getent:
database: group
split: ':'
- debug:
- ansible.builtin.debug:
var: ansible_facts.getent_group
- name: Get all hosts, split by tab
getent:
ansible.builtin.getent:
database: hosts
- debug:
- ansible.builtin.debug:
var: ansible_facts.getent_hosts
- name: Get http service info, no error if missing
getent:
ansible.builtin.getent:
database: services
key: http
fail_key: False
- debug:
- ansible.builtin.debug:
var: ansible_facts.getent_services
- name: Get user password hash (requires sudo/root)
getent:
ansible.builtin.getent:
database: shadow
key: www-data
split: ':'
- debug:
- ansible.builtin.debug:
var: ansible_facts.getent_shadow
'''

@ -48,25 +48,25 @@ seealso:
EXAMPLES = r'''
- hosts: localhost
tasks:
- debug:
- ansible.builtin.debug:
msg: play1
- name: Include a play after another play
import_playbook: otherplays.yaml
ansible.builtin.import_playbook: otherplays.yaml
- name: Set variables on an imported playbook
import_playbook: otherplays.yml
ansible.builtin.import_playbook: otherplays.yml
vars:
service: httpd
- name: This DOES NOT WORK
hosts: all
tasks:
- debug:
- ansible.builtin.debug:
msg: task1
- name: This fails because I'm inside a play already
import_playbook: stuff.yaml
ansible.builtin.import_playbook: stuff.yaml
'''
RETURN = r'''

@ -85,22 +85,22 @@ seealso:
EXAMPLES = r'''
- hosts: all
tasks:
- import_role:
- ansible.builtin.import_role:
name: myrole
- name: Run tasks/other.yaml instead of 'main'
import_role:
ansible.builtin.import_role:
name: myrole
tasks_from: other
- name: Pass variables to role
import_role:
ansible.builtin.import_role:
name: myrole
vars:
rolevar1: value from task
- name: Apply condition to each task in role
import_role:
ansible.builtin.import_role:
name: myrole
when: not idontwanttorun
'''

@ -46,22 +46,22 @@ seealso:
EXAMPLES = r'''
- hosts: all
tasks:
- debug:
- ansible.builtin.debug:
msg: task1
- name: Include task list in play
import_tasks: stuff.yaml
ansible.builtin.import_tasks: stuff.yaml
- debug:
- ansible.builtin.debug:
msg: task10
- hosts: all
tasks:
- debug:
- ansible.builtin.debug:
msg: task1
- name: Apply conditional to all imported tasks
import_tasks: stuff.yaml
ansible.builtin.import_tasks: stuff.yaml
when: hostvar is defined
'''

@ -96,22 +96,22 @@ seealso:
'''
EXAMPLES = r'''
- include_role:
- ansible.builtin.include_role:
name: myrole
- name: Run tasks/other.yaml instead of 'main'
include_role:
ansible.builtin.include_role:
name: myrole
tasks_from: other
- name: Pass variables to role
include_role:
ansible.builtin.include_role:
name: myrole
vars:
rolevar1: value from task
- name: Use role in loop
include_role:
ansible.builtin.include_role:
name: '{{ roleinputvar }}'
loop:
- '{{ roleinput1 }}'
@ -120,12 +120,12 @@ EXAMPLES = r'''
loop_var: roleinputvar
- name: Conditional role
include_role:
ansible.builtin.include_role:
name: myrole
when: not idontwanttorun
- name: Apply tags to tasks within included file
include_role:
ansible.builtin.include_role:
name: install
apply:
tags:

@ -56,26 +56,26 @@ seealso:
EXAMPLES = r'''
- hosts: all
tasks:
- debug:
- ansible.builtin.debug:
msg: task1
- name: Include task list in play
include_tasks: stuff.yaml
ansible.builtin.include_tasks: stuff.yaml
- debug:
- ansible.builtin.debug:
msg: task10
- hosts: all
tasks:
- debug:
- ansible.builtin.debug:
msg: task1
- name: Include task list in play only if the condition is true
include_tasks: "{{ hostvar }}.yaml"
ansible.builtin.include_tasks: "{{ hostvar }}.yaml"
when: hostvar is defined
- name: Apply tags to tasks within included file
include_tasks:
ansible.builtin.include_tasks:
file: install.yml
apply:
tags:
@ -84,7 +84,7 @@ EXAMPLES = r'''
- always
- name: Apply tags to tasks within included file when using free-form
include_tasks: install.yml
ansible.builtin.include_tasks: install.yml
args:
apply:
tags:

@ -114,18 +114,18 @@ seealso:
EXAMPLES = r'''
- name: Include vars of stuff.yaml into the 'stuff' variable (2.2).
include_vars:
ansible.builtin.include_vars:
file: stuff.yaml
name: stuff
- name: Conditionally decide to load in variables into 'plans' when x is 0, otherwise do not. (2.2)
include_vars:
ansible.builtin.include_vars:
file: contingency_plan.yaml
name: plans
when: x == 0
- name: Load a variable file based on the OS type, or a default if not found. Using free-form to specify the file.
include_vars: "{{ lookup('first_found', params) }}"
ansible.builtin.include_vars: "{{ lookup('ansible.builtin.first_found', params) }}"
vars:
params:
files:
@ -136,32 +136,32 @@ EXAMPLES = r'''
- 'vars'
- name: Bare include (free-form)
include_vars: myvars.yaml
ansible.builtin.include_vars: myvars.yaml
- name: Include all .json and .jsn files in vars/all and all nested directories (2.3)
include_vars:
ansible.builtin.include_vars:
dir: vars/all
extensions:
- 'json'
- 'jsn'
- name: Include all default extension files in vars/all and all nested directories and save the output in test. (2.2)
include_vars:
ansible.builtin.include_vars:
dir: vars/all
name: test
- name: Include default extension files in vars/services (2.2)
include_vars:
ansible.builtin.include_vars:
dir: vars/services
depth: 1
- name: Include only files matching bastion.yaml (2.2)
include_vars:
ansible.builtin.include_vars:
dir: vars
files_matching: bastion.yaml
- name: Include all .yaml files except bastion.yaml (2.3)
include_vars:
ansible.builtin.include_vars:
dir: vars
ignore_files:
- 'bastion.yaml'
@ -169,7 +169,7 @@ EXAMPLES = r'''
- 'yaml'
- name: Ignore warnings raised for files with unknown extensions while loading (2.7)
include_vars:
ansible.builtin.include_vars:
dir: vars
ignore_unknown_extensions: True
extensions:

@ -70,20 +70,20 @@ author:
EXAMPLES = r'''
- name: Tell the host about our servers it might want to ssh to
known_hosts:
ansible.builtin.known_hosts:
path: /etc/ssh/ssh_known_hosts
name: foo.com.invalid
key: "{{ lookup('file', 'pubkeys/foo.com.invalid') }}"
key: "{{ lookup('ansible.builtin.file', 'pubkeys/foo.com.invalid') }}"
- name: Another way to call known_hosts
known_hosts:
ansible.builtin.known_hosts:
name: host1.example.com # or 10.9.8.77
key: host1.example.com,10.9.8.77 ssh-rsa ASDeararAIUHI324324 # some key gibberish
path: /etc/ssh/ssh_known_hosts
state: present
- name: Add host with custom SSH port
known_hosts:
ansible.builtin.known_hosts:
name: '[host1.example.com]:2222'
key: '[host1.example.com]:2222 ssh-rsa ASDeararAIUHI324324' # some key gibberish
path: /etc/ssh/ssh_known_hosts

@ -186,7 +186,7 @@ EXAMPLES = r'''
mode: '0644'
- name: Replace a localhost entry searching for a literal string to avoid escaping
lineinfile:
ansible.builtin.lineinfile:
path: /etc/hosts
search_string: '127.0.0.1'
line: 127.0.0.1 localhost
@ -202,7 +202,7 @@ EXAMPLES = r'''
line: Listen 8080
- name: Ensure php extension matches new pattern
lineinfile:
ansible.builtin.lineinfile:
path: /etc/httpd/conf/httpd.conf
search_string: '<FilesMatch ".php[45]?$">'
insertafter: '^\t<Location \/>\n'

@ -76,13 +76,13 @@ author:
EXAMPLES = r'''
# Example showing flushing handlers on demand, not at end of play
- template:
- ansible.builtin.template:
src: new.j2
dest: /etc/config.txt
notify: myhandler
- name: Force all notified handlers to run at this point, not waiting for normal sync points
meta: flush_handlers
ansible.builtin.meta: flush_handlers
# Example showing how to refresh inventory during play
- name: Reload inventory, useful with dynamic inventories when play makes changes to the existing hosts
@ -91,32 +91,32 @@ EXAMPLES = r'''
state: present
- name: Refresh inventory to ensure new instances exist in inventory
meta: refresh_inventory
ansible.builtin.meta: refresh_inventory
# Example showing how to clear all existing facts of targetted hosts
- name: Clear gathered facts from all currently targeted hosts
meta: clear_facts
ansible.builtin.meta: clear_facts
# Example showing how to continue using a failed target
- name: Bring host back to play after failure
copy:
ansible.builtin.copy:
src: file
dest: /etc/file
remote_user: imightnothavepermission
- meta: clear_host_errors
- ansible.builtin.meta: clear_host_errors
# Example showing how to reset an existing connection
- user:
- ansible.builtin.user:
name: '{{ ansible_user }}'
groups: input
- name: Reset ssh connection to allow user changes to affect 'current login user'
meta: reset_connection
ansible.builtin.meta: reset_connection
# Example showing how to end the play for specific targets
- name: End the play for hosts that run CentOS 6
meta: end_host
ansible.builtin.meta: end_host
when:
- ansible_distribution == 'CentOS'
- ansible_distribution_major_version == '6'

@ -67,18 +67,18 @@ notes:
EXAMPLES = '''
- name: Pause for 5 minutes to build app cache
pause:
ansible.builtin.pause:
minutes: 5
- name: Pause until you can verify updates to an application were successful
pause:
ansible.builtin.pause:
- name: A helpful reminder of what to look out for post-update
pause:
ansible.builtin.pause:
prompt: "Make sure org.foo.FooOverload exception is not present"
- name: Pause to get some sensitive input
pause:
ansible.builtin.pause:
prompt: "Enter a secret"
echo: no
'''

@ -46,7 +46,7 @@ author:
EXAMPLES = '''
# Test we can logon to 'webservers' and execute python with json lib.
# ansible webservers -m ping
# ansible webservers -m ansible.builtin.ping
- name: Example from an Ansible Playbook
ansible.builtin.ping:

@ -141,26 +141,26 @@ author:
EXAMPLES = '''
- name: Install bottle python package
pip:
ansible.builtin.pip:
name: bottle
- name: Install bottle python package on version 0.11
pip:
ansible.builtin.pip:
name: bottle==0.11
- name: Install bottle python package with version specifiers
pip:
ansible.builtin.pip:
name: bottle>0.10,<0.20,!=0.11
- name: Install multi python packages with version specifiers
pip:
ansible.builtin.pip:
name:
- django>1.11.0,<1.12.0
- bottle>0.10,<0.20,!=0.11
- name: Install python package using a proxy
# Pip doesn't use the standard environment variables, please use the CAPITALIZED ones below
pip:
ansible.builtin.pip:
name: six
environment:
HTTP_PROXY: '127.0.0.1:8080'
@ -168,70 +168,70 @@ EXAMPLES = '''
# You do not have to supply '-e' option in extra_args
- name: Install MyApp using one of the remote protocols (bzr+,hg+,git+,svn+)
pip:
ansible.builtin.pip:
name: svn+http://myrepo/svn/MyApp#egg=MyApp
- name: Install MyApp using one of the remote protocols (bzr+,hg+,git+)
pip:
ansible.builtin.pip:
name: git+http://myrepo/app/MyApp
- name: Install MyApp from local tarball
pip:
ansible.builtin.pip:
name: file:///path/to/MyApp.tar.gz
- name: Install bottle into the specified (virtualenv), inheriting none of the globally installed modules
pip:
ansible.builtin.pip:
name: bottle
virtualenv: /my_app/venv
- name: Install bottle into the specified (virtualenv), inheriting globally installed modules
pip:
ansible.builtin.pip:
name: bottle
virtualenv: /my_app/venv
virtualenv_site_packages: yes
- name: Install bottle into the specified (virtualenv), using Python 2.7
pip:
ansible.builtin.pip:
name: bottle
virtualenv: /my_app/venv
virtualenv_command: virtualenv-2.7
- name: Install bottle within a user home directory
pip:
ansible.builtin.pip:
name: bottle
extra_args: --user
- name: Install specified python requirements
pip:
ansible.builtin.pip:
requirements: /my_app/requirements.txt
- name: Install specified python requirements in indicated (virtualenv)
pip:
ansible.builtin.pip:
requirements: /my_app/requirements.txt
virtualenv: /my_app/venv
- name: Install specified python requirements and custom Index URL
pip:
ansible.builtin.pip:
requirements: /my_app/requirements.txt
extra_args: -i https://example.com/pypi/simple
- name: Install specified python requirements offline from a local directory with downloaded packages
pip:
ansible.builtin.pip:
requirements: /my_app/requirements.txt
extra_args: "--no-index --find-links=file:///my_downloaded_packages_dir"
- name: Install bottle for Python 3.3 specifically, using the 'pip3.3' executable
pip:
ansible.builtin.pip:
name: bottle
executable: pip3.3
- name: Install bottle, forcing reinstallation if it's already installed
pip:
ansible.builtin.pip:
name: bottle
state: forcereinstall
- name: Install bottle while ensuring the umask is 0022 (to ensure other users can use it)
pip:
ansible.builtin.pip:
name: bottle
umask: "0022"
become: True

@ -73,16 +73,16 @@ author:
EXAMPLES = r'''
- name: Bootstrap a host without python2 installed
raw: dnf install -y python2 python2-dnf libselinux-python
ansible.builtin.raw: dnf install -y python2 python2-dnf libselinux-python
- name: Run a command that uses non-posix shell-isms (in this example /bin/sh doesn't handle redirection and wildcards together but bash does)
raw: cat < /tmp/*txt
ansible.builtin.raw: cat < /tmp/*txt
args:
executable: /bin/bash
- name: Safely use templated variables. Always use quote filter to avoid injection issues.
raw: "{{ package_mgr|quote }} {{ pkg_flags|quote }} install {{ python|quote }}"
ansible.builtin.raw: "{{ package_mgr|quote }} {{ pkg_flags|quote }} install {{ python|quote }}"
- name: List user accounts on a Windows system
raw: Get-WmiObject -Class Win32_UserAccount
ansible.builtin.raw: Get-WmiObject -Class Win32_UserAccount
'''

@ -104,19 +104,19 @@ author:
EXAMPLES = r'''
- name: Unconditionally reboot the machine with all defaults
reboot:
ansible.builtin.reboot:
- name: Reboot a slow machine that might have lots of updates to apply
reboot:
ansible.builtin.reboot:
reboot_timeout: 3600
- name: Reboot a machine with shutdown command in unusual place
reboot:
ansible.builtin.reboot:
search_paths:
- '/lib/molly-guard'
- name: Reboot machine using a custom reboot command
reboot:
ansible.builtin.reboot:
reboot_command: launchctl reboot userspace
boot_time_command: uptime | cut -d ' ' -f 5

@ -82,22 +82,22 @@ author:
EXAMPLES = r'''
- name: Setting host facts using key=value pairs, this format can only create strings or booleans
set_fact: one_fact="something" other_fact="{{ local_var }}"
ansible.builtin.set_fact: one_fact="something" other_fact="{{ local_var }}"
- name: Setting host facts using complex arguments
set_fact:
ansible.builtin.set_fact:
one_fact: something
other_fact: "{{ local_var * 2 }}"
another_fact: "{{ some_registered_var.results | map(attribute='ansible_facts.some_fact') | list }}"
- name: Setting facts so that they will be persisted in the fact cache
set_fact:
ansible.builtin.set_fact:
one_fact: something
other_fact: "{{ local_var * 2 }}"
cacheable: yes
- name: Creating list and dictionary variables
set_fact:
ansible.builtin.set_fact:
one_dict:
something: here
other: there
@ -105,9 +105,16 @@ EXAMPLES = r'''
- a
- b
- c
# As of Ansible 1.8, Ansible will convert boolean strings ('true', 'false', 'yes', 'no')
# to proper boolean values when using the key=value syntax, however it is still
# recommended that booleans be set using the complex argument style:
- name: Setting booleans using complex argument style
ansible.builtin.set_fact:
one_fact: yes
other_fact: no
- name: Creating list and dictionary variables using 'shorthand' YAML
set_fact:
ansible.builtin.set_fact:
two_dict: {'something': here2, 'other': somewhere}
two_list: [1,2,3]
'''

@ -53,7 +53,7 @@ EXAMPLES = r'''
msg: "{{ mounts['content'] | b64decode }}"
# From the commandline, find the pid of the remote machine's sshd
# $ ansible host -m slurp -a 'src=/var/run/sshd.pid'
# $ ansible host -m ansible.builtin.slurp -a 'src=/var/run/sshd.pid'
# host | SUCCESS => {
# "changed": false,
# "content": "MjE3OQo=",

@ -82,13 +82,13 @@ requirements:
EXAMPLES = '''
- name: Make sure apache2 is started
sysvinit:
ansible.builtin.sysvinit:
name: apache2
state: started
enabled: yes
- name: Make sure apache2 is started on runlevels 3 and 5
sysvinit:
ansible.builtin.sysvinit:
name: apache2
state: started
enabled: yes

@ -221,29 +221,29 @@ author:
EXAMPLES = r'''
- name: Check that you can connect (GET) to a page and it returns a status 200
uri:
ansible.builtin.uri:
url: http://www.example.com
- name: Check that a page returns a status 200 and fail if the word AWESOME is not in the page contents
uri:
ansible.builtin.uri:
url: http://www.example.com
return_content: yes
register: this
failed_when: "'AWESOME' not in this.content"
- name: Create a JIRA issue
uri:
ansible.builtin.uri:
url: https://your.jira.example.com/rest/api/2/issue/
user: your_username
password: your_pass
method: POST
body: "{{ lookup('file','issue.json') }}"
body: "{{ lookup('ansible.builtin.file','issue.json') }}"
force_basic_auth: yes
status_code: 201
body_format: json
- name: Login to a form based webpage, then use the returned cookie to access the app in later tasks
uri:
ansible.builtin.uri:
url: https://your.form.based.auth.example.com/index.php
method: POST
body_format: form-urlencoded
@ -255,7 +255,7 @@ EXAMPLES = r'''
register: login
- name: Login to a form based webpage using a list of tuples
uri:
ansible.builtin.uri:
url: https://your.form.based.auth.example.com/index.php
method: POST
body_format: form-urlencoded
@ -267,7 +267,7 @@ EXAMPLES = r'''
register: login
- name: Upload a file via multipart/form-multipart
uri:
ansible.builtin.uri:
url: https://httpbin.org/post
method: POST
body_format: form-multipart
@ -282,7 +282,7 @@ EXAMPLES = r'''
text_form_field: value
- name: Connect to website using a previously stored cookie
uri:
ansible.builtin.uri:
url: https://your.form.based.auth.example.com/dashboard.php
method: GET
return_content: yes
@ -290,7 +290,7 @@ EXAMPLES = r'''
Cookie: "{{ login.cookies_string }}"
- name: Queue build of a project in Jenkins
uri:
ansible.builtin.uri:
url: http://{{ jenkins.host }}/job/{{ jenkins.job }}/build?token={{ jenkins.token }}
user: "{{ jenkins.user }}"
password: "{{ jenkins.password }}"
@ -299,20 +299,20 @@ EXAMPLES = r'''
status_code: 201
- name: POST from contents of local file
uri:
ansible.builtin.uri:
url: https://httpbin.org/post
method: POST
src: file.json
- name: POST from contents of remote file
uri:
ansible.builtin.uri:
url: https://httpbin.org/post
method: POST
src: /path/to/my/file.json
remote_src: yes
- name: Create workspaces in Log analytics Azure
uri:
ansible.builtin.uri:
url: https://www.mms.microsoft.com/Embedded/Api/ConfigDataSources/LogManagementData/Save
method: POST
body_format: json
@ -326,7 +326,7 @@ EXAMPLES = r'''
body:
- name: Pause play until a URL is reachable from this host
uri:
ansible.builtin.uri:
url: "http://192.0.2.1/some/test"
follow_redirects: none
method: GET
@ -339,7 +339,7 @@ EXAMPLES = r'''
# https://github.com/ansible/ansible/issues/52705 where a proxy is defined
# but you want to bypass proxy use on CIDR masks by using no_proxy
- name: Work around a python issue that doesn't support no_proxy envvar
uri:
ansible.builtin.uri:
follow_redirects: none
validate_certs: false
timeout: 5
@ -351,7 +351,7 @@ EXAMPLES = r'''
ip_address: 192.0.2.1
environment: |
{
{% for no_proxy in (lookup('env', 'no_proxy') | regex_replace('\s*,\s*', ' ') ).split() %}
{% for no_proxy in (lookup('ansible.builtin.env', 'no_proxy') | regex_replace('\s*,\s*', ' ') ).split() %}
{% if no_proxy | regex_search('\/') and
no_proxy | ipaddr('net') != '' and
no_proxy | ipaddr('net') != false and

@ -329,12 +329,12 @@ EXAMPLES = r'''
expires: -1
- name: Set maximum expiration date for password
user:
ansible.builtin.user:
name: ram19
password_expire_max: 10
- name: Set minimum expiration date for password
user:
ansible.builtin.user:
name: pushkar15
password_expire_min: 5
'''

@ -51,7 +51,7 @@ attributes:
EXAMPLES = r'''
- name: verify vars needed for this task file are present when included
validate_argument_spec:
ansible.builtin.validate_argument_spec:
argument_spec: '{{required_data}}'
vars:
required_data:
@ -68,14 +68,14 @@ EXAMPLES = r'''
- name: verify vars needed for this task file are present when included, with spec from a spec file
validate_argument_spec:
argument_spec: "{{lookup('file', 'myargspec.yml')['specname']['options']}}"
ansible.builtin.validate_argument_spec:
argument_spec: "{{lookup('ansible.builtin.file', 'myargspec.yml')['specname']['options']}}"
- name: verify vars needed for next include and not from inside it, also with params i'll only define there
block:
- validate_argument_spec:
argument_spec: "{{lookup('file', 'nakedoptions.yml'}}"
- ansible.builtin.validate_argument_spec:
argument_spec: "{{lookup('ansible.builtin.file', 'nakedoptions.yml'}}"
provided_arguments:
but: "that i can define on the include itself, like in it's C(vars:) keyword"

@ -125,65 +125,65 @@ author:
EXAMPLES = r'''
- name: Sleep for 300 seconds and continue with play
wait_for:
ansible.builtin.wait_for:
timeout: 300
delegate_to: localhost
- name: Wait for port 8000 to become open on the host, don't start checking for 10 seconds
wait_for:
ansible.builtin.wait_for:
port: 8000
delay: 10
- name: Waits for port 8000 of any IP to close active connections, don't start checking for 10 seconds
wait_for:
ansible.builtin.wait_for:
host: 0.0.0.0
port: 8000
delay: 10
state: drained
- name: Wait for port 8000 of any IP to close active connections, ignoring connections for specified hosts
wait_for:
ansible.builtin.wait_for:
host: 0.0.0.0
port: 8000
state: drained
exclude_hosts: 10.2.1.2,10.2.1.3
- name: Wait until the file /tmp/foo is present before continuing
wait_for:
ansible.builtin.wait_for:
path: /tmp/foo
- name: Wait until the string "completed" is in the file /tmp/foo before continuing
wait_for:
ansible.builtin.wait_for:
path: /tmp/foo
search_regex: completed
- name: Wait until regex pattern matches in the file /tmp/foo and print the matched group
wait_for:
ansible.builtin.wait_for:
path: /tmp/foo
search_regex: completed (?P<task>\w+)
register: waitfor
- debug:
- ansible.builtin.debug:
msg: Completed {{ waitfor['match_groupdict']['task'] }}
- name: Wait until the lock file is removed
wait_for:
ansible.builtin.wait_for:
path: /var/lock/file.lock
state: absent
- name: Wait until the process is finished and pid was destroyed
wait_for:
ansible.builtin.wait_for:
path: /proc/3466/status
state: absent
- name: Output customized message when failed
wait_for:
ansible.builtin.wait_for:
path: /tmp/foo
state: present
msg: Timeout to find file /tmp/foo
# Do not assume the inventory_hostname is resolvable and delay 10 seconds at start
- name: Wait 300 seconds for port 22 to become open and contain "OpenSSH"
wait_for:
ansible.builtin.wait_for:
port: 22
host: '{{ (ansible_ssh_host|default(ansible_host))|default(inventory_hostname) }}'
search_regex: OpenSSH
@ -192,7 +192,7 @@ EXAMPLES = r'''
# Same as above but you normally have ansible_connection set in inventory, which overrides 'connection'
- name: Wait 300 seconds for port 22 to become open and contain "OpenSSH"
wait_for:
ansible.builtin.wait_for:
port: 22
host: '{{ (ansible_ssh_host|default(ansible_host))|default(inventory_hostname) }}'
search_regex: OpenSSH

@ -66,10 +66,10 @@ author:
EXAMPLES = r'''
- name: Wait 600 seconds for target connection to become reachable/usable
wait_for_connection:
ansible.builtin.wait_for_connection:
- name: Wait 300 seconds, but only start checking after 60 seconds
wait_for_connection:
ansible.builtin.wait_for_connection:
delay: 60
timeout: 300
@ -78,23 +78,23 @@ EXAMPLES = r'''
gather_facts: no
tasks:
- name: Send magic Wake-On-Lan packet to turn on individual systems
wakeonlan:
community.general.wakeonlan:
mac: '{{ mac }}'
broadcast: 192.168.0.255
delegate_to: localhost
- name: Wait for system to become reachable
wait_for_connection:
ansible.builtin.wait_for_connection:
- name: Gather facts for first time
setup:
ansible.builtin.setup:
# Build a new VM, wait for it to become ready and continue playbook
- hosts: all
gather_facts: no
tasks:
- name: Clone new VM, if missing
vmware_guest:
community.vmware.vmware_guest:
hostname: '{{ vcenter_ipaddress }}'
name: '{{ inventory_hostname_short }}'
template: Windows 2012R2
@ -105,11 +105,11 @@ EXAMPLES = r'''
delegate_to: localhost
- name: Wait for system to become reachable over WinRM
wait_for_connection:
ansible.builtin.wait_for_connection:
timeout: 900
- name: Gather facts for first time
setup:
ansible.builtin.setup:
'''
RETURN = r'''

@ -303,17 +303,17 @@ author:
EXAMPLES = '''
- name: Install the latest version of Apache
yum:
ansible.builtin.yum:
name: httpd
state: latest
- name: Install Apache >= 2.4
yum:
ansible.builtin.yum:
name: httpd>=2.4
state: present
- name: Install a list of packages (suitable replacement for 2.11 loop deprecation warning)
yum:
ansible.builtin.yum:
name:
- nginx
- postgresql
@ -321,7 +321,7 @@ EXAMPLES = '''
state: present
- name: Install a list of packages with a list variable
yum:
ansible.builtin.yum:
name: "{{ packages }}"
vars:
packages:
@ -329,69 +329,69 @@ EXAMPLES = '''
- httpd-tools
- name: Remove the Apache package
yum:
ansible.builtin.yum:
name: httpd
state: absent
- name: Install the latest version of Apache from the testing repo
yum:
ansible.builtin.yum:
name: httpd
enablerepo: testing
state: present
- name: Install one specific version of Apache
yum:
ansible.builtin.yum:
name: httpd-2.2.29-1.4.amzn1
state: present
- name: Upgrade all packages
yum:
ansible.builtin.yum:
name: '*'
state: latest
- name: Upgrade all packages, excluding kernel & foo related packages
yum:
ansible.builtin.yum:
name: '*'
state: latest
exclude: kernel*,foo*
- name: Install the nginx rpm from a remote repo
yum:
ansible.builtin.yum:
name: http://nginx.org/packages/centos/6/noarch/RPMS/nginx-release-centos-6-0.el6.ngx.noarch.rpm
state: present
- name: Install nginx rpm from a local file
yum:
ansible.builtin.yum:
name: /usr/local/src/nginx-release-centos-6-0.el6.ngx.noarch.rpm
state: present
- name: Install the 'Development tools' package group
yum:
ansible.builtin.yum:
name: "@Development tools"
state: present
- name: Install the 'Gnome desktop' environment group
yum:
ansible.builtin.yum:
name: "@^gnome-desktop-environment"
state: present
- name: List ansible packages and register result to print with debug later
yum:
ansible.builtin.yum:
list: ansible
register: result
- name: Install package with multiple repos enabled
yum:
ansible.builtin.yum:
name: sos
enablerepo: "epel,ol7_latest"
- name: Install package with multiple repos disabled
yum:
ansible.builtin.yum:
name: sos
disablerepo: "epel,ol7_latest"
- name: Download the nginx package but do not install it
yum:
ansible.builtin.yum:
name:
- nginx
state: latest

@ -378,13 +378,13 @@ notes:
EXAMPLES = '''
- name: Add repository
yum_repository:
ansible.builtin.yum_repository:
name: epel
description: EPEL YUM repo
baseurl: https://download.fedoraproject.org/pub/epel/$releasever/$basearch/
- name: Add multiple repositories into the same file (1/2)
yum_repository:
ansible.builtin.yum_repository:
name: epel
description: EPEL YUM repo
file: external_repos
@ -392,7 +392,7 @@ EXAMPLES = '''
gpgcheck: no
- name: Add multiple repositories into the same file (2/2)
yum_repository:
ansible.builtin.yum_repository:
name: rpmforge
description: RPMforge YUM repo
file: external_repos
@ -402,19 +402,19 @@ EXAMPLES = '''
# Handler showing how to clean yum metadata cache
- name: yum-clean-metadata
command: yum clean metadata
ansible.builtin.command: yum clean metadata
args:
warn: no
# Example removing a repository and cleaning up metadata cache
- name: Remove repository (and clean up left-over metadata)
yum_repository:
ansible.builtin.yum_repository:
name: epel
state: absent
notify: yum-clean-metadata
- name: Remove repository from a specific repo file
yum_repository:
ansible.builtin.yum_repository:
name: epel
file: external_repos
state: absent

@ -37,31 +37,31 @@ DOCUMENTATION = """
EXAMPLES = """
- name: Show configured default become user
debug: msg="{{ lookup('config', 'DEFAULT_BECOME_USER')}}"
ansible.builtin.debug: msg="{{ lookup('ansible.builtin.config', 'DEFAULT_BECOME_USER')}}"
- name: print out role paths
debug:
msg: "These are the configured role paths: {{lookup('config', 'DEFAULT_ROLES_PATH')}}"
ansible.builtin.debug:
msg: "These are the configured role paths: {{lookup('ansible.builtin.config', 'DEFAULT_ROLES_PATH')}}"
- name: find retry files, skip if missing that key
find:
paths: "{{lookup('config', 'RETRY_FILES_SAVE_PATH')|default(playbook_dir, True)}}"
ansible.builtin.find:
paths: "{{lookup('ansible.builtin.config', 'RETRY_FILES_SAVE_PATH')|default(playbook_dir, True)}}"
patterns: "*.retry"
- name: see the colors
debug: msg="{{item}}"
loop: "{{lookup('config', 'COLOR_OK', 'COLOR_CHANGED', 'COLOR_SKIP', wantlist=True)}}"
ansible.builtin.debug: msg="{{item}}"
loop: "{{lookup('ansible.builtin.config', 'COLOR_OK', 'COLOR_CHANGED', 'COLOR_SKIP', wantlist=True)}}"
- name: skip if bad value in var
debug: msg="{{ lookup('config', config_in_var, on_missing='skip')}}"
ansible.builtin.debug: msg="{{ lookup('ansible.builtin.config', config_in_var, on_missing='skip')}}"
var:
config_in_var: UNKNOWN
- name: show remote user and port for ssh connection
debug: msg={{q("config", "remote_user", "port", plugin_type="connection", plugin_name="ssh", on_missing='skip')}}
ansible.builtin.debug: msg={{q("ansible.builtin.config", "remote_user", "port", plugin_type="connection", plugin_name="ssh", on_missing='skip')}}
- name: show remote_tmp setting for shell (sh) plugin
debug: msg={{q("config", "remote_tmp", plugin_type="shell", plugin_name="sh")}}
ansible.builtin.debug: msg={{q("ansible.builtin.config", "remote_tmp", plugin_type="shell", plugin_name="sh")}}
"""
RETURN = """

@ -39,13 +39,13 @@ DOCUMENTATION = """
EXAMPLES = """
- name: Match 'Li' on the first column, return the second column (0 based index)
debug: msg="The atomic number of Lithium is {{ lookup('csvfile', 'Li', file='elements.csv', delimiter=',') }}"
ansible.builtin.debug: msg="The atomic number of Lithium is {{ lookup('ansible.builtin.csvfile', 'Li file=elements.csv delimiter=,') }}"
- name: msg="Match 'Li' on the first column, but return the 3rd column (columns start counting after the match)"
debug: msg="The atomic mass of Lithium is {{ lookup('csvfile', 'Li', file='elements.csv', delimiter=',', col=2) }}"
ansible.builtin.debug: msg="The atomic mass of Lithium is {{ lookup('ansible.builtin.csvfile', 'Li file=elements.csv delimiter=, col=2') }}"
- name: Define Values From CSV File, this reads file in one go, but you could also use col= to read each in it's own lookup.
set_fact:
ansible.builtin.set_fact:
loop_ip: "{{ csvline[0] }}"
int_ip: "{{ csvline[1] }}"
int_mask: "{{ csvline[2] }}"
@ -54,7 +54,7 @@ EXAMPLES = """
neighbor_as: "{{ csvline[5] }}"
neigh_int_ip: "{{ csvline[6] }}"
vars:
csvline = "{{ lookup('csvfile', bgp_neighbor_ip, file='bgp_neighbors.csv', delimiter=',') }}"
csvline = "{{ lookup('ansible.builtin.csvfile', bgp_neighbor_ip, file='bgp_neighbors.csv', delimiter=',') }}"
delegate_to: localhost
"""

@ -30,19 +30,19 @@ vars:
tasks:
# with predefined vars
- name: Print phone records
debug:
ansible.builtin.debug:
msg: "User {{ item.key }} is {{ item.value.name }} ({{ item.value.telephone }})"
loop: "{{ lookup('dict', users) }}"
loop: "{{ lookup('ansible.builtin.dict', users) }}"
# with inline dictionary
- name: show dictionary
debug:
ansible.builtin.debug:
msg: "{{item.key}}: {{item.value}}"
with_dict: {a: 1, b: 2, c: 3}
# Items from loop can be used in when: statements
- name: set_fact when alice in key
set_fact:
ansible.builtin.set_fact:
alice_exists: true
loop: "{{ lookup('dict', users) }}"
loop: "{{ lookup('ansible.builtin.dict', users) }}"
when: "'alice' in item.key"
"""

@ -28,25 +28,25 @@ DOCUMENTATION = """
EXAMPLES = """
- name: Basic usage
debug:
msg: "{{ lookup('env', 'HOME') }} is the HOME environment variable."
ansible.builtin.debug:
msg: "'{{ lookup('ansible.builtin.env', 'HOME') }}' is the HOME environment variable."
- name: Before 2.13, how to set default value if the variable is not defined.
This cannot distinguish between USR undefined and USR=''.
debug:
msg: "{{ lookup('env', 'USR')|default('nobody', True) }} is the user."
ansible.builtin.debug:
msg: "{{ lookup('ansible.builtin.env', 'USR')|default('nobody', True) }} is the user."
- name: Example how to set default value if the variable is not defined, ignores USR=''
debug:
msg: "{{ lookup('env', 'USR', default='nobody') }} is the user."
ansible.builtin.debug:
msg: "{{ lookup('ansible.builtin.env', 'USR', default='nobody') }} is the user."
- name: Set default value to Undefined, if the variable is not defined
debug:
msg: "{{ lookup('env', 'USR', default=Undefined) }} is the user."
ansible.builtin.debug:
msg: "{{ lookup('ansible.builtin.env', 'USR', default=Undefined) }} is the user."
- name: Set default value to undef(), if the variable is not defined
debug:
msg: "{{ lookup('env', 'USR', default=undef()) }} is the user."
ansible.builtin.debug:
msg: "{{ lookup('ansible.builtin.env', 'USR', default=undef()) }} is the user."
"""
RETURN = """

@ -31,10 +31,11 @@ DOCUMENTATION = """
"""
EXAMPLES = """
- debug: msg="the value of foo.txt is {{lookup('file', '/etc/foo.txt') }}"
- ansible.builtin.debug:
msg: "the value of foo.txt is {{lookup('ansible.builtin.file', '/etc/foo.txt') }}"
- name: display multiple file contents
debug: var=item
ansible.builtin.debug: var=item
with_file:
- "/path/to/foo.txt"
- "bar.txt" # will be looked in files/ dir relative to play or in role

@ -25,10 +25,10 @@ DOCUMENTATION = """
EXAMPLES = """
- name: Display paths of all .txt files in dir
debug: msg={{ lookup('fileglob', '/my/path/*.txt') }}
ansible.builtin.debug: msg={{ lookup('ansible.builtin.fileglob', '/my/path/*.txt') }}
- name: Copy each file over that matches the given pattern
copy:
ansible.builtin.copy:
src: "{{ item }}"
dest: "/etc/fooapp/"
owner: "root"

@ -47,8 +47,8 @@ DOCUMENTATION = """
EXAMPLES = """
- name: Set _found_file to the first existing file, raising an error if a file is not found
set_fact:
_found_file: "{{ lookup('first_found', findme) }}"
ansible.builtin.set_fact:
_found_file: "{{ lookup('ansible.builtin.first_found', findme) }}"
vars:
findme:
- /path/to/foo.txt
@ -56,15 +56,15 @@ EXAMPLES = """
- /path/to/biz.txt
- name: Set _found_file to the first existing file, or an empty list if no files found
set_fact:
_found_file: "{{ lookup('first_found', files, paths=['/extra/path'], skip=True) }}"
ansible.builtin.set_fact:
_found_file: "{{ lookup('ansible.builtin.first_found', files, paths=['/extra/path'], skip=True) }}"
vars:
files:
- /path/to/foo.txt
- /path/to/bar.txt
- name: Include tasks only if one of the files exist, otherwise skip the task
include_tasks:
ansible.builtin.include_tasks:
file: "{{ item }}"
with_first_found:
files:
@ -73,17 +73,17 @@ EXAMPLES = """
skip: True
- name: Include tasks only if one of the files exists, otherwise skip
include_tasks: '{{ tasks_file }}'
ansible.builtin.include_tasks: '{{ tasks_file }}'
when: tasks_file != ""
vars:
tasks_file: "{{ lookup('first_found', files=['tasks.yaml', 'other_tasks.yaml'], errors='ignore') }}"
tasks_file: "{{ lookup('ansible.builtin.first_found', files=['tasks.yaml', 'other_tasks.yaml'], errors='ignore') }}"
- name: |
copy first existing file found to /some/file,
looking in relative directories from where the task is defined and
including any play objects that contain it
copy:
src: "{{ lookup('first_found', findme) }}"
ansible.builtin.copy:
src: "{{ lookup('ansible.builtin.first_found', findme) }}"
dest: /some/file
vars:
findme:
@ -92,8 +92,8 @@ EXAMPLES = """
- bar
- name: same copy but specific paths
copy:
src: "{{ lookup('first_found', params) }}"
ansible.builtin.copy:
src: "{{ lookup('ansible.builtin.first_found', params) }}"
dest: /some/file
vars:
params:
@ -106,8 +106,8 @@ EXAMPLES = """
- /tmp/staging
- name: INTERFACES | Create Ansible header for /etc/network/interfaces
template:
src: "{{ lookup('first_found', findme) }}"
ansible.builtin.template:
src: "{{ lookup('ansible.builtin.first_found', findme)}}"
dest: "/etc/foo.conf"
vars:
findme:
@ -115,7 +115,7 @@ EXAMPLES = """
- "default_foo.conf"
- name: read vars from first file found, use 'vars/' relative subdir
include_vars: "{{ lookup('first_found', params) }}"
ansible.builtin.include_vars: "{{lookup('ansible.builtin.first_found', params)}}"
vars:
params:
files:

@ -20,7 +20,7 @@ DOCUMENTATION = """
EXAMPLES = """
- name: indexed loop demo
debug:
ansible.builtin.debug:
msg: "at array position {{ item.0 }} there is a value {{ item.1 }}"
with_indexed_items:
- "{{ some_list }}"

@ -53,19 +53,19 @@ DOCUMENTATION = """
"""
EXAMPLES = """
- debug: msg="User in integration is {{ lookup('ini', 'user', section='integration', file='users.ini') }}"
- ansible.builtin.debug: msg="User in integration is {{ lookup('ansible.builtin.ini', 'user', section='integration', file='users.ini') }}"
- debug: msg="User in production is {{ lookup('ini', 'user', section='production', file='users.ini') }}"
- ansible.builtin.debug: msg="User in production is {{ lookup('ansible.builtin.ini', 'user', section='production', file='users.ini') }}"
- debug: msg="user.name is {{ lookup('ini', 'user.name', type='properties', file='user.properties') }}"
- ansible.builtin.debug: msg="user.name is {{ lookup('ansible.builtin.ini', 'user.name', type='properties', file='user.properties') }}"
- debug:
- ansible.builtin.debug:
msg: "{{ item }}"
loop: "{{ q('ini', '.*', section='section1', file='test.ini', re=True) }}"
loop: "{{ q('ansible.builtin.ini', '.*', section='section1', file='test.ini', re=True) }}"
- name: Read an ini file with allow_no_value
debug:
msg: "{{ lookup('ini', 'user', file='mysql.ini', section='mysqld', allow_no_value=True) }}"
ansible.builtin.debug:
msg: "{{ lookup('ansible.builtin.ini', 'user', file='mysql.ini', section='mysqld', allow_no_value=True) }}"
"""
RETURN = """

@ -22,7 +22,7 @@ DOCUMENTATION = """
EXAMPLES = """
- name: show all the hosts matching the pattern, i.e. all but the group www
debug:
ansible.builtin.debug:
msg: "{{ item }}"
with_inventory_hostnames:
- all:!www

@ -23,7 +23,7 @@ DOCUMENTATION = """
EXAMPLES = """
- name: "loop through list"
debug:
ansible.builtin.debug:
msg: "An item: {{ item }}"
with_items:
- 1
@ -31,7 +31,7 @@ EXAMPLES = """
- 3
- name: add several users
user:
ansible.builtin.user:
name: "{{ item }}"
groups: "wheel"
state: present
@ -40,12 +40,12 @@ EXAMPLES = """
- testuser2
- name: "loop through list from a variable"
debug:
ansible.builtin.debug:
msg: "An item: {{ item }}"
with_items: "{{ somelist }}"
- name: more complex items to add several users
user:
ansible.builtin.user:
name: "{{ item.name }}"
uid: "{{ item.uid }}"
groups: "{{ item.groups }}"

@ -24,11 +24,11 @@ DOCUMENTATION = """
EXAMPLES = """
- name: We could read the file directly, but this shows output from command
debug: msg="{{ item }} is an output line from running cat on /etc/motd"
ansible.builtin.debug: msg="{{ item }} is an output line from running cat on /etc/motd"
with_lines: cat /etc/motd
- name: More useful example of looping over a command result
shell: "/usr/bin/frobnicate {{ item }}"
ansible.builtin.shell: "/usr/bin/frobnicate {{ item }}"
with_lines:
- "/usr/bin/frobnications_per_host --param {{ inventory_hostname }}"
"""

@ -17,7 +17,7 @@ DOCUMENTATION = """
EXAMPLES = """
- name: unlike with_items you will get 3 items from this loop, the 2nd one being a list
debug: var=item
ansible.builtin.debug: var=item
with_list:
- 1
- [2,3]

@ -19,7 +19,7 @@ DOCUMENTATION = """
EXAMPLES = """
- name: give users access to multiple databases
mysql_user:
community.mysql.mysql_user:
name: "{{ item[0] }}"
priv: "{{ item[1] }}.*:ALL"
append_privs: yes
@ -30,7 +30,7 @@ EXAMPLES = """
# As with the case of 'with_items' above, you can use previously defined variables.:
- name: here, 'users' contains the above list of employees
mysql_user:
community.mysql.mysql_user:
name: "{{ item[0] }}"
priv: "{{ item[1] }}.*:ALL"
append_privs: yes

@ -81,36 +81,36 @@ DOCUMENTATION = """
EXAMPLES = """
- name: create a mysql user with a random password
mysql_user:
community.mysql.mysql_user:
name: "{{ client }}"
password: "{{ lookup('password', 'credentials/' + client + '/' + tier + '/' + role + '/mysqlpassword length=15') }}"
password: "{{ lookup('ansible.builtin.password', 'credentials/' + client + '/' + tier + '/' + role + '/mysqlpassword length=15') }}"
priv: "{{ client }}_{{ tier }}_{{ role }}.*:ALL"
- name: create a mysql user with a random password using only ascii letters
mysql_user:
community.mysql.mysql_user:
name: "{{ client }}"
password: "{{ lookup('password', '/tmp/passwordfile chars=ascii_letters') }}"
password: "{{ lookup('ansible.builtin.password', '/tmp/passwordfile chars=ascii_letters') }}"
priv: '{{ client }}_{{ tier }}_{{ role }}.*:ALL'
- name: create a mysql user with an 8 character random password using only digits
mysql_user:
community.mysql.mysql_user:
name: "{{ client }}"
password: "{{ lookup('password', '/tmp/passwordfile length=8 chars=digits') }}"
password: "{{ lookup('ansible.builtin.password', '/tmp/passwordfile length=8 chars=digits') }}"
priv: "{{ client }}_{{ tier }}_{{ role }}.*:ALL"
- name: create a mysql user with a random password using many different char sets
mysql_user:
community.mysql.mysql_user:
name: "{{ client }}"
password: "{{ lookup('password', '/tmp/passwordfile chars=ascii_letters,digits,punctuation') }}"
password: "{{ lookup('ansible.builtin.password', '/tmp/passwordfile chars=ascii_letters,digits,punctuation') }}"
priv: "{{ client }}_{{ tier }}_{{ role }}.*:ALL"
- name: create lowercase 8 character name for Kubernetes pod name
set_fact:
random_pod_name: "web-{{ lookup('password', '/dev/null chars=ascii_lowercase,digits length=8') }}"
ansible.builtin.set_fact:
random_pod_name: "web-{{ lookup('ansible.builtin.password', '/dev/null chars=ascii_lowercase,digits length=8') }}"
- name: create random but idempotent password
set_fact:
password: "{{ lookup('password', '/dev/null', seed=inventory_hostname) }}"
ansible.builtin.set_fact:
password: "{{ lookup('ansible.builtin.password', '/dev/null', seed=inventory_hostname) }}"
"""
RETURN = """

@ -28,12 +28,12 @@ DOCUMENTATION = r"""
EXAMPLES = r"""
- name: raw result of running date command"
debug:
msg: "{{ lookup('pipe', 'date') }}"
ansible.builtin.debug:
msg: "{{ lookup('ansible.builtin.pipe', 'date') }}"
- name: Always use quote filter to make sure your variables are safe to use with shell
debug:
msg: "{{ lookup('pipe', 'getent passwd ' + myuser | quote ) }}"
ansible.builtin.debug:
msg: "{{ lookup('ansible.builtin.pipe', 'getent passwd ' + myuser | quote ) }}"
"""
RETURN = r"""

@ -17,7 +17,7 @@ DOCUMENTATION = """
EXAMPLES = """
- name: Magic 8 ball for MUDs
debug:
ansible.builtin.debug:
msg: "{{ item }}"
with_random_choice:
- "go through the door"

@ -39,31 +39,31 @@ DOCUMENTATION = """
EXAMPLES = """
- name: create some test users
user:
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
file:
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
group:
ansible.builtin.group:
name: "group{{ item }}"
state: present
with_sequence: count=4
- name: the final countdown
debug:
ansible.builtin.debug:
msg: "{{item}} seconds to detonation"
with_sequence: start=10 end=0 stride=-1
- name: Use of variable
debug:
ansible.builtin.debug:
msg: "{{ item }}"
with_sequence: start=1 end="{{ end_at }}"
vars:

@ -56,7 +56,7 @@ EXAMPLES = """
- "DB2.*:ALL"
tasks:
- name: Set authorized ssh key, extracting just that data from 'users'
authorized_key:
ansible.posix.authorized_key:
user: "{{ item.0.name }}"
key: "{{ lookup('file', item.1) }}"
with_subelements:
@ -64,7 +64,7 @@ EXAMPLES = """
- authorized
- name: Setup MySQL users, given the mysql hosts and privs subkey lists
mysql_user:
community.mysql.mysql_user:
name: "{{ item.0.name }}"
password: "{{ item.0.mysql.password }}"
host: "{{ item.1 }}"
@ -74,8 +74,8 @@ EXAMPLES = """
- mysql.hosts
- name: list groups for users that have them, don't error if groups key is missing
debug: var=item
loop: "{{ q('subelements', users, 'groups', {'skip_missing': True}) }}"
ansible.builtin.debug: var=item
loop: "{{ q('ansible.builtin.subelements', users, 'groups', {'skip_missing': True}) }}"
"""
RETURN = """

@ -57,16 +57,16 @@ DOCUMENTATION = """
EXAMPLES = """
- name: show templating results
debug:
msg: "{{ lookup('template', './some_template.j2') }}"
ansible.builtin.debug:
msg: "{{ lookup('ansible.builtin.template', './some_template.j2') }}"
- name: show templating results with different variable start and end string
debug:
msg: "{{ lookup('template', './some_template.j2', variable_start_string='[%', variable_end_string='%]') }}"
ansible.builtin.debug:
msg: "{{ lookup('ansible.builtin.template', './some_template.j2', variable_start_string='[%', variable_end_string='%]') }}"
- name: show templating results with different comment start and end string
debug:
msg: "{{ lookup('template', './some_template.j2', comment_start_string='[#', comment_end_string='#]') }}"
ansible.builtin.debug:
msg: "{{ lookup('ansible.builtin.template', './some_template.j2', comment_start_string='[#', comment_end_string='#]') }}"
"""
RETURN = """

@ -22,7 +22,7 @@ DOCUMENTATION = """
EXAMPLES = """
- name: item.0 returns from the 'a' list, item.1 returns from the '1' list
debug:
ansible.builtin.debug:
msg: "{{ item.0 }} and {{ item.1 }}"
with_together:
- ['a', 'b', 'c', 'd']

@ -19,7 +19,7 @@ DOCUMENTATION = """
"""
EXAMPLES = """
- debug: msg="the value of foo.txt is {{lookup('unvault', '/etc/foo.txt')|to_string }}"
- ansible.builtin.debug: msg="the value of foo.txt is {{lookup('ansible.builtin.unvault', '/etc/foo.txt')|to_string }}"
"""
RETURN = """

@ -150,20 +150,22 @@ options:
EXAMPLES = """
- name: url lookup splits lines by default
debug: msg="{{item}}"
loop: "{{ lookup('url', 'https://github.com/gremlin.keys', wantlist=True) }}"
ansible.builtin.debug: msg="{{item}}"
loop: "{{ lookup('ansible.builtin.url', 'https://github.com/gremlin.keys', wantlist=True) }}"
- name: display ip ranges
debug: msg="{{ lookup('url', 'https://ip-ranges.amazonaws.com/ip-ranges.json', split_lines=False) }}"
ansible.builtin.debug: msg="{{ lookup('ansible.builtin.url', 'https://ip-ranges.amazonaws.com/ip-ranges.json', split_lines=False) }}"
- name: url lookup using authentication
debug: msg="{{ lookup('url', 'https://some.private.site.com/file.txt', username='bob', password='hunter2') }}"
ansible.builtin.debug: msg="{{ lookup('ansible.builtin.url', 'https://some.private.site.com/file.txt', username='bob', password='hunter2') }}"
- name: url lookup using basic authentication
debug: msg="{{ lookup('url', 'https://some.private.site.com/file.txt', username='bob', password='hunter2', force_basic_auth='True') }}"
ansible.builtin.debug:
msg: "{{ lookup('ansible.builtin.url', 'https://some.private.site.com/file.txt', username='bob', password='hunter2', force_basic_auth='True') }}"
- name: url lookup using headers
debug: msg="{{ lookup('url', 'https://some.private.site.com/api/service', headers={'header1':'value1', 'header2':'value2'} ) }}"
ansible.builtin.debug:
msg: "{{ lookup('ansible.builtin.url', 'https://some.private.site.com/api/service', headers={'header1':'value1', 'header2':'value2'} ) }}"
"""
RETURN = """

@ -18,7 +18,7 @@ DOCUMENTATION = """
EXAMPLES = """
- name: List variables that start with qz_
debug: msg="{{ lookup('varnames', '^qz_.+')}}"
ansible.builtin.debug: msg="{{ lookup('ansible.builtin.varnames', '^qz_.+')}}"
vars:
qz_1: hello
qz_2: world
@ -26,13 +26,13 @@ EXAMPLES = """
qz_: "I won't show either"
- name: Show all variables
debug: msg="{{ lookup('varnames', '.+')}}"
ansible.builtin.debug: msg="{{ lookup('ansible.builtin.varnames', '.+')}}"
- name: Show variables with 'hosts' in their names
debug: msg="{{ lookup('varnames', 'hosts')}}"
ansible.builtin.debug: msg="{{ lookup('ansible.builtin.varnames', 'hosts')}}"
- name: Find several related variables that end specific way
debug: msg="{{ lookup('varnames', '.+_zone$', '.+_location$') }}"
ansible.builtin.debug: msg="{{ lookup('ansible.builtin.varnames', '.+_zone$', '.+_location$') }}"
"""

@ -22,29 +22,29 @@ DOCUMENTATION = """
EXAMPLES = """
- name: Show value of 'variablename'
debug: msg="{{ lookup('vars', 'variabl' + myvar) }}"
ansible.builtin.debug: msg="{{ lookup('ansible.builtin.vars', 'variabl' + myvar) }}"
vars:
variablename: hello
myvar: ename
- name: Show default empty since i dont have 'variablnotename'
debug: msg="{{ lookup('vars', 'variabl' + myvar, default='')}}"
ansible.builtin.debug: msg="{{ lookup('ansible.builtin.vars', 'variabl' + myvar, default='')}}"
vars:
variablename: hello
myvar: notename
- name: Produce an error since i dont have 'variablnotename'
debug: msg="{{ lookup('vars', 'variabl' + myvar)}}"
ansible.builtin.debug: msg="{{ lookup('ansible.builtin.vars', 'variabl' + myvar)}}"
ignore_errors: True
vars:
variablename: hello
myvar: notename
- name: find several related variables
debug: msg="{{ lookup('vars', 'ansible_play_hosts', 'ansible_play_batch', 'ansible_play_hosts_all') }}"
ansible.builtin.debug: msg="{{ lookup('ansible.builtin.vars', 'ansible_play_hosts', 'ansible_play_batch', 'ansible_play_hosts_all') }}"
- name: Access nested variables
debug: msg="{{ lookup('vars', 'variabl' + myvar).sub_var }}"
ansible.builtin.debug: msg="{{ lookup('ansible.builtin.vars', 'variabl' + myvar).sub_var }}"
ignore_errors: True
vars:
variablename:
@ -52,7 +52,7 @@ EXAMPLES = """
myvar: ename
- name: alternate way to find some 'prefixed vars' in loop
debug: msg="{{ lookup('vars', 'ansible_play_' + item) }}"
ansible.builtin.debug: msg="{{ lookup('ansible.builtin.vars', 'ansible_play_' + item) }}"
loop:
- hosts
- batch

Loading…
Cancel
Save