Ansible Documentation: Complete Guide to Finding and Using Official Docs

By Luca Berton · Published 2024-01-01 · Category: installation

Navigate Ansible documentation effectively. Official docs, module reference, collection docs, ansible-doc CLI, playbook keywords, configuration reference.

Where to Find Ansible Documentation

Ansible documentation is spread across several locations. Here's the definitive map.

Official Documentation Sites

Resource	URL	What's There
Ansible Core docs		Playbook language, modules, plugins, configuration
AAP docs		Automation Controller, Hub, EDA, Mesh
Collection index		Every collection and its modules/plugins
Galaxy		Community collections and roles
Automation Hub		Red Hat certified collections
GitHub		Source code, issues, development

Most-Used Documentation Pages

Bookmark these — you'll use them constantly:

Module Index — searchable list of every module
Playbook Keywords — every keyword you can use in plays, roles, blocks, and tasks
Special Variables — inventory_hostname, ansible_facts, hostvars, etc.
Jinja2 Filters — data transformation in templates
ansible.cfg Settings — every configuration option
Connection Plugins — SSH, WinRM, network_cli, httpapi

ansible-doc: Documentation From the Command Line

The ansible-doc command is the fastest way to check module documentation without opening a browser.

Look Up a Module

# Full documentation for a module
ansible-doc ansible.builtin.copy

# Short usage snippet
ansible-doc -s ansible.builtin.copy

# Output:
# - name: Copy files to remote locations
#   copy:
#     backup:     # Create backup file with timestamp
#     content:    # Write content directly (mutually exclusive with src)
#     dest:       # (required) Remote absolute path
#     ...

List All Modules

# List every available module
ansible-doc -l

# Filter by keyword
ansible-doc -l | grep -i "firewall"
# community.general.ufw
# ansible.posix.firewalld
# ...

# List modules in a specific collection
ansible-doc -l -t module ansible.builtin
ansible-doc -l -t module community.general

Other Plugin Types

# Lookup plugins
ansible-doc -t lookup file
ansible-doc -t lookup env

# Filter plugins
ansible-doc -t filter ansible.builtin.regex_replace

# Connection plugins
ansible-doc -t connection ansible.netcommon.network_cli

# Callback plugins
ansible-doc -t callback ansible.builtin.debug

# Inventory plugins
ansible-doc -t inventory ansible.builtin.yaml

# All plugin types
ansible-doc -t module   # Modules (default)
ansible-doc -t lookup   # Lookup plugins
ansible-doc -t filter   # Filter plugins
ansible-doc -t callback # Callback plugins
ansible-doc -t connection # Connection plugins
ansible-doc -t inventory  # Inventory plugins
ansible-doc -t become     # Become plugins
ansible-doc -t strategy   # Strategy plugins
ansible-doc -t vars       # Vars plugins
ansible-doc -t cache      # Cache plugins

JSON Output for Scripts

# Machine-readable documentation
ansible-doc ansible.builtin.copy --json

# Useful for building custom tooling or documentation sites

ansible-navigator doc (With EEs)

If you use Execution Environments, ansible-navigator doc shows documentation for modules inside the EE:

# Interactive TUI documentation browser
ansible-navigator doc ansible.builtin.copy

# Stdout mode
ansible-navigator doc ansible.builtin.copy -m stdout

# List all modules in the EE
ansible-navigator doc -l -m stdout

# Browse all collections in the EE
ansible-navigator collections

This is important because your local Ansible installation may have different collections than your EE. Always check documentation against the EE you'll run in production.

Reading Module Documentation

Every module doc page follows the same structure:

1. Synopsis

What the module does in one paragraph.

2. Requirements

Python libraries or system packages needed on the target host (not the control node).

3. Parameters

The most important section. Each parameter shows:

Name — the parameter name
Type — string, boolean, list, dict, int, path, etc.
Required — yes/no
Default — default value if not specified
Choices — valid values for restricted parameters
Description — what it does

4. Notes

Edge cases, version requirements, and gotchas.

5. Examples

Copy-paste-ready YAML. Start here when learning a new module.

6. Return Values

What the module returns in register — essential for when conditions and debug output.

Example: Reading the copy Module Doc

$ ansible-doc ansible.builtin.copy

Key parameters to understand:

# Required
dest:        # Remote absolute path (required)

# Content source (pick one)
src:         # Local file path to copy
content:     # Write this string directly to dest

# Options
mode:        # File permissions (e.g., '0644')
owner:       # File owner
group:       # File group
backup:      # Create backup before overwriting (yes/no)
validate:    # Command to validate file before placing (e.g., 'visudo -cf %s')
remote_src:  # If true, src is on remote host, not control node
force:       # Replace even if dest exists and is identical (default: yes)

Collection Documentation

