merica-dlh/merica
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5a137dba42ce36f750622520206ba390977e0094
merica/docs/panduan_integrasi_existing_airflow.md
T

14 KiB
Raw Blame History

📘 Panduan Integrasi MERICA Standalone dengan Existing Apache Airflow

Navigasi Cepat: 🏠 Pusat Dokumentasi | 🏛️ Arsitektur Platform | 📦 Panduan Deployment | 🎨 Panduan Pengguna Canvas

Dokumen panduan ini dirancang khusus bagi Data Engineer, Platform Engineer, dan DevOps yang ingin menginstal MERICA secara mandiri (standalone appliance) dan menghubungkannya ke kluster Apache Airflow yang sudah ada (existing enterprise cluster).

🏛️ 1. Gambaran Umum Arsitektur

MERICA (Managed Engine for Robust Ingestion & Cloud Airflow) berfungsi sebagai Visual Low-Code DAG Builder berbasis web. MERICA tidak mengeksekusi pipeline berat secara langsung; tugas eksekusi, pemantauan, dan retry task sepenuhnya didelegasikan ke kluster Apache Airflow eksternal Anda.

flowchart LR
    subgraph STANDALONE ["MERICA Standalone Host (Port 14000)"]
        UI["ReactFlow Canvas UI"]
        API["FastAPI Backend Gateway"]
        PIPES["Mounted Pipelines SSOT\n(./pipelines/)"]
        UI --- API
        API <--> PIPES
    end

    subgraph AIRFLOW_HOST ["Existing Apache Airflow Cluster"]
        AF_WEBSERVER["Airflow Web UI / API\n(Port 14080 / Domain)"]
        AF_SCHEDULER["Airflow Scheduler & Workers"]
        AF_DAG_PROC["DAG Processor\n(AIP-66 Git DAG Bundles)"]
        AF_SCHEDULER --- AF_DAG_PROC
    end

    STANDALONE -.->|"Deploy DAG (Git / YAML)"| AIRFLOW_HOST
    API -.->|"Direct Link Out"| AF_WEBSERVER

🚀 2. Dua Metode Penyiapan Sisi Existing Airflow

Untuk dapat menjalankan pipeline modern yang dirancang di MERICA (termasuk dbt Medallion, deduplikasi DuckDB, dan Shift-Left Quality Gates), worker dan DAG processor Airflow Anda membutuhkan beberapa pustaka tambahan (seperti astronomer-cosmos dan dbt-postgres).

Pilih salah satu dari 2 Metode berikut sesuai kebijakan infrastruktur Anda:

METODE 1: Modifikasi Langsung Tanpa Build Ulang (Zero-Build / Runtime Injection)

Tip

Gunakan metode ini jika: Anda ingin uji coba cepat, tidak memiliki akses untuk mem-build image di private registry, atau dilarang me-rebuild Dockerfile Airflow existing.

Opsi 1A: Injeksi Runtime Otomatis via _PIP_ADDITIONAL_REQUIREMENTS (Rekomendasi Persisten)

Image resmi Apache Airflow memiliki hook entrypoint otomatis. Pustaka akan terpasang setiap kali kontainer dinyalakan tanpa perlu build Dockerfile:

  1. Buka berkas .env atau docker-compose.yml di server Airflow existing Anda.
  2. Tambahkan variabel lingkungan ini pada service Airflow (airflow-scheduler, airflow-dag-processor, dan airflow-worker): 
    environment:
  _PIP_ADDITIONAL_REQUIREMENTS: "astronomer-cosmos==1.15.1 dbt-postgres==1.11.0 apache-airflow-providers-git==1.0.0 duckdb==1.1.3 pyiceberg[s3fs,pyarrow]==0.8.0"
  3. Restart service Airflow: 
    docker compose restart airflow-scheduler airflow-dag-processor

Opsi 1B: docker exec Langsung ke Kontainer (Aktif dalam 15 Detik Tanpa Restart)

Jika kontainer Airflow sedang running dalam jam kerja dan Anda dilarang me-restart kontainer:

