On-Premise Data Gateway

On-premise gateway memungkinkan SQL Database Reader meng-query database Anda tanpa membuka port database ke internet, dan tanpa Qlar menyimpan kredensial database Anda.

Anda menjalankan sebuah program open-source kecil di dekat database Anda. Program ini melakukan panggilan HTTPS keluar (outbound) ke Qlar untuk menanyakan apakah ada query yang perlu dijalankan, menjalankannya secara read-only, lalu mengirimkan baris hasilnya kembali. Tidak ada yang terhubung masuk.

Direct connection vs. on-premise gateway

Anda memilih salah satunya di langkah pertama penyiapan plugin. Keduanya menjawab pertanyaan yang sama dengan data yang sama; perbedaannya ada pada apa yang harus diizinkan jaringan Anda dan apa yang akhirnya dipegang oleh Qlar.

Pilih gateway ketika tim keamanan Anda tidak akan membuka port database, atau ketika keberatannya adalah kredensial yang keluar dari lingkungan Anda. Pilih direct ketika keduanya bukan masalah, karena komponennya lebih sedikit.

Apa yang dilindungi gateway, dan apa yang tidak

Hal ini perlu dijelaskan dengan tepat, karena kontrol yang dilebih-lebihkan lebih buruk daripada tidak ada kontrol sama sekali.

Gateway melindungi:

• Paparan jaringan. Tidak ada aturan inbound, tidak ada socket yang mendengarkan, tidak ada milik Anda yang dapat dijangkau dari internet.
• Kredensial Anda. Kredensial hanya ada di file konfigurasi gateway itu sendiri. Qlar tidak pernah menerimanya dan tidak punya cara untuk membacanya.
• Apa yang boleh dieksekusi. Gateway mem-parse setiap statement dan hanya menerima tepat satu operasi baca, menolak celah akses ke file, shell, dan jaringan yang disediakan dialek database-nya, serta menjalankan semuanya dalam transaksi read-only yang ditegakkan oleh database Anda.
• Visibilitas. Setiap statement ditulis ke audit log lokal beserta agent, user, dan conversation yang memicunya. File itu milik Anda dan tidak ada apa pun dalam protokol yang bisa mematikannya.

Gateway tidak melindungi:

• Hasil query tetap sampai ke Qlar dan model AI. Memang itulah tujuan fitur ini. Kolom yang sama sekali tidak boleh keluar dari lingkungan Anda sebaiknya tidak dimasukkan ke allow-list.
• Apa pun yang boleh dibaca oleh gateway yang sudah disetujui, seandainya Qlar sendiri disusupi. Allow-list Anda membatasi hal itu; audit log Anda mengungkapnya.
• Akses ke mesin. Siapa pun yang bisa membaca .env milik gateway memiliki kredensial database Anda, persis seperti konfigurasi aplikasi lainnya.

Sebelum memulai

• Sebuah mesin di jaringan Anda yang bisa menjangkau database dan melakukan panggilan HTTPS keluar.
• Docker, atau Python 3.11+.
• Akun database dengan izin SELECT pada tabel-tabel yang dibutuhkan agent, dan tidak lebih dari itu. Gateway selalu membuka transaksi read-only, tetapi akun read-only adalah jaminan yang tidak bergantung pada kebenaran perangkat lunak.

Menyiapkannya

1. Pilih gateway

Di penyiapan plugin, pada How should Qlar reach your database?, pilih On-premise gateway. Langkah Connection diganti dengan langkah Gateway, yang tidak pernah meminta host, username, atau password.

2. Dapatkan kode enrolment sekali pakai

Klik Connect a new gateway. Qlar menampilkan sebuah kode seperti K7P4-9WQX-2MTD, beserta perintah yang perlu dijalankan, termasuk dua baris yang memberi tahu gateway ke mana kode itu harus dikirim.

Kode ini sekali pakai dan kedaluwarsa setelah 15 menit. Qlar hanya menyimpan hash-nya, sehingga kode tidak bisa ditampilkan lagi; salin kode sebelum Anda meninggalkan halaman. Jika kode hilang, buat yang baru.

3. Pasang dan konfigurasikan

Unduh gateway dari github.com/pusakaai/data-gateway dan buat file .env di sebelahnya:

# Both of these come from the panel that showed you the code. QLAR_BASE_URL is the API
# endpoint, which is not the address of the Qlar web interface: that one serves a website,
# and a gateway pointed at it fails to enrol.
QLAR_BASE_URL=https://your-qlar-endpoint/api/data-gateway
QLAR_ENROLLMENT_CODE=K7P4-9WQX-2MTD

DB_PROVIDER=postgresql
DB_HOST=db.internal
DB_PORT=5432
DB_NAME=warehouse
DB_USER=qlar_readonly
DB_PASSWORD=...

Periksa database terlebih dahulu sebelum melibatkan Qlar sama sekali:

docker run --rm --env-file .env -v "$PWD/state:/state" \
  ghcr.io/pusakaai/data-gateway:0.2.0 test-db

4. Jalankan

Cukup satu perintah. enroll mendaftarkan mesin ini, menunggu persetujuan, lalu mulai melayani query; tidak ada yang perlu Anda jalankan lagi setelahnya.

docker run -d --name qlar-gateway --restart unless-stopped \
  --env-file .env -v "$PWD/state:/state" \
  ghcr.io/pusakaai/data-gateway:0.2.0 enroll

docker logs -f qlar-gateway

Gateway membuat key pair-nya sendiri (bagian privatnya ditulis ke gateway-key.pem dan tidak pernah meninggalkan mesin Anda), hanya mendaftarkan bagian publiknya, lalu mencetak fingerprint ke log:

3A:7F:19:C4:...:C2

enrolled, waiting for approval in Qlar. Compare the key fingerprint above with the one
the CMS shows and click Approve; this starts working on its own, nothing else to run here.

Menghentikan docker logs tidak menghentikan gateway, dan menjalankan baris docker run yang sama lagi setelah restart akan memakai ulang enrolment yang sudah dimilikinya, alih-alih mencoba menukarkan kode yang sudah terpakai pada kali pertama.

5. Setujui fingerprint

Qlar kini menampilkan sebuah kartu berisi hostname yang mendaftar dan fingerprint yang sama. Bandingkan kedua string itu karakter demi karakter, dan setujui hanya jika keduanya cocok.

Inilah langkah yang paling penting. Enrolment sendiri tidak memberikan akses apa pun: sampai ada orang yang menyetujui fingerprint, gateway sama sekali tidak menerima query. Inilah yang membuat kode enrolment yang bocor menjadi tidak berguna, karena siapa pun yang mencurinya juga harus membuat Anda menyetujui fingerprint yang belum pernah Anda lihat.

Jika fingerprint tidak cocok dengan yang dicetak mesin Anda, jangan setujui. Batalkan dan buat kode baru.

Tidak ada langkah 6. Dalam beberapa detik setelah Anda mengklik, log menampilkan approved. Serving queries for ..., gateway tampil online di Qlar, dan Anda melanjutkan ke mengonfigurasi tabel dan kolom persis seperti pada direct connection.

Perhatikan bahwa tidak ada perintah di halaman ini yang membuka (publish) port. Memang itulah intinya.

Pengamanan tambahan (disarankan)

Atur TABLE_ALLOWLIST di .env milik gateway dengan tabel-tabel yang boleh dibaca agent:

TABLE_ALLOWLIST=public.shipment_order,public.hub,public.customer

Daftar ini berada di lingkungan Anda sendiri, sehingga tidak ada perubahan di sisi Qlar yang bisa memperluasnya. Query yang menyentuh tabel lain ditolak sebelum sampai ke database, dan penolakannya dicatat di audit log Anda.

Mengoperasikannya

Backup gateway-key.pem. File itu adalah identitas gateway.

Me-restart Qlar tidak memutus apa pun: tidak ada sesi yang bisa hilang. Poll yang gagal cukup dicoba ulang, dan enrolment serta persetujuan disimpan di sisi server.

Troubleshooting

Panduan instalasi milik gateway membahas systemd dan Kubernetes, dan spesifikasi protokol mendokumentasikan kontrak komunikasinya secara lengkap. Spesifikasi ini dipublikasikan agar Anda bisa mengauditnya, atau menulis gateway sendiri dalam bahasa pemrograman lain.

Halaman Terkait

• Setup Connection
• Configure Tables and Columns
• Usage Logs
• Overview SQL Database Reader