Find a Collection's Docs

# What collections are installed?
ansible-galaxy collection list

# Documentation for a specific collection
ansible-doc -l -t module amazon.aws
ansible-doc amazon.aws.ec2_instance

Install a Collection and Read Its Docs

# Install
ansible-galaxy collection install community.general

# Read
ansible-doc community.general.ufw
ansible-doc community.general.nmcli
ansible-doc community.general.timezone

Collection Documentation Sites

Most major collections maintain their own documentation sites:

Collection	Documentation
ansible.builtin
amazon.aws
azure.azcollection
google.cloud
community.general
ansible.posix
ansible.windows
cisco.ios

Playbook Language Reference

Playbook Keywords

The playbook keywords reference lists every keyword by context:

Play-level keywords:

- name: Example play
  hosts: webservers          # Target hosts (required)
  become: true               # Privilege escalation
  gather_facts: true         # Collect system facts
  serial: 3                  # Rolling update batch size
  max_fail_percentage: 10    # Fail play if >10% hosts fail
  any_errors_fatal: true     # Stop on first failure
  strategy: free             # Execution strategy
  environment:               # Environment variables
    http_proxy: "http://proxy:3128"
  vars:                      # Play variables
    app_version: "2.0"
  vars_files:                # Load variables from files
    - vars/production.yml
  roles:                     # Include roles
    - common
    - webserver
  pre_tasks: []              # Tasks before roles
  tasks: []                  # Main tasks
  post_tasks: []             # Tasks after roles
  handlers: []               # Triggered tasks

Task-level keywords:

- name: Example task
  ansible.builtin.copy:
    src: file.conf
    dest: /etc/app/file.conf
  become: true                    # Escalate for this task
  become_user: postgres           # Escalate to specific user
  when: ansible_os_family == "Debian"  # Conditional
  loop: "{{ packages }}"          # Iterate
  register: result                # Capture output
  changed_when: false             # Override change detection
  failed_when: result.rc > 1     # Override failure detection
  ignore_errors: true             # Continue on failure
  no_log: true                    # Hide sensitive output
  notify: restart service         # Trigger handler
  tags: [deploy, config]          # Tags for selective runs
  delegate_to: localhost          # Run on different host
  run_once: true                  # Execute only once
  retries: 3                      # Retry on failure
  delay: 10                       # Seconds between retries
  until: result is success        # Retry condition
  timeout: 300                    # Task timeout in seconds
  async: 3600                     # Run asynchronously
  poll: 10                        # Async polling interval

Offline Documentation

Build Local Docs

# Clone Ansible docs
git clone https://github.com/ansible/ansible-documentation.git
cd ansible-documentation/docs/docsite

# Build HTML docs
pip install -r requirements.txt
make webdocs

# Open in browser
open _build/html/index.html

ansible-doc Works Offline

ansible-doc reads documentation from installed module Python files — no internet required:

# Works completely offline
ansible-doc ansible.builtin.apt
ansible-doc -l

Getting Help

Channel	URL	Best For
Ansible Forum		Questions, discussions, announcements
GitHub Issues		Bug reports
IRC/Matrix	`#ansible` on Libera.Chat / Matrix	Real-time chat
Stack Overflow	`[ansible]` tag	Specific technical questions
Reddit	r/ansible	Community discussions
Ansible Bullhorn	Newsletter	Release notes, community news

FAQ

Where is the official Ansible documentation?

The primary documentation site is . For Ansible Automation Platform (AAP) enterprise features, use .

How do I check module documentation from the terminal?

Use ansible-doc . For example: ansible-doc ansible.builtin.copy. Use -s for a short snippet, -l to list all modules, and -t to specify plugin type (lookup, filter, callback, etc.).

How do I find which collection a module belongs to?

Every module has a fully qualified collection name (FQCN) like ansible.builtin.copy or community.general.ufw. The format is namespace.collection.module. Run ansible-doc -l | grep module_name to find it.

Can I use Ansible documentation offline?

Yes. ansible-doc works completely offline using the installed module files. For full HTML documentation, clone the ansible-documentation repository and build it locally with Sphinx.

How do I keep up with Ansible changes?

Subscribe to the Ansible Bullhorn newsletter for release announcements. Check the changelog for version-specific changes. Follow ansible-core releases on GitHub.

Conclusion

Ansible documentation lives at docs.ansible.com for the core engine and collection modules, and at docs.redhat.com for AAP enterprise features. The ansible-doc CLI gives you instant offline access to any module's parameters, examples, and return values. Start with the Examples section of any module doc — it's the fastest path from "what does this do?" to working automation.

Category: installation

Browse all Ansible tutorials · AnsiblePilot Home

AnsiblePilot — Master Ansible Automation

Popular Topics

About Luca Berton