# 1. Install di Scheduler (user airflow)
docker exec -u airflow <container_scheduler> pip install --no-cache-dir \
    astronomer-cosmos==1.15.1 dbt-postgres==1.11.0 apache-airflow-providers-git==1.0.0

# 2. Install di DAG Processor
docker exec -u airflow <container_dag_processor> pip install --no-cache-dir \
    astronomer-cosmos==1.15.1 dbt-postgres==1.11.0 apache-airflow-providers-git==1.0.0

Verifikasi Keberhasilan Instalasi:

docker exec <container_scheduler> python -c "import cosmos; print('✅ Cosmos Version:', cosmos.__version__)"

Bagaimana Menghubungkan DAGs & Custom Operators Tanpa Build Ulang?

Seluruh operator custom (helpers/duckdb_operator.py, helpers/dbt_trino_operator.py, helpers/ge_lakehouse_operator.py, dll.) serta dag_factory.py tidak perlu dibake ke image Airflow. Cukup sambungkan folder dags/ ke Airflow Anda:

  • Via AIP-66 Git DAG Bundles (Airflow 3): Airflow otomatis meng-clone dari repositori merica-pipelines.git.
  • Via Shared Volume Mount: Mount direktori dags/ ke /opt/airflow/dags di kontainer Airflow.

METODE 2: Build Ulang Image Resmi (Official Baked Image)

Important

Gunakan metode ini jika: Server produksi organisasi Anda berada di jaringan terisolasi (air-gapped / tanpa akses internet luar) atau standar DevOps mewajibkan seluruh dependensi paten di dalam image registry resmi.

1. Buat Dockerfile Airflow Resmi

Buat berkas Dockerfile.airflow untuk registry organisasi Anda:

FROM registry.sicabe.com/airflow:3.3.2-om203-ol

LABEL maintainer="BPKP Data Lakehouse Team <dlh@bpkp.go.id>"
LABEL description="Official Airflow 3 Engine Image with Baked MERICA Operators & Cosmos"
LABEL version="3.3.2-merica-v1.1"

USER airflow

# Instalasi dependensi engine MERICA langsung ke layer image
RUN pip install --no-cache-dir \
    astronomer-cosmos==1.15.1 \
    dbt-postgres==1.11.0 \
    apache-airflow-providers-git==1.0.0 \
    duckdb==1.1.3 \
    pyiceberg[s3fs,pyarrow]==0.8.0 \
    pyarrow==17.0.0 \
    s3fs==2024.9.0 \
    fsspec==2024.9.0 \
    dlt[duckdb,filesystem]==1.6.1

# Validasi kompilasi paket di dalam image
RUN python -c "import cosmos; import duckdb; import pyiceberg; print('✅ All MERICA Dependencies Baked!')"

2. Build dan Push ke Private Registry

docker build -t registry.sicabe.com/airflow:3.3.2-merica-v1.1 -f Dockerfile.airflow .
docker push registry.sicabe.com/airflow:3.3.2-merica-v1.1

3. Terapkan Image Baru di Kluster Airflow

Ubah tag image pada deployment Airflow:

image: registry.sicabe.com/airflow:3.3.2-merica-v1.1

Lalu deploy ulang kontainer (docker compose up -d atau kubectl rollout restart deployment airflow).

🎨 3. Starter Seed Pipelines (Jaminan Daftar DAGs Langsung Tersedia)

Kenapa Fitur Ini Ada?

MERICA adalah backend stateless file-based. Jika kontainer berdiri sendiri tanpa mount volume, sistem akan membaca folder kosong sehingga daftar pipeline di halaman web akan kosong (blank), yang sering kali menimbulkan kebingungan bagi pengguna baru.

Cara Kerja Starter Seed Pipelines:

Di dalam paket rilis release/merica/, disediakan direktori ./pipelines/:

  • pipelines/configs/: Menyimpan spesifikasi YAML Airflow (e2e_modernized_ingestion_flow.yaml, e2e_medallion_permits_flow.yaml, e2e_orders_master_medallion_flow.yaml).
  • pipelines/metadata/: Menyimpan data visual layout node & edge ReactFlow (*.json).
  • pipelines/dbt/: Menyimpan model SQL dbt Medallion.

