ansible-pull

Pull a playbook from a VCS and execute a default local.yml playbook

$ ansible-pull [[-U|--url]] [repository_url]

$ ansible-pull [[-U|--url]] [repository_url] [playbook]

$ ansible-pull [[-U|--url]] [repository_url] [[-C|--checkout]] [branch] [playbook]

$ ansible-pull [[-U|--url]] [repository_url] [[-i|--inventory-file]] [hosts_file] [playbook]

ansible-pull [options] --url --directory [playbook.yml]

-U , --url
    Specifies the URL of the Git repository to pull configurations from. This is a mandatory option.

-d , --directory
    Specifies the local directory where the Git repository will be cloned or updated. This is a mandatory option.

-i , --inventory
    Specifies the inventory file or hosts. For ansible-pull, it's typically 'localhost,' or a dynamically generated one.

-s , --sleep
    Adds a random delay (in seconds, up to this value) before executing the playbook. Useful for cron jobs to prevent all clients hitting the Git repo simultaneously.

--checkout
    Specifies the Git branch, tag, or commit hash to checkout from the repository. Defaults to the repository's default branch.

--accept-host-keys
    Automatically accept new SSH host keys when cloning the repository. Use with caution in production environments.

--clean
    Resets any local modifications in the repository directory before pulling. Useful for ensuring a clean state.

--full-idempotence
    Ensures that all tasks run, not just changed ones, for full idempotence checking. This is primarily for debugging.

--purge
    Purges the entire local checkout directory before cloning the repository. Useful for starting fresh.

--verify-commit
    Verifies the GPG signature of the latest commit before running the playbook. Requires a valid GPG setup.

--vault-password-file
    Specifies the path to a file containing the Ansible Vault password.

--ask-vault-pass
    Prompts for the Ansible Vault password interactively. Less common for automated ansible-pull usage.

--private-key , --key-file
    Specifies the path to the SSH private key file to use for authenticating with the Git repository.

[playbook.yml]
    Optional argument to specify the playbook file within the cloned repository to execute. Defaults to main.yml or site.yml if not provided.

ansible-pull is an Ansible command-line utility designed for a decentralized, client-driven configuration management model.

Unlike the standard ansible-playbook, which operates in a 'push' mode from a central controller, ansible-pull reverses this dynamic. It enables managed nodes (clients) to fetch their configuration directly from a Git repository. This command clones or updates a specified Git repository on the local machine, then executes an ansible-playbook against 'localhost' using the content pulled from that repository.

This approach is particularly useful in scenarios where a central controller might not have direct SSH access to all managed nodes, such as dynamic cloud environments, large-scale deployments, or when managing IoT devices. It's commonly deployed as a cron job on the client machines, allowing them to periodically check for and apply updates. ansible-pull ensures that the configuration is idempotent, meaning it can be run multiple times without causing unintended side effects, only applying changes when necessary. It simplifies initial bootstrapping and ongoing maintenance by empowering nodes to manage their own configuration lifecycle from a version-controlled source.

ansible-pull requires git and python to be installed on the client machines.

Security is a key concern: ensure secure handling of Git repository access credentials (SSH keys or HTTPS tokens) on client systems, especially for private repositories. Managing Ansible Vault passwords on client machines also requires careful consideration.

Visibility and debugging can be more challenging compared to the push model, as logs and command output are local to the client. Centralized logging solutions or Ansible callback plugins are often needed to aggregate results.

A common use case involves scheduling ansible-pull as a cron job on target machines (e.g., hourly). The command pulls the latest playbook from a Git repository and executes it against 'localhost'. This ensures machines are always up-to-date with the desired configuration defined in the central repository, without requiring a constant connection from a central Ansible control node.

For private Git repositories, clients need appropriate authentication. This typically involves SSH keys (often an agent-forwarded key or a key stored directly on the client, protected with proper permissions) or HTTPS credentials. For HTTPS, personal access tokens are generally preferred over usernames and passwords.

Since ansible-pull runs locally on the client, managing output and errors is crucial. Output can be redirected to a log file. For centralized reporting, Ansible callback plugins can be configured to send execution results, failures, or changes to a monitoring system, syslog, or a log aggregation service.

ansible-pull was introduced relatively early in Ansible's development lifecycle to address the need for a decentralized, client-driven configuration management model. It provided a solution for scenarios where the traditional 'push' model wasn't suitable, such as managing cloud instances behind NATs or large-scale, dynamic environments where direct SSH access from a central controller is impractical or undesirable. Its core functionality has remained consistent, evolving alongside Ansible's general features and options.

ansible-playbook(1), ansible(1), git(1), cron(8)