How to Use 'ansible-pull' (with examples)
Ansible-pull is an essential command-line tool within the Ansible automation suite. Unlike the standard “ansible” command that pushes configuration from a control node to managed nodes, “ansible-pull” operates in a pull-based model. This means that the execution is initiated from the nodes themselves, pulling configurations from a version control system (VCS) repository to apply locally. This is particularly useful in environments where a central control node isn’t feasible or for systems designed to be updated individually.
Use case 1: Pull a playbook from a VCS and execute a default local.yml playbook
Code:
ansible-pull -U repository_url
Motivation:
This command is perfect for scenarios where you have a standard configuration stored under the default “local.yml” playbook in your VCS repository. It’s ideal for automated deployment setups where minimal configuration is required, and you want a straightforward, hands-off approach to maintaining system states.
Explanation:
-U repository_url: This argument specifies the URL of the VCS repository where your Ansible playbooks are stored. Using “-U” enables ansible-pull to clone or pull the latest changes from this remote location. This setup is perfect for ensuring that your system configurations are always in sync with the latest version of your playbooks.
Example Output:
Upon executing this command, you may see output indicating that the “local.yml” file is being pulled from the specified repository and then executed. The console will display the usual Ansible execution summary, showing which tasks were run and their respective statuses.
[INFO] ansible-pull args: ['/usr/bin/ansible-pull', '-U', 'repository_url']
Cloning into '/etc/ansible'...
[INFO] Executing playbook local.yml
PLAY [local] ***************************************************************
TASK [Gathering Facts] *****************************************************
ok: [localhost]
TASK [Print message] *******************************************************
ok: [localhost] => {
"msg": "Ansible pull default playbook executed!"
}
PLAY RECAP *****************************************************************
localhost : ok=2 changed=0 unreachable=0 failed=0
Use case 2: Pull a playbook from a VCS and execute a specific playbook
Code:
ansible-pull -U repository_url playbook
Motivation:
When maintaining multiple playbooks in a repository, you might need to execute a specific one based on your current requirements. Whether deploying a web server setup or initiating a database configuration, having the flexibility to specify the playbook directly allows better control and customization.
Explanation:
-U repository_url: As previously mentioned, this points to the VCS repository from which the Ansible playbooks will be retrieved.playbook: Following the repository URL, you specify the playbook’s name you wish to execute. This allows you to bypass the default “local.yml” and directly run the configuration scripts relevant to your task.
Example Output:
The output will show the successful pull of the specific playbook from the repository and its execution. Each task within the playbook will be displayed with its result status, ensuring transparency of operations.
[INFO] ansible-pull args: ['/usr/bin/ansible-pull', '-U', 'repository_url', 'playbook']
Cloning into '/etc/ansible'...
[INFO] Executing playbook playbook.yml
PLAY [local] ***************************************************************
TASK [Gathering Facts] *****************************************************
ok: [localhost]
TASK [Install packages] ****************************************************
changed: [localhost] => (installing packages)
PLAY RECAP *****************************************************************
localhost : ok=3 changed=1 unreachable=0 failed=0
Use case 3: Pull a playbook from a VCS at a specific branch and execute a specific playbook
Code:
ansible-pull -U repository_url -C branch playbook
Motivation:
In situations where your repository hosts multiple branches (for testing, development, or production stages), it is crucial to specify the branch you want to pull the playbook from. This use case is beneficial for environment-specific configurations where settings might distinctly differ across branches.
Explanation:
-U repository_url: Locates the VCS repository.-C branch: This argument specifies the branch from which to pull the playbook. Using “-C,” you can target configurations relevant to different stages without affecting the master branch.playbook: Specifies the playbook to be executed from the pulled branch.
Example Output:
Expect the output to include the branch being checked out and the playbook execution details. You’ll see the tasks being executed as defined in that specific branch and playbook.
[INFO] ansible-pull args: ['/usr/bin/ansible-pull', '-U', 'repository_url', '-C', 'branch', 'playbook']
Cloning into '/etc/ansible'...
Switched to branch 'branch'
[INFO] Executing playbook playbook.yml
PLAY [local] ***************************************************************
TASK [Gathering Facts] *****************************************************
ok: [localhost]
TASK [Configure environment] ***********************************************
changed: [localhost] => (environment specific tasks executed)
PLAY RECAP *****************************************************************
localhost : ok=3 changed=1 unreachable=0 failed=0
Use case 4: Pull a playbook from a VCS, specify hosts file and execute a specific playbook
Code:
ansible-pull -U repository_url -i hosts_file playbook
Motivation:
You might have an environment where multiple hosts need configuration, or you could be reusing notes across different setups. Specifying a hosts file allows more complex and tailored configurations by defining which set of machines the playbooks should apply.
Explanation:
-U repository_url: Retrieves the playbooks from the defined VCS repository.-i hosts_file: Provides the path to a custom inventory file which lists the hosts and variables. This argument customizes the inventory against which the playbook will run.playbook: States the specific playbook to invoke after fetching it along with the inventory file from the repository.
Example Output:
The execution shows the hosts being targeted as listed in your custom inventory file, alongside the completion results of tasks specified in the chosen playbook.
[INFO] ansible-pull args: ['/usr/bin/ansible-pull', '-U', 'repository_url', '-i', 'hosts_file', 'playbook']
Cloning into '/etc/ansible'...
[INFO] Executing playbook playbook.yml using inventory from hosts_file
PLAY [servers] ***************************************************************
TASK [Gathering Facts] *****************************************************
ok: [server1]
ok: [server2]
TASK [Setup environment] ***************************************************
changed: [server1] => (installation and configuration task completed)
changed: [server2] => (installation and configuration task completed)
PLAY RECAP *****************************************************************
server1 : ok=3 changed=2 unreachable=0 failed=0
server2 : ok=3 changed=2 unreachable=0 failed=0
Conclusion:
The “ansible-pull” command serves as a powerful tool in the Ansible ecosystem by providing flexibility in deploying configurations to individual nodes. Through these straightforward examples, an understanding of its use in various scenarios illustrates how it can fit into different system architecture or deployment models, driving efficiency and customization in system management tasks.