Saat kontainer merica dijalankan via docker compose up -d, direktori ./pipelines ini otomatis di-mount ke /app/merica-pipelines. Begitu browser dibuka di http://localhost:14000, 3 pipeline data lakehouse modern langsung muncul secara visual dan siap dieksplorasi atau diduplikasi!

Cara Mengganti Starter Pipelines dengan Git Organisasi Anda (Opsi GitOps SSOT):

Jika tim Anda menggunakan pendekatan GitOps di mana MERICA dan Airflow 3 tersinkronisasi langsung ke repositori Git yang sama (merica-pipelines.git):

  1. Clone repositori Git di samping folder release/merica: 
    git clone https://repo.sicabe.com/merica-dlh/merica-pipelines.git ../merica-pipelines
  2. Pada berkas .env, aktifkan variabel yang sudah disediakan di template (cukup buka tanda komentar): 
    # Ganti dari ./pipelines ke path clone repositori Git Anda:
PIPELINES_DIR=../merica-pipelines
  3. Parameter referensi Git DAG Bundle di sisi Airflow 3 (AIP-66): 
    GIT_PIPELINE_BUNDLE_NAME=merica-pipeline
GIT_PIPELINE_REPO_URL=https://repo.sicabe.com/merica-dlh/merica-pipelines.git
GIT_PIPELINE_REPO_BRANCH=main
GIT_PIPELINE_REPO_SUBDIR=dags
AIRFLOW_DAG_BUNDLE_REFRESH_INTERVAL=30
  4. Restart MERICA: docker compose up -d. Seluruh pipeline tim Anda akan langsung tersinkronkan secara hot-reload!

⚡ 4. Panduan Operasional Cepat (Runbook 3 Menit)

Langkah 1: Siapkan Konfigurasi Lingkungan

cd release/merica
cp .env.example .env

Sesuaikan parameter AIRFLOW_WEB_URL dan POSTGRES_HOST mengarah ke alamat server Airflow & Database Anda.

Langkah 2: Jalankan Script Setup Sekali Klik

bash ./setup.sh

Langkah 3: Buka Antarmuka MERICA

Akses antarmuka web di browser:

Daftar DAGs Anda akan langsung tampil secara visual dan siap digunakan!

🏢 5. Studi Kasus Implementasi Nyata (Real-World Deployment Walkthrough)

Bagian ini menyajikan contoh implementasi nyata ketika Anda menghubungkan MERICA ke server produksi yang telah menjalankan Apache Airflow dan stack data dengan port kustom (non-standar).

Skenario Lapangan:

Sebuah server telah menjalankan kluster Airflow dan infrastruktur data dengan kondisi:

  • Kontainer Airflow: sicabe-airflow-scheduler, sicabe-airflow-webserver (Port Host 12082:8080), dan sicabe-airflow-dag-processor sudah berstatus Up 7 days (tidak boleh restart lama).
  • Penyimpanan Objek MinIO S3: Port Host 8443.
  • Katalog IAM Keycloak: Port Host 12080.
  • PostgreSQL MetaDB Shared: Berjalan pada host dengan port standar atau custom.
flowchart LR
    subgraph MERICA_CONTAINER ["MERICA Standalone (Port 14000)"]
        UI["Web UI Canvas\n(Port 14000)"]
        BE["FastAPI Engine\n(127.0.0.1:8000)"]
        UI --- BE
    end

    subgraph EXISTING_STACK ["Existing Data Stack (Server SiCABE / Enterprise)"]
        AF_WEB["Airflow Webserver\n(Port Host :12082)"]
        AF_SCHED["Airflow Scheduler\n(Injected Libs)"]
        AF_PROC["DAG Processor\n(Injected Libs)"]
        S3["MinIO S3\n(Port Host :8443)"]
        PG["PostgreSQL MetaDB\n(Port :5432 / Custom)"]
    end

    BE -->|REST API :12082| AF_WEB
    BE -->|Introspection & Safe Preview| PG
    BE -->|Storage Connection| S3
    AF_SCHED -.->|Eksekusi Task Ingestion| S3

Langkah Praktis Penerapan di Server:

