Struktur

Struktur #

Mengetahui bahwa role punya direktori tasks/, handlers/, templates/, dan seterusnya adalah satu hal. Memahami apa yang seharusnya ada di masing-masing direktori, bagaimana mengorganisir task yang kompleks agar tetap mudah dikelola, dan kapan memecah file menjadi beberapa bagian — itu adalah keterampilan yang membedakan role yang baik dari role yang hanya “bekerja”.

Gambaran Lengkap Direktori Role #

roles/nginx/
  │
  ├── tasks/
  │   ├── main.yml          # Entry point — import task lain dari sini
  │   ├── install.yml       # Task instalasi package
  │   ├── configure.yml     # Task konfigurasi file
  │   └── ssl.yml           # Task setup SSL (opsional, dikondisikan)
  │
  ├── handlers/
  │   └── main.yml          # Handler untuk role ini
  │
  ├── templates/
  │   ├── nginx.conf.j2     # Konfigurasi utama nginx
  │   ├── vhost.conf.j2     # Template virtual host
  │   └── ssl.conf.j2       # Template konfigurasi SSL
  │
  ├── files/
  │   ├── dhparam.pem       # File statis DH parameters untuk SSL
  │   └── robots.txt        # File robots.txt default
  │
  ├── vars/
  │   └── main.yml          # Variabel internal role (path, konstanta)
  │
  ├── defaults/
  │   └── main.yml          # Nilai default yang bisa di-override
  │
  ├── meta/
  │   └── main.yml          # Metadata dan dependency role
  │
  └── README.md             # Dokumentasi cara menggunakan role

tasks/main.yml: Orkestrator, Bukan Daftar Panjang #

tasks/main.yml seharusnya berfungsi sebagai orkestrator — mendelegasikan ke file task yang lebih spesifik — bukan berisi ratusan task dalam satu file:

# roles/nginx/tasks/main.yml
---
# Instalasi package
- name: Install nginx
  import_tasks: install.yml
  tags: install

# Konfigurasi dasar
- name: Konfigurasi nginx
  import_tasks: configure.yml
  tags: configure

# Setup SSL — hanya jika diaktifkan
- name: Setup SSL/TLS
  import_tasks: ssl.yml
  when: nginx_ssl_enabled | default(false)
  tags: ssl

# Verifikasi akhir
- name: Verifikasi nginx berjalan
  import_tasks: verify.yml
  tags: verify

Struktur seperti ini membuat tasks/main.yml bisa dibaca sekilas tanpa memahami semua detailnya. Kamu bisa langsung melihat: role ini menginstal, mengkonfigurasi, menyiapkan SSL, lalu memverifikasi.

handlers/main.yml #

Handler dalam role sama seperti handler di playbook biasa, tapi berlaku dalam lingkup role:

# roles/nginx/handlers/main.yml
---
- name: Reload nginx
  systemd:
    name: nginx
    state: reloaded
  listen: nginx config changed

- name: Restart nginx
  systemd:
    name: nginx
    state: restarted
  listen: nginx restart required

- name: Test nginx config
  command: nginx -t
  changed_when: false
  listen: nginx config changed

templates/: Konvensi Penamaan yang Konsisten #

File template menggunakan ekstensi .j2 (Jinja2). Konvensi penamaan yang baik mencerminkan nama file yang akan dihasilkan di managed node:

Template di role              → File yang dihasilkan di managed node
nginx.conf.j2              → /etc/nginx/nginx.conf
vhost.conf.j2              → /etc/nginx/sites-available/myapp.conf
systemd.service.j2         → /etc/systemd/system/myapp.service
logrotate.conf.j2          → /etc/logrotate.d/myapp

Contoh template yang menggunakan variabel role:

{# roles/nginx/templates/nginx.conf.j2 #}
user www-data;
worker_processes {{ nginx_worker_processes | default(ansible_processor_vcpus) }};
pid {{ nginx_pid_file }};

events {
    worker_connections {{ nginx_worker_connections }};
}

http {
    server_tokens off;
    client_max_body_size {{ nginx_client_max_body_size }};
    keepalive_timeout {{ nginx_keepalive_timeout }};

    include /etc/nginx/mime.types;
    include {{ nginx_sites_enabled }}/*;
}

files/: File Statis Tanpa Variabel #

Direktori files/ berisi file yang disalin apa adanya ke managed node — tidak ada substitusi variabel. Gunakan ini untuk file binary, sertifikat, atau file konfigurasi yang tidak perlu dikustomisasi:

# roles/nginx/tasks/configure.yml
- name: Salin DH parameters untuk SSL
  copy:
    src: dhparam.pem          # Ansible otomatis cari di roles/nginx/files/
    dest: /etc/ssl/dhparam.pem
    owner: root
    mode: '0644'

Ansible secara otomatis mencari file di roles/<rolename>/files/ saat kamu menggunakan module copy tanpa path lengkap.

defaults/main.yml: Dokumentasi Sekaligus Konfigurasi #

defaults/main.yml yang baik bukan hanya daftar nilai — ia juga berfungsi sebagai dokumentasi variabel yang bisa dikustomisasi:

# roles/nginx/defaults/main.yml
---
# === KONFIGURASI DASAR ===
# Port yang digunakan nginx untuk melayani HTTP
nginx_port: 80

# Jumlah worker process. "auto" akan menggunakan jumlah CPU yang tersedia.
nginx_worker_processes: "auto"

# Koneksi maksimal per worker
nginx_worker_connections: 1024

# === SSL/TLS ===
# Set ke true untuk mengaktifkan HTTPS
nginx_ssl_enabled: false

# Port HTTPS (hanya berlaku jika nginx_ssl_enabled: true)
nginx_ssl_port: 443

# Path ke file sertifikat SSL
nginx_ssl_cert: ""
nginx_ssl_key: ""

# === PERFORMA ===
# Ukuran maksimal body request (upload)
nginx_client_max_body_size: "10m"

# Timeout koneksi keep-alive dalam detik
nginx_keepalive_timeout: 65

Dengan komentar seperti ini, pengguna role bisa memahami setiap variabel hanya dengan membaca defaults/main.yml — tanpa harus membaca README atau source code task.

meta/main.yml: Metadata dan Dependency #

meta/main.yml mendefinisikan informasi tentang role: siapa pembuatnya, platform apa yang didukung, dan role apa yang harus dijalankan sebelum role ini:

# roles/nginx/meta/main.yml
galaxy_info:
  author: "Tim Infrastruktur"
  description: "Role untuk instalasi dan konfigurasi nginx"
  company: "Contoh Corp"

  # Platform yang didukung
  platforms:
    - name: Ubuntu
      versions:
        - "20.04"
        - "22.04"
    - name: Debian
      versions:
        - "11"
        - "12"

  # Tag untuk pencarian di Ansible Galaxy
  galaxy_tags:
    - nginx
    - webserver
    - ssl

# Role yang harus dijalankan SEBELUM role ini
dependencies:
  - role: common    # common harus dijalankan dulu sebelum nginx

README.md: Dokumentasi yang Tidak Boleh Diabaikan #

Role tanpa dokumentasi yang baik hampir tidak berguna untuk orang lain. README minimal harus berisi:

# Role: nginx

Instalasi dan konfigurasi nginx sebagai web server.

## Requirements

- OS: Ubuntu 20.04/22.04 atau Debian 11/12
- Python: 3.8+

## Variabel

| Variabel | Default | Deskripsi |
|----------|---------|-----------|
| `nginx_port` | `80` | Port HTTP |
| `nginx_ssl_enabled` | `false` | Aktifkan HTTPS |
| `nginx_worker_processes` | `auto` | Jumlah worker process |

## Penggunaan

```yaml
- hosts: webservers
  roles:
    - role: nginx
      vars:
        nginx_port: 8080
        nginx_ssl_enabled: true

## Dependencies

- Role `common` harus dijalankan sebelum role ini.

Ringkasan #

  • tasks/main.yml sebagai orkestrator yang mendelegasikan ke file task spesifik (install.yml, configure.yml) — bukan tempat untuk ratusan task sekaligus.
  • Penamaan template mencerminkan nama file target di managed node: nginx.conf.j2 → /etc/nginx/nginx.conf.
  • files/ untuk file statis tanpa variabel; templates/ untuk file yang membutuhkan substitusi variabel Jinja2.
  • defaults/main.yml berfungsi ganda: nilai default sekaligus dokumentasi variabel yang bisa dikustomisasi — tulis komentar yang baik.
  • meta/main.yml mendefinisikan dependency role dan platform yang didukung.
  • README.md wajib ada — dokumentasikan semua variabel, requirements, dan contoh penggunaan.

← Sebelumnya: Apa itu Role?   Berikutnya: Dependency →

About | Author | Content Scope | Editorial Policy | Privacy Policy | Disclaimer | Contact