Ansible Command Line
Introduction
Ansible is a powerful IT automation tool that simplifies complex tasks like configuration management, application deployment, and orchestration. One of the most accessible ways to start using Ansible is through its command-line interface. In this guide, we'll explore the essential Ansible command-line tools, their syntax, and practical applications to help you automate your infrastructure with confidence.
The Ansible command line provides a direct way to execute automation tasks without needing to write complex playbooks first, making it perfect for beginners or quick one-off tasks.
Core Ansible Commands
Ansible offers several command-line tools, but the most commonly used are:
ansible
- For running ad-hoc commandsansible-playbook
- For executing playbooksansible-inventory
- For working with inventory filesansible-config
- For managing configurationansible-doc
- For accessing documentation
Let's explore each of these commands in detail.
The ansible
Command
The ansible
command allows you to execute ad-hoc tasks on managed nodes without writing a playbook. This is useful for quick operations like checking system status, installing packages, or restarting services.
Basic Syntax
ansible <host-pattern> -m <module-name> -a "<module-arguments>"
Key Components:
- host-pattern: The hosts or groups to target (from your inventory)
- -m: Specifies the module to use
- -a: Provides arguments for the module
Example 1: Ping all hosts to verify connectivity
ansible all -m ping
Output:
192.168.1.101 | SUCCESS => {
"ansible_facts": {
"discovered_interpreter_python": "/usr/bin/python3"
},
"changed": false,
"ping": "pong"
}
192.168.1.102 | SUCCESS => {
"ansible_facts": {
"discovered_interpreter_python": "/usr/bin/python3"
},
"changed": false,
"ping": "pong"
}
Example 2: Checking system information
ansible webservers -m setup
This command returns detailed system information about all hosts in the "webservers" group.
Example 3: Running shell commands
ansible all -m command -a "uptime"
Output:
192.168.1.101 | SUCCESS | rc=0 >>
14:32:56 up 12 days, 3:45, 1 user, load average: 0.08, 0.03, 0.01
192.168.1.102 | SUCCESS | rc=0 >>
14:32:57 up 5 days, 7:12, 0 users, load average: 0.12, 0.05, 0.02
Example 4: Installing a package
ansible webservers -m apt -a "name=nginx state=present" --become
This command installs Nginx on all servers in the "webservers" group. The --become
flag enables privilege escalation (sudo).
The ansible-playbook
Command
While ad-hoc commands are useful, playbooks are at the heart of Ansible's power. The ansible-playbook
command executes playbook files that contain multiple tasks organized into plays.
Basic Syntax
ansible-playbook playbook.yml
Example: Running a simple playbook
Imagine we have a playbook named web_setup.yml
:
---
- name: Web Server Setup
hosts: webservers
become: true
tasks:
- name: Install Nginx
apt:
name: nginx
state: present
- name: Start Nginx Service
service:
name: nginx
state: started
enabled: yes
To run this playbook:
ansible-playbook web_setup.yml
Output:
PLAY [Web Server Setup] ************************
TASK [Gathering Facts] ************************
ok: [192.168.1.101]
ok: [192.168.1.102]
TASK [Install Nginx] **************************
changed: [192.168.1.101]
ok: [192.168.1.102]
TASK [Start Nginx Service] ********************
changed: [192.168.1.101]
ok: [192.168.1.102]
PLAY RECAP ***********************************
192.168.1.101 : ok=3 changed=2 unreachable=0 failed=0
192.168.1.102 : ok=3 changed=0 unreachable=0 failed=0
Common ansible-playbook
Options
--limit SUBSET
: Limit execution to specific hosts--check
: Perform a dry run without making changes--diff
: Show differences when files change-v
,-vv
,-vvv
: Increase verbosity for debugging--tags TAG_NAME
: Run only tasks with specified tags--skip-tags TAG_NAME
: Skip tasks with specified tags
Example with options
ansible-playbook web_setup.yml --limit 192.168.1.101 --check --diff -v
This runs the playbook in check mode (no changes), showing differences and increased verbosity, limited to a single host.
The ansible-inventory
Command
The ansible-inventory
command helps examine and visualize your inventory, which is crucial for targeting the right hosts.
Basic Syntax
ansible-inventory [options]
Example 1: List all hosts
ansible-inventory --list
Output (simplified):
{
"_meta": {
"hostvars": {
"192.168.1.101": {
"ansible_host": "192.168.1.101",
"group": "webservers"
},
"192.168.1.102": {
"ansible_host": "192.168.1.102",
"group": "webservers"
},
"192.168.1.103": {
"ansible_host": "192.168.1.103",
"group": "databases"
}
}
},
"all": {
"children": ["ungrouped", "webservers", "databases"]
},
"databases": {
"hosts": ["192.168.1.103"]
},
"webservers": {
"hosts": ["192.168.1.101", "192.168.1.102"]
}
}
Example 2: Graph the inventory
ansible-inventory --graph
Output:
@all:
|--@ungrouped:
|--@webservers:
| |--192.168.1.101
| |--192.168.1.102
|--@databases:
| |--192.168.1.103
Example 3: Show host variables
ansible-inventory --host 192.168.1.101
Output:
{
"ansible_host": "192.168.1.101",
"group": "webservers"
}
The ansible-config
Command
The ansible-config
command helps view and manage your Ansible configuration.
Basic Syntax
ansible-config [view|dump|list]
Example 1: View current configuration
ansible-config view
This shows the content of your ansible.cfg file.
Example 2: Dump all configuration (including defaults)
ansible-config dump
Output (partial):
ACTION_WARNINGS(default) = True
AGNOSTIC_BECOME_PROMPT(default) = True
ANSIBLE_CONNECTION_PATH(default) = None
ANSIBLE_COW_PATH(default) = None
ANSIBLE_COW_SELECTION(default) = default
ANSIBLE_COW_WHITELIST(default) = ['bud-frogs', 'bunny', 'cheese', 'daemon'...]
...
Example 3: List all configuration options
ansible-config list
This provides a detailed list of all available configuration options with descriptions.
The ansible-doc
Command
The ansible-doc
command provides easy access to documentation for Ansible modules, which is invaluable when you need to understand how to use a particular module.
Basic Syntax
ansible-doc [options] [module name]
Example 1: Get documentation for the "apt" module
ansible-doc apt
Output (partial):
> APT (/usr/lib/python3/dist-packages/ansible/modules/packaging/os/apt.py)
Manages apt packages (such as for Debian/Ubuntu).
* This module is maintained by The Ansible Core Team
* note: This module has a corresponding action plugin.
OPTIONS (= is mandatory):
- allow_change_held_packages
Allows changing the version of a package which is on the apt hold list.
[Default: False]
type: bool
...
Example 2: List all available modules
ansible-doc -l
This lists all available modules with a brief description of each.
Example 3: Get a snippet example
ansible-doc -s copy
Output:
- name: Copy files to remote locations
copy:
src: # Local path to a file to copy to the remote server; can be absolute or relative.
content: # When used instead of 'src', sets the contents of a file directly to the specified value.
dest: # Remote absolute path where the file should be copied to.
backup: # Create a backup file including the timestamp information.
checksum: # SHA1 checksum of the file.
decrypt: # This option controls the autodecryption of source files using vault.
directory_mode: # When doing a recursive copy set the mode for the directories.
follow: # This flag indicates that filesystem links in the destination, if they exist, should be followed.
force: # Influence whether the remote file must always be replaced.
...
Common Patterns and Best Practices
1. Testing Commands with --check
Before making changes to production systems, use the --check
flag to perform a dry run:
ansible webservers -m apt -a "name=nginx state=present" --check
ansible-playbook deployment.yml --check
2. Targeting Specific Hosts
You can target hosts in various ways:
# Target a single host
ansible server1.example.com -m ping
# Target multiple hosts
ansible server1.example.com,server2.example.com -m ping
# Target a group
ansible webservers -m ping
# Target multiple groups
ansible webservers,databases -m ping
# Target all hosts except a group
ansible 'all:!databases' -m ping
# Target based on a pattern
ansible 'web*' -m ping
3. Using Variables at the Command Line
You can pass variables directly at the command line:
ansible-playbook release.yml --extra-vars "version=1.23.45 environment=staging"
4. Parallel Execution
Control how many hosts Ansible targets simultaneously:
ansible all -m apt -a "name=nginx state=present" -f 10
This sets the fork count to 10, meaning Ansible will communicate with 10 hosts in parallel.
Real-world Examples
Example 1: System Maintenance
# Update all packages on all servers
ansible all -m apt -a "update_cache=yes upgrade=yes" --become
# Reboot servers with a custom message
ansible webservers -m reboot -a "msg='Scheduled maintenance reboot' reboot_timeout=600" --become
Example 2: Deploying a Configuration Change
# Copy a configuration file to all web servers
ansible webservers -m copy -a "src=./nginx.conf dest=/etc/nginx/nginx.conf owner=root group=root mode=0644" --become
# Restart the service to apply changes
ansible webservers -m service -a "name=nginx state=restarted" --become
Example 3: Gathering Information
# Check disk space on all servers
ansible all -m shell -a "df -h"
# Find large files
ansible all -m shell -a "find /var/log -type f -size +100M -exec ls -lh {} \;"
Example 4: Running Playbooks with Different Environments
# Deploy to staging
ansible-playbook deploy.yml --extra-vars "env=staging"
# Deploy to production with limited concurrency
ansible-playbook deploy.yml --extra-vars "env=production" -f 5
Visualizing Ansible Command Flow
Summary
The Ansible command line provides powerful tools for infrastructure automation:
- The
ansible
command for running ad-hoc tasks ansible-playbook
for executing more complex, repeatable operationsansible-inventory
for examining your infrastructure inventoryansible-config
for managing configuration settingsansible-doc
for accessing built-in documentation
By mastering these commands, you'll be able to efficiently manage your infrastructure, automate routine tasks, and ensure consistency across your environment. The command-line interface offers a great entry point to Ansible's capabilities before diving into more complex playbook development.
Additional Resources
-
Practice Exercises:
- Write an ad-hoc command to check free disk space on all your servers
- Create a simple playbook to install and configure your favorite web server
- Set up a basic inventory file with at least two groups and use
ansible-inventory
to visualize it
-
Further Learning:
- Explore Ansible Galaxy for community-contributed roles
- Learn about Ansible Vault for managing sensitive data
- Study Ansible's idempotency concept to write safer automation
Remember that while ad-hoc commands are useful for quick tasks, playbooks offer reusability and documentation of your infrastructure as code. As you become more comfortable with the command line, consider evolving your automation into well-structured playbooks for maximum benefit.
If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)