Code Quality #

Kualitas kode di dalam otomatisasi Ansible bukan sekadar tentang estetika penulisan, melainkan faktor penentu keandalan infrastruktur. Kode Ansible yang ditulis secara tergesa-gesa tanpa standarisasi format akan menjadi hutang teknis (technical debt) yang sangat besar. Ketika kode tersebut sulit dipahami, risiko kegagalan eksekusi di lingkungan production akan meningkat tajam. Kita harus menerapkan kontrol kualitas kode yang ketat—mulai dari analisis statis (linting), pembatasan Git commit, hingga proses review yang terstruktur—untuk memastikan setiap baris kode infrastruktur kita aman, idempoten, dan mudah dipelihara oleh seluruh anggota tim.

1. Menerapkan Profil ansible-lint yang Ketat #

ansible-lint adalah alat utama kita untuk menganalisis kode secara statis (static analysis). Alat ini mendeteksi kesalahan umum, praktik buruk, dan celah keamanan dalam playbook, role, dan variabel sebelum kita menjalankannya pada infrastruktur nyata.

Sejak versi modern, ansible-lint memperkenalkan konsep “profile” yang menentukan tingkat keketatan aturan. Untuk project berskala enterprise yang mengutamakan kestabilan, kita wajib menerapkan profil tertinggi: production.

Berikut adalah file konfigurasi .ansible-lint standar industri yang kita gunakan untuk mengontrol kualitas kode secara ketat:

# .ansible-lint
# Menggunakan profil production untuk standar kualitas tertinggi
profile: production

# Mengaktifkan aturan bawaan terlengkap
use_default_rules: true

# Aturan yang kita kecualikan secara sengaja dengan alasan teknis yang kuat
skip_list:
  - yaml[line-length]    # Perintah command/shell yang panjang terkadang tidak dapat dipotong
  - fqcn[action-core]    # Mengizinkan penulisan modul bawaan tanpa nama koleksi lengkap untuk menyederhanakan kode

# Aturan yang kita kategorikan sebagai peringatan (warning) terlebih dahulu (bukan error)
warn_list:
  - no-changed-when      # Kita izinkan sebagai warning selama proses migrasi kode lama berlangsung
  - jinja[spacing]       # Spasi pada jinja template menjadi warning agar tidak mengganggu build blocking

# Direktori yang kita kecualikan sepenuhnya dari proses linting (misal cache dan pihak ketiga)
exclude_paths:
  - .cache/
  - molecule/
  - vendor/
  - collections/

# Menunjuk direktori tempat kita menyimpan aturan linting custom buatan tim internal
rulesdir:
  - .ansible-lint-rules/

# Konfigurasi detail output terminal
verbosity: 1
show_progress: true

Mengapa Memilih Profil Production? #

Profil production memastikan kode kita memenuhi standar kesiapan deployment nyata. Profil ini mewajibkan setiap task memiliki nama yang jelas, semua modul menggunakan parameter yang aman, dan tidak ada penggunaan fungsi-fungsi usang (deprecated functions) yang dapat merusak eksekusi di versi Ansible yang lebih baru.

2. Menulis Aturan Lint Custom (Custom Lint Rules) #

Terkadang, aturan bawaan ansible-lint tidak mencakup kebijakan internal organisasi kita. Sebagai contoh, kita mungkin ingin melarang penggunaan variabel sensitif (secret) yang ditulis langsung dalam bentuk teks biasa (plaintext) tanpa enkripsi Ansible Vault. Untuk kebutuhan ini, kita dapat menulis aturan custom menggunakan bahasa pemrograman Python.

Kita membuat sebuah script Python di dalam folder .ansible-lint-rules/NoPlaintextSecrets.py:

# .ansible-lint-rules/NoPlaintextSecrets.py
"""Aturan custom untuk mendeteksi penulisan secret plaintext di variabel."""

from ansiblelint.rules import AnsibleLintRule
import re

