Ansible Tutorial - Directory layout and Example

Ansible is agentless configuration management: it does not require an agent like Puppet, Chef, or Salt. It works over SSH, so a machine that allows remote SSH access can be managed. Ansible can work from a single YAML file, but many tasks make editing and reuse difficult. In this article, I explain directory layout so beginners can understand how to create and organize it correctly.

Directory Layout

The example below shows the top-level directories and files.

├── production                # ไฟล์ inventory สำหรับ production servers
├── staging                   # ไฟล์ inventory สำหรับ staging
├── dev                       # ไฟล์ inventory สำหรับ development
├── group_vars/
│   ├── group1                # กำหนด variable ในแต่ละ group โดยอ้างอิงจาก inventory file
│   ├── group2                # 
│   └── all                   # ถ้าหากต้องการกำหนด variable เป็น default value หรือใช้งานได้ทั้งหมด
├── host_vars/
│   └── hostname1             # กำหนด variable แบบเฉพาะเจาะจงเครื่อง โดยชื่อไฟล์คือชื่อเครื่องใน inventory file
├── library/                  # custom modules (optional)
├── filter_plugins/           # custom filter plugins (optional)
├── site.yml                  # ไฟล์ playbook หลัก
├── nginxservers.yml          # ไฟล์ playbook ของ nginx server
├── mysqlservers.yml          # playbook ของ MySQL server
│
└── roles/
    ├── common/               # role ชื่อ common
    │   ├── tasks/            # 
    │   │   └── main.yml      #  tasks ต่างๆของ role
    │   ├── handlers/         #
    │   │   └── main.yml      # handlers file
    │   ├── templates/        # Folder สำหรับเก็บไฟล์ template
    │   │   └── ntp.conf.j2   #  - ไฟล์ templates ลงท้ายด้วย .j2
    │   ├── files/            #  ไฟล์ที่ต้องการให้ ansible ทำการ copy ไปยัง folder ที่ต้องการ
    │   │   ├── bar.txt       #  
    │   │   └── foo.sh        #   
    │   ├── vars/             #
    │   │   └── main.yml      #  variable ในระดับ role
    │   ├── defaults/         #
    │   │   └── main.yml      #  lower priority variable สำหรับ role
    │   └── meta/             #
    │       └── main.yml      #  role dependencies
    │
    ├── webtier/              # role ชื่อ webtier โดยมีโครงสร้างของ folder เหมือนกับ common role
    └── monitoring/           # role ชื่อ monitoring โดยมีโครงสร้างของ folder เหมือนกับ common role

The folder structure above can be explained in parts as follows.

Inventory file

This defines hostnames and hostname groups so Ansible knows which servers to run on. The file and folder structure above defines three inventory files: production, staging, and dev. You can select the required environment when running Ansible. Example run specifying an inventory file:

# ansible-playbook -i production site.yml

Example inventory file:

[thailand-nginxservers]
www-th-1.ezylinux.com
www-th-2.ezylinux.com

[singapore-nginxservers:vars]  # Apply variables using :vars
www-sg-1.ezylinux.com
ntp_server=ntp.sg.ezylinux.com

[thailand-mysqlservers]
db-th-1.ezylinux.com
db-th-2.ezylinux.com

[singapore-mysqlservers]
db-sg-1.ezylinux.com

# nginxservers in both Thailand and Singapore 
[nginxservers:children]   # Make groups of groups using the :children suffix.
thailand-nginxservers
singapore-nginxservers

# mysqlservers in both Thailand and Singapore
[dbservers:children]
thailand-mysqlservers
singapore-mysqlservers

# everything in the Thaland
[thailand:children]
thailand-nginxservers
thailand-mysqlservers

# everything in the Singapore
[singapore:children]
singapore-nginxservers
singapore-mysqlservers

Group Variables

This defines variables for groups declared in the inventory file, with these requirements:

1. The filename must match a group name in the inventory file.
2. It must be in the group_vars folder.

For example, make the Thailand server group use an NTP server in Thailand:

---
# file: group_vars/thailand
ntp: th.pool.ntp.org

Host Variables

This defines variables for individual hosts declared in the inventory file. For example, configure db-th-1.ezylinux.com to run MySQL on port 3307:

---
# file: host_vars/db-th-1.ezylinux.com
mysql_port: 3307

Roles

In Ansible, tasks can be split into roles for easier use, editing, and reuse in new work. For example, a folder named common under roles defines a role called common. Inside common are the folders shown in the example. ** Roles can have dependencies, allowing their execution order to be defined.

└── roles/
    ├── common/               # role ชื่อ common
    │   ├── tasks/            # ไฟล์ YAML ที่กำหนดขั้นตอนการทำงาน
    │   ├── handlers/         # ไฟล์ YAML ที่จะถูก notify จาก task เพื่อให้ทำงานที่กำหนด
    │   ├── templates/        # Folder สำหรับเก็บไฟล์ Jinja2 template
    │   ├── files/            # ไฟล์ที่ต้องการให้ ansible ทำการ copy ไปยัง folder ที่ต้องการ
    │   ├── vars/             # variable ที่เกี่ยวข้องกับ role นี้
    │   ├── defaults/         # lower priority variables
    │   └── meta/             # role dependencies