Best Practice #

Mengelola inventaris Ansible pada lingkungan skala kecil sangatlah mudah. Namun, ketika infrastruktur kita berkembang mencakup ratusan server virtual, multi-cloud, serta dikelola oleh beberapa tim platform engineering secara paralel, inventaris yang tidak terstruktur akan menjadi beban pemeliharaan yang berat. Artikel best practice ini tidak menyusun aturan-aturan kaku yang mengekang, melainkan menyajikan prinsip-prinsip desain teruji yang akan menjaga berkas inventaris kita tetap bersih, aman, mudah dipahami (bahkan oleh anggota tim baru yang baru bergabung), dan skalabel untuk kebutuhan masa depan.

1. Satu Inventory per Lingkungan #

Isolasi fisik adalah prinsip keamanan pertama dalam manajemen inventaris. Kita wajib memisahkan data server target untuk lingkungan Pengembangan (development), Pengujian (staging), dan Produksi (production) ke dalam folder atau berkas yang berbeda secara fisik.

# Rekomendasi Struktur Isolasi Lingkungan:
environments/
  ├── development/
  │   ├── hosts.ini
  │   └── group_vars/
  ├── staging/
  │   ├── hosts.ini
  │   └── group_vars/
  └── production/
      ├── hosts.ini
      └── group_vars/

Menyatukan semua lingkungan dalam satu berkas inventaris monolitik sangat dilarang karena memperbesar blast radius dari kesalahan penulisan perintah limit di terminal. Dengan memisahkan direktori secara fisik, setiap eksekusi playbook menuntut penunjukan argumen inventaris secara eksplisit:

# Eksekusi terkendali ke server produksi
ansible-playbook -i environments/production/hosts.ini playbooks/site.yml

Strategi Git Branching dan Akses Kontrol #

Selain pemisahan folder fisik, kita direkomendasikan untuk menerapkan kontrol akses (permissions) menggunakan aturan Git. Kita dapat mengunci folder environments/production/ pada repositori Git menggunakan berkas CODEOWNERS. Dengan demikian, setiap perubahan pada daftar server produksi atau variabel produksi wajib melalui proses peninjauan (pull request review) oleh tim administrator senior sebelum dapat digabungkan ke cabang utama (main branch).

2. Beri Nama Host yang Deskriptif #

Menggunakan alamat IP mentah atau nama host bawaan cloud provider (seperti ip-10-0-1-24.ap-southeast-1.compute.internal) sebagai pengenal server di file inventaris adalah sebuah anti-pattern yang mempersulit pemantauan.

Kita harus mengadopsi pola penamaan yang konsisten dan informatif yang langsung mencerminkan tiga dimensi server target: Lingkungan, Fungsi (Peran), dan Nomor Urut.

# ANTI-PATTERN: Nama host acak dan alamat IP mentah
[webservers]
10.0.1.15
server-v3-instance
vm-web-staging-01

# BENAR: Penamaan deskriptif berpola {env}-{role}-{nomor}.{domain}
[webservers]
prod-web-01.unisbadri.com
prod-web-02.unisbadri.com

[dbservers]
prod-db-primary-01.unisbadri.com
prod-db-replica-01.unisbadri.com

Penanganan Hostname pada Autoscaling #

Jika kita menggunakan layanan cloud autoscaling di mana instans server virtual lahir dan mati dengan nama acak dari AWS API, kita dapat menggunakan pemetaan caching internal atau memanfaatkan tag metadata cloud provider sebagai nama host dinamis di Ansible. Kita dapat menyusun parameter hostnames di berkas konfigurasi plugin dinamis AWS EC2 kita untuk memetakan nama instans berdasarkan tag Name yang diberikan secara otomatis oleh pustaka provisioning cloud kita (seperti Terraform).

3. Kelompokkan secara Hierarkis #

Gunakan fitur grup-dalam-grup (nested groups) menggunakan kata kunci :children untuk membangun struktur topologi infrastruktur kita. Hal ini memberikan fleksibilitas tinggi saat menargetkan eksekusi playbook.

# File: inventory/production/hosts.ini

# Grup tingkat terendah (Granular)
[web_primary]
prod-web-01.example.com

[web_cdn]
prod-cdn-01.example.com

# Grup gabungan tingkat menengah
[webservers:children]
web_primary
web_cdn

[db_primary]
prod-db-01.example.com

[db_replica]
prod-db-02.example.com

[dbservers:children]
db_primary
db_replica

# Grup tingkat teratas (Top-Level Group)
[production:children]
webservers
dbservers