# Pola regex untuk mendeteksi key yang terindikasi berisi rahasia/secret
SECRET_KEYS = [
    r'password',
    r'api_key',
    r'secret',
    r'token',
    r'private_key'
]


class NoPlaintextSecrets(AnsibleLintRule):
    id = 'COMP001'
    shortdesc = 'Dilarang keras menyimpan rahasia (secret) dalam plaintext'
    description = (
        'Semua variabel yang mengandung kata kunci sensitif seperti password, '
        'api_key, atau token wajib disimpan menggunakan enkripsi Ansible Vault '
        'atau dirujuk menggunakan sintaks Jinja2. Plaintext dilarang.'
    )
    severity = 'VERY_HIGH'
    tags = ['security', 'company-policy']

    def matchplay(self, file, data):
        """Memeriksa variabel yang dideklarasikan di tingkat playbook/play."""
        errors = []
        if not data:
            return errors

        # Mencari blok variabel 'vars' di tingkat play
        play_vars = data.get('vars', {})
        if isinstance(play_vars, dict):
            for key, value in play_vars.items():
                # Jika key cocok dengan kriteria secret dan value bukan sintaks Jinja2 {{ ... }}
                if any(re.search(pattern, key, re.IGNORECASE) for pattern in SECRET_KEYS):
                    if isinstance(value, str) and not (value.startswith('{{') and value.endswith('}}')):
                        errors.append(
                            self.create_matcherror(
                                message=f"Variabel sensitif '{key}' ditulis plaintext. Gunakan Ansible Vault!",
                                filename=file.name
                            )
                        )
        return errors

    def matchtask(self, task, file):
        """Memeriksa variabel yang ditulis di tingkat task (vars atau argumen)."""
        errors = []
        task_vars = task.get('vars', {})
        if isinstance(task_vars, dict):
            for key, value in task_vars.items():
                if any(re.search(pattern, key, re.IGNORECASE) for pattern in SECRET_KEYS):
                    if isinstance(value, str) and not (value.startswith('{{') and value.endswith('}}')):
                        errors.append(
                            self.create_matcherror(
                                message=f"Task variable '{key}' terdeteksi plaintext di task '{task.get('name')}'",
                                filename=file.name
                            )
                        )
        return errors

Aturan custom di atas akan memindai setiap file YAML dan memicu kegagalan build jika mendeteksi variabel seperti db_password: "password_mentah" tanpa dibungkus kurung kurawal Jinja2 yang merujuk ke file Vault terenkripsi.

3. Otomatisasi Validasi Melalui Pre-commit Hooks #

Meninggalkan proses linting hanya pada saat pipeline CI/CD berjalan di server Git adalah praktik yang kurang efisien. Developer harus menunggu beberapa menit hingga pipeline berjalan hanya untuk mengetahui ada kesalahan spasi atau syntax minor. Hal ini memperlambat siklus pengembangan.

Kita harus mengintegrasikan pengujian ini langsung ke komputer developer menggunakan pre-commit hooks. Alat ini akan otomatis memotong proses Git commit dan memvalidasi file yang diubah sebelum commit berhasil dibuat.

Berikut adalah konfigurasi .pre-commit-config.yaml terlengkap yang wajib kita gunakan di setiap repositori project:

