Understanding Ansible Concepts

This document provides an overview of core Ansible concepts and how they are utilized in the infra-bootstrap-tools project. Understanding these will help you navigate and customize the automation scripts.

1. Playbooks

• What they are: Ansible Playbooks are YAML files that define a set of tasks to be executed on managed nodes (servers). They are the core of Ansible’s configuration management and orchestration capabilities.
• In this project:
  • The main playbook is ansible/playbooks/main.yml. This orchestrates the entire infrastructure setup, from provisioning with Terraform to deploying applications like Caddy and Portainer.
  • Other playbooks like ansible/playbooks/terraform.yml handle specific, smaller parts of the process, so that we can apply only part of the setup or iterate faster when testing a specific module

2. Tasks

• What they are: Tasks are the individual units of action in Ansible. Each task calls an Ansible module (e.g., apt for package management, copy for file transfer, shell for running commands) to perform a specific operation.
• In this project: Tasks are defined within roles (see below). For example, a task in the docker role might install the Docker engine, while a task in the docker_swarm_app_caddy role would deploy the Caddy service to the swarm.

3. Roles

• What they are: Roles are Ansible’s way of organizing automation content into self-contained, reusable units. They typically encapsulate tasks, handlers, variables, templates, and files needed to configure a specific piece of software or a system aspect.
• In this project: Roles are heavily used to structure the automation. You can find them in ansible/roles/. Examples include:
  • terraform_digitalocean: Manages the creation and destruction of infrastructure on DigitalOcean.
  • docker: Installs and configures Docker on hosts.
  • docker_swarm_manager: Initializes the Docker Swarm and manages manager nodes.
  • docker_swarm_app_caddy: Deploys Caddy as a Docker Swarm service.
  • Using roles makes the main playbook (ansible/playbooks/main.yml) cleaner and easier to understand.

4. Inventory

• What it is: An inventory file defines the hosts (servers) that Ansible will manage. It can be static (a simple text file) or dynamic (generated by scripts, e.g., from cloud provider APIs). Inventories can also group hosts.
• In this project:
  • The primary static inventory is located at ansible/playbooks/inventory/. This is where you would add files to define additional servers that you would like to configure using the provided roles.
  • The main playbook also leverages dynamically populating parts of the inventory. For instance, the role terraform_digitalocean outputs an inventory file for the droplets created via Terraform in DigitalOcean for Ansible to use.
  • Host groups like managers and nodes are used in ansible/playbooks/main.yml to target specific plays to the correct servers.

5. Variables (host_vars and group_vars)

• What they are: Variables are used to customize playbook execution and adapt it to different environments or hosts without changing the core logic of tasks and roles.
  • group_vars: Variables defined here apply to all hosts within a specific group in the inventory.
  • host_vars: Variables defined here apply to a specific host.
• In this project:
  • ansible/playbooks/group_vars/all.yml: Contains variables that apply to all hosts, such as the 1Password lookup for Rclone secrets.
  • ansible/playbooks/group_vars/managers.yaml: Contains variables specific to the managers group, like Caddy configuration details retrieved from 1Password.
  • ansible/playbooks/host_vars/localhost.yml: Contains variables for the localhost (where Ansible is run from), especially secrets for Terraform provisioning (DigitalOcean token, AWS credentials for S3 backend) fetched via 1Password.

Understanding these concepts will provide a solid foundation for working with the infra-bootstrap-tools and tailoring them to your specific needs.