Struktur hierarkis ini memudahkan kita memilih cakupan tindakan:

Jika kita ingin memperbarui sertifikat SSL CDN: targetkan web_cdn.
If we want to update Nginx configurations globally: target webservers.
Jika kita ingin memicu backup sistem produksi global: targetkan production.

Pewarisan variabel pada struktur ini mengalir ke bawah. Properti yang didefinisikan pada production:vars akan otomatis mengalir ke webservers dan dbservers, namun variabel yang didefinisikan pada web_primary:vars tidak akan mempengaruhi server lain yang berada di luar grup anak tersebut.

4. Pisahkan Variabel Berdasarkan Concern #

Jangan biarkan file variabel tingkat grup (group_vars/all.yml atau group_vars/webservers.yml) membengkak menjadi file raksasa berisi ratusan baris kode YAML. Pisahkan variabel tersebut ke dalam subdirektori bermakna yang sejajar dengan topik layanannya.

# Rekomendasi Struktur Penyimpanan Variabel:
group_vars/
  ├── all/
  │   ├── system.yml      # Pengaturan dasar: timezone, ntp, dns
  │   └── security.yml    # Pengaturan pengerasan keamanan firewall
  ├── webservers/
  │   ├── nginx.yml       # Konfigurasi parameter web server Nginx
  │   ├── php.yml         # Konfigurasi runtime PHP-FPM
  │   └── ssl.yml         # Konfigurasi jalur kunci enkripsi SSL/TLS
  └── dbservers/
      ├── postgresql.yml  # Konfigurasi database PostgreSQL
      └── backup.yml      # Jadwal otomatisasi pencadangan database

Contoh Penerapan Pemisahan Variabel #

Berikut adalah ilustrasi isi berkas YAML di dalam folder group_vars/webservers/ yang terpisah secara modular:

nginx.yml:

---
nginx_version: "1.24"
nginx_worker_processes: 4
nginx_client_max_body_size: "10m"

php.yml:

---
php_version: "8.2"
php_memory_limit: "256M"
php_max_execution_time: 60

ssl.yml:

---
ssl_cert_path: "/etc/ssl/certs/app.crt"
ssl_key_path: "/etc/ssl/private/app.key"

Menerapkan pemisahan ini membuat kode kita lebih modular dan mempercepat proses troubleshooting karena lokasi pendefinisian parameter sangat mudah ditemukan.

5. Dokumentasikan Variabel yang Tidak Obvious #

Mendokumentasikan alasan di balik pemilihan nilai parameter yang tidak standar (tidak umum) menggunakan komentar di atas baris variabel YAML sangat membantu menjaga keberlangsungan proyek saat dikelola oleh insinyur lain di masa mendatang.

# File: group_vars/webservers/nginx.yml
---
# Nginx Tuning Parameters:

# Nilai worker_processes diatur ke 8 mencocokkan jumlah vCPU instans tipe c5.2xlarge
# JANGAN naikkan nilai ini jika tipe instans managed node di AWS diturunkan (*downgraded*)
nginx_worker_processes: 8

# Dibatasi maksimal 15M untuk membatasi ukuran unggahan berkas dokumen PDF
nginx_client_max_body_size: "15m"

# Timeout dinaikkan menjadi 180 detik khusus untuk menampung respon kueri laporan keuangan legacy API
# Target refaktor: ganti kembali ke 30s setelah endpoint report dimigrasi ke microservices Q4 2026
nginx_proxy_read_timeout: 180

Komentar kontekstual seperti ini menghindarkan tim dari perdebatan berulang tentang mengapa suatu parameter diatur ke angka tertentu.

6. Gunakan Variabel untuk Membedakan Lingkungan #

Saat menulis playbook, kita sering menghadapi kondisi di mana satu tugas harus dijalankan secara berbeda berdasarkan lingkungan target (misalnya mengaktifkan fitur pencatatan debug di staging tetapi mematikannya di produksi).

Kita sangat dilarang menuliskan kondisi pengecekan nama host secara imperatif menggunakan conditional when di dalam file task playbook. Hal ini mengotori alur kerja playbook kita dengan detail nama server yang dinamis.

# ANTI-PATTERN: Mengecek nama host target di dalam task playbook
- name: Aktifkan visualisasi log debug
  template:
    src: app.conf.j2
    dest: /etc/app/app.conf
  when: inventory_hostname in groups['staging']  # Kaku dan sulit dirawat

Praktek terbaiknya adalah menyerahkan perbedaan perilaku tersebut kepada variabel inventaris masing-masing lingkungan, lalu menulis playbook secara deklaratif murni menggunakan variabel tersebut:

# 1. Definisikan variabel di berkas lingkungan staging:
# environments/staging/group_vars/all.yml
enable_app_debug: true

# 2. Definisikan variabel di berkas lingkungan produksi:
# environments/production/group_vars/all.yml
enable_app_debug: false

# 3. Tulis playbook secara bersih tanpa peduli nama lingkungan target:
# playbooks/deploy.yml
- name: Konfigurasikan aplikasi
  template:
    src: app.conf.j2
    dest: /etc/app/app.conf
  # Variabel enable_app_debug akan diserap secara dinamis dari inventaris aktif

7. Simpan Inventory di Git #

Inventaris adalah bagian tidak terpisahkan dari Infrastructure as Code (IaC). Kita wajib menyimpan seluruh struktur direktori inventaris (termasuk folder environments/, berkas requirements.yml, dan plugin constructed) ke dalam repositori Git bersama kode playbook dan role kita.

Hal ini memberikan pencatatan riwayat perubahan (audit trail) yang jelas: siapa yang menambahkan server baru, kapan variabel di-update, dan mempermudah pemulihan sistem jika terjadi kesalahan konfigurasi (rollback).

Namun, kita harus mengonfigurasi file .gitignore secara ketat untuk mencegah kebocoran kunci otentikasi privat atau file sandi plaintext lokal:

# File: .gitignore
# Mengabaikan file cadangan otomatis Ansible
*.retry

# Mengabaikan kunci otentikasi SSH privat lokal yang diletakkan tidak sengaja
*.pem
*.key
id_rsa
id_ed25519

# Mengabaikan berkas sandi pembaca Vault lokal
.vault_pass
vault_password.txt

Assembly Runtime Ansible #

Untuk menyimpulkan seluruh best practice ini dalam arsitektur Ansible, diagram di bawah ini mengilustrasikan bagaimana seluruh sumber data inventaris, berkas variabel, playbook, dan role dirakit secara dinamis oleh Ansible Engine pada saat eksekusi runtime sebelum dikirim ke mesin target via SSH:

flowchart TD
    subgraph "Sumber Inventaris (Data Target)"
        A["hosts.ini / hosts.yml atau Cloud Plugin"] -->|"1. Muat Host & Grup"| E["Ansible Runtime Engine"]
    end
    subgraph "Sumber Variabel (Data Parameter)"
        B["group_vars/all/*.yml"] -->|"2. Muat Variabel Global"| E
        C["group_vars/webservers/*.yml"] -->|"3. Muat Variabel Grup"| E
        D["host_vars/web-01.yml"] -->|"4. Muat Variabel Host"| E
    end
    subgraph "Logika Eksekusi (Tindakan)"
        F["Playbook (playbooks/webservers.yml)"] -->|"5. Definisikan Alur Kerja & Roles"| E
        G["Ansible Roles (roles/nginx/)"] -->|"6. Sediakan Template & Tasks"| E
    end
    E -->|"7. Rakit Kombinasi Final (hostvars)"| H["Managed Nodes via SSH"]

22 Tingkat Precedence Variabel Ansible #

Untuk memahami bagaimana Ansible merakit variabel final di langkah ke-7 pada diagram di atas, kita harus menyadari keberadaan urutan precedence global. Berikut adalah 22 tingkat prioritas variabel di Ansible (diurutkan dari prioritas terendah ke prioritas tertinggi):

role defaults: Variabel default dalam folder defaults/main.yml di dalam sebuah role.
inventory file or script group vars: Variabel yang didefinisikan di dalam berkas inventaris untuk sebuah grup.
inventory group_vars/all: Variabel global dalam berkas group_vars/all.yml.
playbook group_vars/all: Variabel global group_vars/all.yml yang terletak di dekat playbook.
inventory group_vars/: Variabel grup yang didefinisikan sejajar dengan inventaris.
playbook group_vars/: Variabel grup yang didefinisikan sejajar dengan berkas playbook.
inventory file or script host vars: Variabel host yang didefinisikan langsung di dalam berkas inventaris.
inventory host_vars/: Variabel host yang didefinisikan sejajar dengan inventaris.
playbook host_vars/: Variabel host yang didefinisikan sejajar dengan berkas playbook.
host facts / cached facts: Variabel hasil pengumpulan sistem target oleh modul setup.
play vars: Variabel yang didefinisikan langsung pada blok vars: di dalam playbook.
play vars_files: Variabel yang diimpor menggunakan parameter vars_files: di dalam playbook.
role vars: Variabel yang didefinisikan dalam folder vars/main.yml di dalam sebuah role.
block vars: Variabel yang didefinisikan pada tingkat blok di dalam task.
task vars: Variabel yang didefinisikan langsung pada tingkat tugas tunggal (task).
include_vars: Variabel yang dimuat secara dinamis saat eksekusi task menggunakan modul include_vars.
set_facts / registered vars: Variabel yang dibuat dinamis menggunakan modul set_fact atau tangkapan modul register.
role params: Parameter yang dikirimkan saat memanggil role.
include params: Parameter yang dikirimkan saat memanggil file tugas via include.
handler vars: Variabel yang digunakan di dalam handler.
extra vars (CLI): Variabel yang didefinisikan di terminal menggunakan flag -e atau --extra-vars. Ini adalah prioritas tertinggi yang tidak dapat ditimpa oleh apa pun.