# .pre-commit-config.yaml
# Menentukan hook yang berjalan sebelum git commit berhasil dibuat
repos:
  # 1. Integrasi dengan Ansible Lint resmi
  - repo: https://github.com/ansible/ansible-lint
    rev: v24.2.0
    hooks:
      - id: ansible-lint
        name: "Ansible Linting (Profil: Production)"
        args: ['--profile=production']
        files: \.(yml|yaml)$
        exclude: ^(molecule|vendor|collections)/

  # 2. Integrasi dengan Yamllint untuk merapikan format spasi/tata letak YAML
  - repo: https://github.com/adrienverge/yamllint
    rev: v1.35.1
    hooks:
      - id: yamllint
        name: "YAML Format Auditor"
        args: [-c=.yamllint]

  # 3. Kumpulan hooks standard untuk menjaga integritas file repositori
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: check-yaml
        name: "Verify YAML Syntax"
      - id: check-merge-conflict
        name: "Prevent Git Merge Conflicts"
      - id: trailing-whitespace
        name: "Remove Trailing Whitespaces"
      - id: end-of-file-fixer
        name: "Ensure Newline at EOF"
      - id: detect-private-key
        name: "Block Accidental SSH Private Key Commits"
      - id: check-added-large-files
        name: "Prevent Committing Large Files (>500KB)"
        args: ['--maxkb=500']

  # 4. Integrasi dengan Gitleaks untuk mencegah kebocoran kredensial (secrets)
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.0
    hooks:
      - id: gitleaks
        name: "Scan Repository for Leaked Secrets"

Cara Pemasangan di Mesin Developer: #

Untuk menggunakan sistem otomatisasi pre-commit ini, kita cukup menjalankan perintah berikut satu kali pada komputer lokal kita:

# Menginstal tool pre-commit menggunakan python package manager
pip install pre-commit

# Memasang hook ke dalam database Git lokal repositori kita
pre-commit install

# Menjalankan pengujian manual ke seluruh berkas untuk pertama kali
pre-commit run --all-files

Sekarang, setiap kali kita menjalankan git commit -m "update configuration", seluruh pengujian di atas akan dieksekusi secara otomatis. Jika ada file yang melanggar aturan format atau keamanan, proses commit akan dibatalkan secara otomatis dan kita akan diberikan laporan baris mana yang harus diperbaiki.

4. Konfigurasi yamllint untuk Konsistensi Format #

Meskipun Ansible dapat membaca format YAML yang tidak rapi selama strukturnya valid, format yang tidak konsisten (misalnya campuran indentasi 2 spasi dan 4 spasi) akan menyulitkan pembacaan kode oleh anggota tim lain.

Kita menggunakan yamllint untuk memaksakan konsistensi gaya penulisan YAML di seluruh berkas.

Berikut konfigurasi .yamllint yang kita rekomendasikan:

# .yamllint
# Dokumentasi aturan format penulisan file YAML
---
extends: default

rules:
  # Membatasi panjang maksimal karakter dalam satu baris
  line-length:
    max: 160              # Kita longgarkan ke 160 karakter untuk mengakomodasi command shell yang panjang
    level: warning        # Memberikan peringatan tanpa memblokir build jika melanggar

  # Mengatur nilai kebenaran boolean (true/false)
  truthy:
    allowed-values: ['true', 'false'] # Hanya mengizinkan penulisan lowercase true/false
    check-keys: false     # Jangan memeriksa kunci asosiatif

  # Mengatur jarak spasi di dalam komentar berkas
  comments:
    min-spaces-before-comment: 1
    require-starting-space: true

  # Mengatur jarak spasi di dalam kurung kurawal
  braces:
    min-spaces-inside: 0
    max-spaces-inside: 1

  # Memaksakan indentasi yang konsisten
  indentation:
    spaces: 2             # Wajib menggunakan 2 spasi untuk setiap level indentasi
    indent-sequences: consistent

Dengan aturan ini, kita memastikan tidak ada file YAML dengan spasi berantakan yang masuk ke repositori utama.

5. Alur Pengendalian Kualitas dalam Pipeline CI/CD #

Untuk menjamin tidak ada kode kotor yang masuk ke cabang utama (main branch) meskipun developer menonaktifkan hook pre-commit lokal mereka secara sengaja, kita harus menerapkan gerbang validasi akhir (final gateway) pada pipeline CI/CD (misalnya menggunakan GitHub Actions).

Berikut adalah alur perjalanan kode (workflow) dari komputer lokal hingga masuk ke production:

flowchart TD
    A["Developer Menulis Kode"] --> B["Pre-commit Hook (Lokal)"]
    B -->|"Lolos"| C["Git Push ke Branch Baru"]
    B -->|"Gagal"| D["Perbaiki Kode di Mesin Lokal"]
    C --> E["Buka Pull Request (PR)"]
    E --> F["CI Pipeline (Lint & Syntax Check)"]
    F -->|"Lolos"| G["Peer Review (Checklist Manual)"]
    F -->|"Gagal"| H["Blokir PR & Beri Notifikasi Error"]
    G -->|"Disetujui"| I["Merge ke Main Branch"]
    G -->|"Ditolak"| D

Berikut adalah contoh konfigurasi pipeline otomatisasi GitHub Actions .github/workflows/validate.yml untuk melakukan pengecekan kualitas kode pada setiap Pull Request:

# .github/workflows/validate.yml
name: Code Quality Validation

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  validate:
    name: Lint & Verify Syntax
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: 'pip'

      - name: Install Dependencies
        run: |
          python -m pip install --upgrade pip
          pip install ansible-lint yamllint pre-commit          

      - name: Run Yamllint Audit
        run: yamllint -c .yamllint .

      - name: Run Ansible Lint Verification
        run: ansible-lint --profile=production

      - name: Execute Playbook Syntax Verification
        run: |
          # Melakukan cek sintaksis terhadap semua playbook utama kita
          for playbook in playbooks/*.yml; do
            ansible-playbook "$playbook" --syntax-check
          done

6. Praktik Dokumentasi Inline yang Efektif #

Dokumentasi inline yang baik bukan menjelaskan APA yang dilakukan oleh baris kode tersebut (karena sintaks YAML Ansible sudah sangat deklaratif dan mudah dibaca), melainkan menjelaskan MENGAPA kita memilih pendekatan tersebut atau keputusan arsitektur di baliknya.

Contoh Perbandingan Kode: #

# ANTI-PATTERN: Task tanpa penjelasan tujuan, menggunakan modul mentah, dan tidak deskriptif
- name: Run command
  command: systemctl restart nginx

- name: install packages
  apt:
    name: ["nginx", "git"]

# BENAR: Task deskriptif, menggunakan modul terdedikasi, serta memberikan konteks MENGAPA
- name: Restart nginx untuk memuat sertifikat SSL Let's Encrypt yang baru diperbarui
  systemd:
    name: nginx
    state: restarted

- name: Install paket prasyarat untuk web proxy internal
  apt:
    name:
      - nginx
      - git
    state: present
    update_cache: true

# Dokumentasi inline menerangkan logika yang tidak umum/tidak intuitif
- name: Tunggu hingga aplikasi siap menerima koneksi HTTP
  uri:
    url: "http://localhost:8080/health"
    status_code: 200
  register: result
  until: result.status == 200
  retries: 10
  delay: 5
  # PENGECUALIAN TEKNIS: Aplikasi kita membutuhkan waktu inisialisasi koneksi database
  # selama kurang lebih 20 detik pada saat startup sebelum endpoint /health dapat diakses.
  # Oleh karena itu, kita berikan delay 5 detik dengan batas percobaan 10 kali.

7. Checklist Review Kualitas Kode #

Kita wajib menyertakan panduan review ini pada setiap Pull Request. Reviewer harus menandai setiap poin checklist di bawah ini sebelum memberikan persetujuan (approval):

KEBENARAN & IDEMPOTENSI:
  □ Task tidak menggunakan modul command/shell jika tersedia modul khusus (misal apt, systemd, file).
  □ Semua task command/shell menyertakan conditional changed_when atau creates/removes agar idempoten.
  □ Handler digunakan dengan benar untuk merespons perubahan, bukan memanggil perintah restart langsung.
  □ Penanganan error (failed_when atau ignore_errors) diimplementasikan pada task yang rentan gagal.

KEAMANAN & RAHASIA:
  □ Tidak ada kunci API, password database, atau private key yang ditulis secara plaintext.
  □ Task yang menampilkan output sensitif telah dilengkapi dengan parameter no_log: true.
  □ Akses root (become: true) hanya dibatasi pada task yang benar-benar membutuhkan hak istimewa.
  □ File-file temporary yang dibuat dalam task selalu dihapus kembali di akhir eksekusi.

STRUKTUR KODE & VARIABEL:
  □ Seluruh variabel role dideklarasikan dengan nilai default di direktori defaults/main.yml.
  □ Tidak ada hardcode nilai konfigurasi; semua dialihkan ke variabel konseptual.
  □ Tipe data boolean ditulis secara konsisten menggunakan format lowercase (true/false).
  □ Parameter task diatur dalam bentuk list terstruktur (YAML block), bukan string panjang sebaris.

Anti-Pattern yang Harus Dihindari #

Berikut adalah beberapa kesalahan fatal terkait kualitas kode Ansible yang wajib kita hindari:

1. Menggunakan Command/Shell Tanpa Batas Idempotensi #

Penggunaan perintah shell mentah tanpa batasan akan menyebabkan task selalu mengembalikan status changed pada setiap kali eksekusi, merusak prinsip idempotensi.

# ANTI-PATTERN: Mengubah permission file menggunakan shell (selalu mengembalikan status changed)
- name: Change file permission
  shell: chmod 644 /var/www/index.html

# BENAR: Menggunakan modul file bawaan yang menjamin status changed hanya jika ada perubahan nyata
- name: Atur hak akses file index secara aman dan idempoten
  file:
    path: /var/www/index.html
    mode: '0644'
    state: file

2. Menyembunyikan Kegagalan Tanpa Penanganan yang Tepat #

Menggunakan ignore_errors: true secara serampangan untuk menghindari kegagalan build hanya akan menyembunyikan masalah asli yang kelak merusak sistem.

# ANTI-PATTERN: Mengabaikan error pada proses download kritis
- name: Download application binary
  get_url:
    url: "https://example.com/app.tar.gz"
    dest: /tmp/app.tar.gz
  ignore_errors: true

# BENAR: Menangani kegagalan dengan melakukan retry otomatis secara terstruktur
- name: Unduh binary aplikasi dengan toleransi kegagalan jaringan sementara
  get_url:
    url: "https://example.com/app.tar.gz"
    dest: /tmp/app.tar.gz
  register: download_result
  until: download_result is succeeded
  retries: 3
  delay: 10

Ringkasan #

Wajib Profil Production — Kita harus mengaktifkan profile: production pada file .ansible-lint untuk memastikan kepatuhan standar kode terbaik sejak awal pengembangan.

Pre-commit Hooks Sebagai Filter Pertama — Gunakan integrasi pre-commit di komputer lokal kita untuk menyaring kesalahan sintaksis, format file YAML, dan kebocoran rahasia sebelum berhasil dicommit.

Yamllint untuk Kerapian Spasi — Konfigurasikan .yamllint secara konsisten guna meminimalkan perbedaan gaya penulisan spasi dan indentasi antar sesama developer di dalam tim.

Jamin Idempotensi Task — Jangan pernah membiarkan modul command atau shell berjalan tanpa parameter changed_when: false atau creates/removes agar status perubahan selalu akurat.

Gunakan Modul Khusus — Hindari menuliskan command bash manual apabila Ansible telah menyediakan modul khusus (seperti apt, systemd, atau copy) yang teruji stabilitasnya.

Tulis Dokumentasi MENGAPA — Selalu sertakan komentar inline untuk menjelaskan latar belakang keputusan teknis atau pengecualian logika di dalam file konfigurasi kita.

Peta Alur Kualitas di Pipeline — Terapkan verifikasi kualitas kode secara otomatis pada server CI/CD sebelum mengizinkan Pull Request digabungkan ke cabang utama.

← Sebelumnya: Project Structure Berikutnya: Testing Strategy →