Guide 08 / 3
Ansible commands
Find the operational commands and their options for working carefully on servers.
Test access, target hosts, simulate, apply and diagnose an Ansible playbook.
01 · Installing and checking
From a Linux control machine: isolate the project's dependencies and check the active configuration.
Create a Python environment
Avoids changing the system's Python packages and isolates Ansible for the project.
Example
python3 -m venv .venv
source .venv/bin/activate
python -m pip install ansible
The source command is meant for bash/zsh; on Windows use a compatible environment.
ansible --version
Shows the tool's version, the Python in use and the path of ansible.cfg.
Example
ansible --version
ansible-config dump --only-changed
Displays the settings that differ from the default values.
Example
ansible-config dump --only-changed
ansible-config view
Displays the content of the loaded configuration file.
Example
ansible-config view
ansible-doc -l
Lists the available documented modules and plugins.
Example
ansible-doc -l | grep ansible.builtin.apt
ansible-doc [module]
Opens a module's detailed documentation and parameters.
Example
ansible-doc ansible.builtin.template
02 · Inventory, targets and connectivity
Start by viewing the targeted hosts and testing their reachability before an intervention.
ansible-inventory --graph
Shows the structure of the inventory's groups.
Example
ansible-inventory -i inventory.ini --graph
ansible-inventory --list
Produces the complete view of the inventory, with variables, as Ansible interprets it.
Example
ansible-inventory -i inventory.ini --list
The output may include sensitive information present in the inventory.
ansible [group] --list-hosts
Displays the hosts matching the targeting without running a remote module.
Example
ansible web -i inventory.ini --list-hosts
ansible [group] -m ping
Tests access and the execution of a Python module on the hosts.
Example
ansible web -i inventory.ini -m ansible.builtin.ping
This ping is not an ICMP packet: it requires authentication and Python on the target side.
ansible [group] -m setup
Retrieves the system facts of one or more servers.
Example
ansible web -i inventory.ini -m ansible.builtin.setup
Targeting a single host with --limit
Restricts a group or an execution to a subset.
Example
ansible-playbook -i inventory.ini site.yml --limit web1
Selecting the account (-u)
Specifies the SSH login account.
Example
ansible web -i inventory.ini -m ping -u deployer
Choosing an SSH key (--private-key)
Designates a particular SSH private key.
Example
ansible web -i inventory.ini -m ping --private-key ~/.ssh/id_ed25519
Asking for the password (-k)
Prompts for a password for the connection.
Example
ansible web -i inventory.ini -m ping -k
Prefer SSH keys on managed environments.
03 · One-off commands (ad hoc)
For a simple check or action, an ansible command can run a module without creating a playbook.
Showing the remote identity
Runs the command module to find out which account runs the command.
Example
ansible web -i inventory.ini -a "whoami"
-a without an explicit -m uses ansible.builtin.command by default.
Testing a package's presence
Queries the packages present with package_facts, without changing them.
Example
ansible web -i inventory.ini -m ansible.builtin.package_facts
Installing a package with apt
Requests the installation of a package on a Debian/Ubuntu target.
Example
ansible web -i inventory.ini -b -m ansible.builtin.apt -a "name=curl state=present"
A modifying action: start with --limit web1 and a lab environment.
Creating a folder
Ensures a directory exists and has the given permissions.
Example
ansible web -i inventory.ini -b -m ansible.builtin.file -a "path=/opt/demo state=directory mode=0755"
Checking a service's state
Collects service information without imposing a change.
Example
ansible web -i inventory.ini -b -m ansible.builtin.service_facts
ansible [group] -m command
Runs a remote program without interpretation by a shell.
Example
ansible web -i inventory.ini -m ansible.builtin.command -a "uptime"
ansible [group] -m shell
Runs a string through a remote shell, useful for pipes or redirections.
Example
ansible web -i inventory.ini -m ansible.builtin.shell -a "df -h | tail -n 3"
The shell increases the risks of injection and of non-idempotence; limit its use.
04 · Reading, checking and running playbooks
Recommended order: identify the hosts, validate the syntax, simulate, examine the differences, then apply.
ansible-playbook -i ...
Runs the playbook on the inventory's targets.
Example
ansible-playbook -i inventory.ini site.yml
--syntax-check
Analyses the playbook's structure and syntax without running the tasks.
Example
ansible-playbook -i inventory.ini site.yml --syntax-check
Guarantees neither connectivity, nor permissions, nor business success.
--check
Tries to simulate a playbook's changes without applying them.
Example
ansible-playbook -i inventory.ini site.yml --check
--diff
Displays file and template differences when the modules support it.
Example
ansible-playbook -i inventory.ini site.yml --check --diff
--list-hosts
Lists the playbook's targets before it runs.
Example
ansible-playbook -i inventory.ini site.yml --list-hosts
--list-tasks
Displays the playbook tasks known before execution.
Example
ansible-playbook -i inventory.ini site.yml --list-tasks
Dynamic includes are not always visible at this stage.
--start-at-task
Resumes from a named task.
Example
ansible-playbook site.yml --start-at-task "Installer nginx"
Does not replace validating the prerequisites of the previous steps.
--step
Asks for interactive confirmation before each task.
Example
ansible-playbook site.yml --step
-b / -K
Enables become and, with -K, asks for the elevation password if needed.
Example
ansible-playbook -i inventory.ini site.yml -b -K
-e (extra-vars)
Supplies a variable that has high priority over other definitions.
Example
ansible-playbook site.yml -e "env=staging"
Do not write secrets in clear text in the command history.
-v / -vvv
Displays an increasing level of detail to understand failures.
Example
ansible-playbook -i inventory.ini site.yml -vvv
Detailed traces may disclose parameters; handle with care.
05 · Roles, collections and secrets
Working as a team means documenting dependencies and protecting confidential variables.
ansible-galaxy collection list
Lists the installed collections and their version.
Example
ansible-galaxy collection list
ansible-galaxy collection install
Installs an additional collection.
Example
ansible-galaxy collection install community.docker
Installing collections via requirements.yml
Installs the dependencies listed in the repository.
Example
ansible-galaxy collection install -r requirements.yml
ansible-galaxy role init
Creates a role's standard folder structure.
Example
ansible-galaxy role init roles/nginx
ansible-vault create
Creates an encrypted YAML file and opens it in an editor.
Example
ansible-vault create group_vars/prod/vault.yml
ansible-vault encrypt
Encrypts an existing file.
Example
ansible-vault encrypt group_vars/prod/vault.yml
ansible-vault edit
Opens an encrypted file for editing without keeping a plain copy.
Example
ansible-vault edit group_vars/prod/vault.yml
ansible-vault rekey
Renews the encryption password of a Vault file.
Example
ansible-vault rekey group_vars/prod/vault.yml
--ask-vault-pass
Asks for the Vault password during a run.
Example
ansible-playbook site.yml --ask-vault-pass
06 · Diagnosing and operating
When something fails, confirm the target, the access, the module used and the exact part of the task in error.
PLAY RECAP
The final summary per host: ok, changed, unreachable, failed, skipped, rescued, ignored.
Example
failed=0 et unreachable=0 : pas d’erreur détectée pendant l’exécution.
unreachable
Ansible could not establish a usable connection with the host.
Example
Vérifier IP, SSH, clé, utilisateur et pare-feu.
failed
A task was run but failed.
Example
Vérifier le message détaillé, les permissions et les prérequis.
ansible-config dump
Displays the effective configuration values.
Example
ansible-config dump | grep DEFAULT_TIMEOUT
ansible-playbook --help
Displays the general help on command-line options.
Example
ansible-playbook --help
Checking drift without deploying
Run the playbook again with --check --diff after an intervention to detect drift.
Example
ansible-playbook -i inventory.ini site.yml --check --diff
Modules that do not support check mode can limit the scope of the check.