Memahami urutan precedence ini membantu kita merancang strategi penempatan variabel yang aman dan terprediksi.

Checklist Review Inventory #

Gunakan lembar checklist ini sebagai pedoman wajib saat melakukan peninjauan kode (pull request review) pada repositori otomatisasi Ansible tim kita:

1. Struktur Direktori & Isolasi #

Isolasi Fisik: Berkas inventaris dipisahkan secara fisik berdasarkan lingkungan target (dev, staging, prod) ke dalam folder tersendiri untuk meminimalkan salah sasaran eksekusi.
Pemisahan Folder: Folder inventaris diletakkan terpisah secara teratur dari folder playbooks/ dan roles/ agar struktur repositori tetap rapi.
Tanpa Variabel Inline: Tidak ada variabel inline panjang yang ditulis menumpuk di file hosts.ini yang dapat merusak kerapian berkas.

2. Standar Penamaan #

Nama Grup Konsisten: Nama grup ditulis dengan lowercase, jamak (plural), dan underscore (misal: dbservers, application_servers) untuk menghindari ketidakcocokan parser.
Nama Host Deskriptif: Nama host deskriptif mencakup informasi env, role, dan indeks (misal: prod-web-01.example.com) guna memudahkan penelusuran logs.
Nama Variabel: Nama variabel kustom menggunakan format snake_case secara konsisten di seluruh berkas YAML.

3. Pengelolaan Variabel #

Konsolidasi Global: Parameter global homogen dikonsolidasikan di group_vars/all.yml untuk mencegah duplikasi kode.
Pemisahan Concern: File group_vars dipisah berdasarkan concern (seperti nginx.yml, postgresql.yml) jika jumlah variabel sudah melebihi 20 baris.
Komentar Konteks: Terdapat komentar penjelas alasan di atas nilai parameter kustom yang tidak standar untuk menjaga transfer pengetahuan antar insinyur.

4. Keamanan & Git #

Enkripsi Rahasia: Tidak ada password, private key, atau API token dalam bentuk plaintext yang dapat bocor ke publik.
Ansible Vault: Seluruh data kredensial sensitif dienkripsi menggunakan Ansible Vault secara aman.
Abaikan Git: Berkas rahasia lokal (.vault_pass, *.pem, *.key) telah terdaftar di file .gitignore proyek.
Verifikasi Eksekusi: Perintah ansible-inventory --graph berjalan sukses 100% tanpa memicu peringatan warning atau error.

Ringkasan #

Isolasi Lingkungan Fisik — Memisahkan inventaris secara fisik per folder lingkungan menghindarkan resiko fatal eksekusi deployment ke produksi akibat kesalahan ketik limit.

Konvensi Nama Deskriptif — Adopsi format {env}-{role}-{nomor}.{domain} untuk memberikan identitas visual instan pada server target di log audit.

Abstraksi Modular group_vars — Pisahkan berkas parameter berdasarkan concern di subdirektori group_vars untuk mempermudah troubleshooting dan audit parameter.

Deklaratif Bukan Kondisional — Hindari penggunaan pengecekan manual hostname target di playbook; pindahkan perbedaan logika ke data variabel inventaris.

Dokumentasi Keputusan Desain — Selalu sertakan komentar penjelasan di atas variabel yang menggunakan nilai tidak standar untuk menjaga kontinuitas pengetahuan tim.

Git as Source of Truth — Simpan konfigurasi inventaris di dalam Git, dan lindungi kredensial menggunakan penulisan .gitignore yang sangat ketat.

Verifikasi Checklist — Gunakan checklist review inventaris secara disiplin sebelum menggabungkan kode otomatisasi baru ke cabang utama repositori.

← Sebelumnya: Anti-Pattern Berikutnya: Apa itu Playbook? →