Project Structure #

Struktur project yang baik adalah fondasi dari semua best practice lainnya. Playbook yang ditulis dengan sempurna tapi disimpan di tempat yang tidak terduga akan membingungkan siapapun yang bergabung ke tim. Konvensi penamaan yang tidak konsisten memperlambat onboarding. Inventory yang tidak terorganisir menyebabkan konfigurasi diterapkan ke lingkungan yang salah. Artikel ini membahas struktur project Ansible yang terbukti skalabel untuk tim dari berbagai ukuran.

Layout Direktori yang Direkomendasikan #

ansible-infrastructure/
├── ansible.cfg                   # Konfigurasi Ansible untuk project ini
├── requirements.yml              # Dependency collection dan role eksternal
├── README.md                     # Onboarding guide — cara mulai
│
├── inventory/                    # Semua inventory
│   ├── development/
│   │   ├── hosts.ini
│   │   └── group_vars/
│   │       ├── all.yml
│   │       ├── webservers.yml
│   │       └── vault.yml         # Dienkripsi dengan ansible-vault
│   ├── staging/
│   │   ├── hosts.ini
│   │   └── group_vars/
│   │       ├── all.yml
│   │       ├── webservers.yml
│   │       └── vault.yml
│   └── production/
│       ├── hosts.ini
│       └── group_vars/
│           ├── all.yml
│           ├── webservers.yml
│           └── vault.yml
│
├── group_vars/                   # Variabel shared antar semua environment
│   └── all.yml
│
├── playbooks/                    # Semua playbook
│   ├── site.yml                  # Master playbook — menjalankan semua role
│   ├── deploy.yml                # Deployment aplikasi
│   ├── provision.yml             # Provisioning server baru
│   ├── patch.yml                 # Patch management
│   └── rollback.yml              # Emergency rollback
│
├── roles/                        # Role yang ditulis tim
│   ├── common/                   # Selalu dijalankan di semua server
│   ├── nginx/
│   ├── postgresql/
│   └── myapp/
│
├── collections/                  # Collection yang di-install lokal (git-ignored)
│   └── ansible_collections/
│
├── tests/                        # Test playbook dan fixtures
│   ├── test-vars.yml
│   └── integration/
│
├── scripts/                      # Script helper
│   ├── encrypt-vault.sh
│   └── rotate-vault-password.sh
│
└── .github/                      # CI/CD pipeline
    └── workflows/
        ├── validate.yml
        └── deploy.yml

ansible.cfg yang Terstruktur #

# ansible.cfg
[defaults]
inventory          = inventory/
roles_path         = roles:~/.ansible/roles
collections_paths  = collections:~/.ansible/collections
remote_user        = ansible-deploy
private_key_file   = ~/.ssh/ansible_deploy_key
host_key_checking  = true
retry_files_enabled = false       # Jangan buat file .retry
stdout_callback    = yaml          # Output lebih mudah dibaca
callbacks_enabled  = profile_tasks, timer

# Performance
forks              = 20
gathering          = smart
fact_caching       = jsonfile
fact_caching_connection = /tmp/ansible_fact_cache
fact_caching_timeout    = 3600

[ssh_connection]
pipelining         = true
ssh_args           = -o ControlMaster=auto -o ControlPersist=60s

[vault]
vault_identity_list = [email protected]_pass_dev, [email protected]_pass_staging, [email protected]_pass_prod

Konvensi Penamaan yang Konsisten #

INVENTORY GROUPS:
  Format: [tier]_[role] atau hanya [role]
  Contoh: webservers, dbservers, cache_servers, load_balancers
  Hindari: web, db, ws (terlalu singkat dan ambigu)

VARIABEL:
  Format: [scope]_[nama_deskriptif]
  Contoh: nginx_port, app_log_dir, postgresql_max_connections
  Vault: prefix vault_ untuk variabel terenkripsi: vault_db_password, vault_api_key

PLAYBOOK:
  Format: [kata kerja]-[objek].yml
  Contoh: deploy-app.yml, provision-server.yml, rotate-certs.yml, patch-os.yml
  Hindari: main.yml, run.yml (terlalu generic)

ROLE:
  Format: nama komponen lowercase dengan tanda hubung
  Contoh: nginx, postgresql, node-exporter, cert-manager
  Hindari: setup_nginx, install-postgresql (verba tidak perlu di nama role)

FILE VAULT:
  Format: vault.yml (di group_vars) atau [nama].vault.yml
  Enkripsi: SELALU per-environment, bukan satu file vault untuk semua

site.yml: Titik Masuk yang Jelas #

# playbooks/site.yml — master playbook
# Menjalankan semua role ke semua host yang tepat
# Berguna untuk: setup server baru, baseline compliance check, full redeploy

---
- name: Apply common configuration ke semua server
  hosts: all
  roles:
    - common

- name: Setup load balancer
  hosts: load_balancers
  roles:
    - nginx
    - certbot

- name: Setup web application servers
  hosts: webservers
  roles:
    - nginx
    - myapp
    - node-exporter

- name: Setup database servers
  hosts: dbservers
  roles:
    - postgresql
    - postgresql-backup
    - node-exporter

README.md yang Efektif #

# Ansible Infrastructure

Repositori ini berisi semua konfigurasi infrastruktur menggunakan Ansible.

## Prasyarat

- Python 3.11+
- Ansible 2.15+
- Akses ke private key `~/.ssh/ansible_deploy_key`

## Setup Pertama Kali

```bash
pip install ansible
ansible-galaxy install -r requirements.yml
cp .vault_pass.example .vault_pass_staging
# Edit .vault_pass_staging dengan password vault yang benar
```

## Menjalankan Playbook

```bash
# Deploy ke staging
ansible-playbook -i inventory/staging/ playbooks/deploy.yml -e "version=2.1.0"

# Apply semua konfigurasi ke production (dry run dulu)
ansible-playbook -i inventory/production/ playbooks/site.yml --check --diff

# Patch management
ansible-playbook -i inventory/staging/ playbooks/patch.yml
```

## Struktur Direktori

- `inventory/` — Konfigurasi host per environment
- `playbooks/` — Playbook untuk berbagai operasi
- `roles/` — Role yang bisa digunakan ulang
- `group_vars/` — Variabel shared antar environment

## Menambahkan Server Baru

Lihat `docs/adding-new-server.md` untuk panduan lengkap.

Ringkasan #

Satu direktori inventory per environment — mencegah konfigurasi yang salah diterapkan ke lingkungan yang salah dan memudahkan audit.
ansible.cfg di root project memastikan semua orang di tim menggunakan konfigurasi yang sama — tidak ada perbedaan perilaku antar mesin.
Konvensi penamaan konsisten untuk grup, variabel, playbook, dan role — tim baru harus bisa menebak lokasi file tanpa bertanya.
site.yml sebagai titik masuk yang jelas untuk full setup/redeploy — ia mendokumentasikan apa yang berjalan di mana.
README.md yang actionable: bukan penjelasan panjang lebar, tapi perintah konkret yang bisa langsung dijalankan engineer baru.
requirements.yml dengan versi yang di-pin untuk semua dependency eksternal — memastikan reproduktifitas di mesin yang berbeda dan di CI/CD.

← Sebelumnya: CI/CD Anti Pattern Berikutnya: Code Quality →