325 lines
14 KiB
Markdown
325 lines
14 KiB
Markdown
# 📘 Panduan Integrasi MERICA Standalone dengan Existing Apache Airflow
|
|
|
|
> **Navigasi Cepat**: [🏠 Pusat Dokumentasi](index.md) | [🏛️ Arsitektur Platform](architecture.md) | [📦 Panduan Deployment](deployment_guide.md) | [🎨 Panduan Pengguna Canvas](user_guide.md)
|
|
|
|
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.
|
|
|
|
```mermaid
|
|
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
|
|
|
|
PIPES -.->|"Deploy DAG (Git / YAML)"| AF_DAG_PROC
|
|
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`):
|
|
```yaml
|
|
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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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:
|
|
|
|
```dockerfile
|
|
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
|
|
```bash
|
|
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:
|
|
```yaml
|
|
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`:
|
|
```bash
|
|
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):
|
|
```bash
|
|
# 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`):
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
bash ./setup.sh
|
|
```
|
|
|
|
### Langkah 3: Buka Antarmuka MERICA
|
|
Akses antarmuka web di browser:
|
|
* **URL**: [`http://localhost:14000`](http://localhost:14000)
|
|
* **Username**: `admin`
|
|
* **Password**: `admin`
|
|
|
|
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.
|
|
|
|
```mermaid
|
|
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:
|
|
```bash
|
|
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)*:
|
|
```bash
|
|
# Injeksi ke Scheduler
|
|
docker exec -u airflow <nama_kontainer_scheduler> python -m 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> python -m pip install --no-cache-dir \
|
|
astronomer-cosmos==1.15.1 dlt[duckdb,filesystem]==1.6.1
|
|
|
|
# Injeksi ke Webserver (Konsistensi UI)
|
|
docker exec -u airflow <nama_kontainer_webserver> python -m 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`:
|
|
```yaml
|
|
networks:
|
|
default:
|
|
name: sicabe_default
|
|
external: true
|
|
```
|
|
|
|
#### 4. Contoh Konfigurasi `.env` Riil yang Teruji
|
|
Di direktori hasil clone (misal `~/merica` atau `/home/<user>/merica`), buat berkas `.env` dengan konfigurasi seperti berikut:
|
|
|
|
```bash
|
|
# --- MERICA Appliance ---
|
|
MERICA_IMAGE=registry.sicabe.com/merica:1.0.0
|
|
MERICA_PORT=14000
|
|
ENVIRONMENT=production
|
|
|
|
# --- External Airflow Cluster (Control Host: 100.112.76.124 / Port 12082) ---
|
|
AIRFLOW_WEB_URL=http://100.112.76.124:12082
|
|
AIRFLOW_API_URL=http://100.112.76.124:12082
|
|
AIRFLOW_USERNAME=admin
|
|
AIRFLOW_PASSWORD=1310cc9a318f75cf
|
|
|
|
# --- PostgreSQL MetaDB (Database Host: 100.73.229.107) ---
|
|
POSTGRES_HOST=100.73.229.107
|
|
POSTGRES_PORT=5432
|
|
POSTGRES_DB=airflow
|
|
POSTGRES_USER=airflow
|
|
POSTGRES_PASSWORD=a7bda1593a75d0ff0a8e51002c62c1f3
|
|
|
|
# --- External MinIO S3 (Domain minio-api.sicabe.com / Port 8443) ---
|
|
S3_ENDPOINT_URL=https://minio-api.sicabe.com:8443
|
|
S3_ACCESS_KEY=minioadmin
|
|
S3_SECRET_KEY=942a43b2a0e371545dfa0bff75381d49
|
|
|
|
# --- Pipeline Storage SSOT ---
|
|
PIPELINES_DIR=./pipelines
|
|
```
|
|
|
|
#### 5. Eksekusi & Validasi Konektivitas
|
|
1. Nyalakan kontainer MERICA:
|
|
```bash
|
|
bash ./setup.sh
|
|
# atau: docker compose up -d
|
|
```
|
|
2. Uji endpoint kesehatan:
|
|
```bash
|
|
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
|
|
|
|
* Pahami Rancang Bangun: [🏛️ Arsitektur Platform](architecture.md)
|
|
* Cara Install Appliance: [📦 Panduan Deployment & Build](deployment_guide.md)
|
|
* Panduan Mendesain Pipeline di Canvas: [🎨 Panduan Pengguna Canvas](user_guide.md)
|
|
* Kembali ke Indeks: [🏠 Pusat Dokumentasi](index.md)
|