1. Inspeksi Kontainer & Port Aktif

Periksa nama kontainer Airflow dan pemetaan port host di server Anda:

docker ps --filter "name=airflow" --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"

Catat nama kontainer scheduler dan dag processor serta port host webserver (misal: 0.0.0.0:12082->8080/tcp).

2. Injeksi Pustaka Engine ke Kontainer Berjalan (Tanpa Restart)

Gunakan docker exec untuk memasang pustaka yang belum ada (astronomer-cosmos dan dlt) langsung ke worker/scheduler tanpa mematikan layanan. (Catatan: Pustaka apache-airflow-providers-git, dbt-postgres, duckdb, pyiceberg, dan sling sudah tersedia bawaan (built-in) di image resmi):

# Injeksi ke Scheduler
docker exec -u airflow <nama_kontainer_scheduler> pip install --no-cache-dir \
  astronomer-cosmos==1.15.1 dlt[duckdb,filesystem]==1.6.1

# Injeksi ke DAG Processor
docker exec -u airflow <nama_kontainer_dag_processor> pip install --no-cache-dir \
  astronomer-cosmos==1.15.1 dlt[duckdb,filesystem]==1.6.1

# Verifikasi instalasi berhasil
docker exec <nama_kontainer_scheduler> python -c "import cosmos, duckdb, pyiceberg; print('✅ Airflow Engine Ready!')"

3. Penanganan Komunikasi Jaringan (Docker Networking)

Tentukan bagaimana kontainer MERICA berkomunikasi dengan layanan existing:

  • Kasus A — Satu Mesin (Single-Host): Gunakan host.docker.internal (didukung di Linux via extra_hosts pada compose) atau gunakan IP gateway Docker host (umumnya 172.17.0.1).
  • Kasus B — Beda Server (Multi-Node): Ganti host.docker.internal dengan IP private / LAN server Airflow Anda (contoh: http://192.168.10.50:12082).
  • Kasus C — Shared Docker Network: Jika ingin menggunakan nama kontainer langsung (contoh: http://sicabe-airflow-webserver:8080), hubungkan kontainer MERICA ke network yang sama dengan Airflow melalui docker-compose.yml: 
    networks:
  default:
    name: sicabe_default
    external: true

4. Contoh Konfigurasi .env Riil yang Teruji

Di direktori /opt/merica, buat berkas .env dengan konfigurasi seperti berikut:

# --- MERICA Appliance ---
MERICA_IMAGE=registry.sicabe.com/merica:1.0.0
MERICA_PORT=14000
ENVIRONMENT=production

# --- External Airflow Cluster (Port Kustom 12082) ---
AIRFLOW_WEB_URL=http://host.docker.internal:12082
AIRFLOW_API_URL=http://host.docker.internal:12082
AIRFLOW_USERNAME=admin
AIRFLOW_PASSWORD=1310cc9a318f75cf

# --- PostgreSQL MetaDB (Introspection & Preview) ---
POSTGRES_HOST=host.docker.internal
POSTGRES_PORT=5432
POSTGRES_DB=airflow
POSTGRES_USER=airflow
POSTGRES_PASSWORD=a7bda1593a75d0ff0a8e51002c62c1f3

# --- External MinIO S3 (Port Kustom 8443) ---
S3_ENDPOINT_URL=http://host.docker.internal:8443
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=942a43b2a0e371545dfa0bff75381d49

# --- Pipeline Storage SSOT ---
PIPELINES_DIR=./pipelines

5. Eksekusi & Validasi Konektivitas

  1. Nyalakan kontainer MERICA: 
    bash ./setup.sh
# atau: docker compose up -d
  2. Uji endpoint kesehatan: 
    curl -s http://localhost:14000/api/v1/health | jq .
  3. Akses antarmuka web MERICA di browser: http://<ip-server>:14000.
  4. Anda dapat langsung menguji fitur Database Introspection & Safe Preview yang terhubung ke PostgreSQL, serta melihat tautan langsung ke Airflow Webserver di port 12082.

🧭 Navigasi Dokumen Terkait

Reference in New Issue View Git Blame Copy Permalink