Sidecar

Sidecar adalah komponen pelengkap dari DataFlux Func.

Karena DataFlux Func biasanya berjalan di dalam container, perintah Shell tidak dapat langsung dieksekusi di host. Sidecar adalah program yang berjalan di host dan, sebagai proxy DataFlux Func, mengeksekusi perintah Shell langsung di host.

Perintah Unduh

bash -c "$(curl -fsSL docs.dataflux-func.com/sidecar-download)"

0. Catatan Sebelum Membaca

Fitur ini memerlukan hak akses root

Semua perintah shell yang dibahas dalam dokumen ini dapat langsung dijalankan oleh pengguna root; pengguna non-root perlu menambahkan sudo saat menjalankannya.

1. Persyaratan Sistem dan Lingkungan

Host yang dapat menjalankan DataFlux Func biasanya juga dapat menjalankan Sidecar.

1.1 Persyaratan Versi DataFlux Func

Sidecar harus digunakan bersama DataFlux Func 1.3.5 dan versi yang lebih tinggi

2. Instalasi Cepat

Dalam keadaan normal, Sidecar akan diinstal pada host yang sama dengan DataFlux Func. Operasi berikut diasumsikan dilakukan pada host yang telah menginstal DataFlux Func.

Jika Sidecar dan DataFlux Func berjalan di host yang berbeda, konfigurasi terkait perlu diubah

2.1 Instalasi Offline

Sebelum menginstal Sidecar, Anda perlu mengunduh sumber daya yang diperlukan.

Untuk host di lingkungan tanpa jaringan publik, Anda dapat menyalin file ke host melalui perangkat portabel seperti USB flash drive.

File sumber daya yang diunduh sudah disertai skrip instalasi otomatis; cukup jalankan untuk melakukan instalasi (lihat detail di bawah).

2.1.1 Unduh Berkas Sumber Daya dengan Satu Perintah

Untuk sistem seperti Linux, macOS, disarankan menggunakan perintah shell resmi untuk mengunduh paket instalasi.

Jalankan perintah berikut untuk otomatis mengunduh file yang diperlukan Sidecar. Skrip pengunduh akan otomatis memilih versi arsitektur x86_64 atau aarch64 berdasarkan lingkungan saat ini:

bash -c "$(curl -fsSL docs.dataflux-func.com/sidecar-download)"

Jika perlu mengunduh versi dengan arsitektur tertentu, Anda dapat menggunakan perintah berikut untuk mengunduhnya:

• Prosesor Intel x86_64

bash -c "$(curl -fsSL docs.dataflux-func.com/sidecar-download)" -- --arch=x86_64

• Prosesor ARM aarch64 (yaitu ARM64v8, seperti Raspberry Pi, dll.)

bash -c "$(curl -fsSL docs.dataflux-func.com/sidecar-download)" -- --arch=aarch64

Setelah perintah selesai dijalankan, semua file yang diperlukan akan disimpan dalam direktori dataflux-func-sidecar yang baru dibuat di direktori saat ini.

• Jika Sidecar perlu diinstal ke server tanpa jaringan publik, Anda dapat mengunduhnya terlebih dahulu di mesin lokal, lalu menyalin seluruh direktori ke mesin target menggunakan perangkat penyimpanan portabel seperti USB flash drive, atau alat seperti scp.
• Jika Sidecar perlu diinstal ke server yang dapat mengakses jaringan publik, cukup unduh langsung di server tersebut.

2.1.2 Unduh Berkas Sumber Daya Secara Manual

Untuk sistem yang tidak mudah menggunakan perintah shell, file sumber daya yang diperlukan dapat diunduh secara manual.

Jika perlu mengunduh secara manual, berikut adalah daftar semua file:

#	Konten	Nama File	Arsitektur x86_64	Arsitektur aarch64
1	Program biner Sidecar	dataflux-func-sidecar.tar.gz	Unduh	Unduh
2	File konfigurasi layanan Sidecar	dataflux-func-sidecar.service	Unduh	Unduh
3	Skrip instalasi Sidecar	run-sidecar.sh	Unduh	Unduh
4	Informasi versi	version	Unduh	Unduh

Setelah semua file diunduh secara manual, cukup letakkan ke dalam direktori dataflux-func-sidecar yang baru dibuat.

Jika ada pembaruan, Anda harus mengunduh ulang semua file. Jangan menebak sendiri file mana yang berubah dan mana yang tidak

Saat mengunduh secara manual, misalnya menggunakan browser, perhatikan agar tidak mengunduh konten lama dari cache!!

2.1.3 Melakukan Instalasi Menggunakan Skrip yang Disertakan

Di direktori dataflux-func-sidecar yang telah diunduh, jalankan perintah berikut untuk otomatis mengonfigurasi dan memulai seluruh Sidecar:

Sidecar tidak mendukung Mac, salin ke sistem Linux terlebih dahulu lalu jalankan instalasi

sudo bash run-sidecar.sh

Dengan menggunakan skrip instalasi otomatis, Anda dapat menginstal dan menjalankannya dengan cepat dalam hitungan detik. Konten yang dikonfigurasi otomatis adalah sebagai berikut:

• Membuat file yang dapat dieksekusi /usr/local/bin/dataflux-func-sidecar
• Membuat file konfigurasi /etc/dataflux-func-sidecar
• Membuat pengguna dffs untuk menjalankan program Sidecar
• Membuat file konfigurasi Systemd /etc/systemd/system/dataflux-func-sidecar dan menyetelnya agar mulai otomatis saat boot

Setelah instalasi selesai, informasi instalasi berikut akan ditampilkan:

Bind:
    127.0.0.1:8099,172.17.0.1:8099
Secret Key:
    xxxxxxxxxxxxxxxx
To shutdown:
    sudo systemctl start dataflux-func-sidecar
To start:
    sudo systemctl stop dataflux-func-sidecar

Now open 127.0.0.1:8099,172.17.0.1:8099 and have fun!

Arti dari konten keluaran adalah sebagai berikut:

Item	Keterangan	Item File Konfigurasi Terkait
Bind	Alamat listen. Mendukung banyak alamat, dipisahkan dengan koma bahasa Inggris	BIND
Secret Key	Kunci rahasia. Digunakan untuk memverifikasi permintaan	SECRET_KEY

Dalam hal instalasi default, Bind akan memiliki 2 alamat:

• 127.0.0.1:8099: jaringan lokal
• 172.17.0.1:8099: docker0, digunakan untuk berkomunikasi dengan DataFlux Func

2.2. Verifikasi Instalasi

Setelah instalasi default Sidecar selesai, Anda dapat memverifikasi instalasi dengan perintah berikut:

curl http://127.0.0.1:8099

Jika informasi berikut dikembalikan, maka Sidecar berjalan normal:

Welcome to DataFlux Func Sidecar
* Version: 0.0.1
* Release Date: 2021-10-17 00:00:00

2.3. Opsi Instalasi

Skrip instalasi otomatis mendukung beberapa opsi instalasi untuk menyesuaikan dengan kebutuhan instalasi yang berbeda.

Saat instalasi, cukup tambahkan --{parameter}[ konfigurasi parameter (jika ada)] setelah perintah instalasi otomatis untuk menentukan opsi instalasi

Misalnya, untuk menentukan alamat listen:

sudo bash run-sidecar.sh --bind 0.0.0.0.8099

2.3.1 Opsi Instalasi yang Tersedia

Detail parameter selengkapnya lihat di bawah ini.

--bind: Menentukan alamat listen

Secara default, Sidecar mendengarkan di 127.0.0.1:8099,172.17.0.1:8099. Jika port sudah digunakan, Anda dapat memilih alamat listen yang lain.

--secret-key: Menentukan Secret Key

Pada instalasi default, DataFlux Func Sidecar akan otomatis menghasilkan Secret Key acak. Anda dapat menggunakan parameter ini untuk menentukan Secret Key secara manual.

3. Memanggil Sidecar di DataFlux Func

Di DataFlux Func tersedia Konektor DataFlux Func Sidecar yang dapat digunakan untuk mengoperasikan Sidecar.

3.1. Membuat Konektor Sidecar

Buka "Konektor / Tambah Konektor / DataFlux Func Sidecar (HTTP)", isi Secret Key dengan benar, lalu buat.

Jika Anda menentukan alamat listen yang berbeda saat menginstal Sidecar (mengubah parameter Bind), maka saat membuat Konektor juga perlu disesuaikan.

3.2. Menulis Kode

Berikut adalah contoh kode:

import json

@DFF.API('Test Sidecar')
def test_sidecar():
    sidecar = DFF.CONN('sidecar')
    res = sidecar.shell('hostname', wait=True, callback_url='http://172.17.0.1:8088/api/v1/sync/sidecar-callback')
    # Isi res:
    # (200, {'data': {'stderr': '', 'stdout': 'my_host\n'}, 'message': '', 'ok': True})
    return res

@DFF.API('Test Sidecar callback')
def test_sidecar_callback(**kwargs):
    # Isi kwargs:
    # {'stdout': 'my_host\n', 'stderr': ''}
    print(kwargs['stdout'])
    print(kwargs['stderr'])

3.3. Mengonfigurasi Fungsi

Pada contoh kode di atas:

Fungsi eksekusi utama adalah "Test Sidecar", yang dapat dikonfigurasi sebagai "API Fungsi" atau "Tugas Terjadwal" untuk dieksekusi.

"Test Sidecar callback" adalah fungsi yang menerima callback setelah eksekusi, dan perlu dikonfigurasi sebagai "API Fungsi"

Dalam contoh kode, bagian ID alamat API Fungsi pada parameter callback_url adalah sidecar-callback, jadi saat mengonfigurasi API Fungsi untuk fungsi callback, tentukan juga ID yang sama untuk memastikan alamat URL konsisten

Untuk kasus di mana Sidecar dan DataFlux Func diinstal pada host yang sama, keduanya dapat saling mengakses melalui docker0, yaitu alamat IP 172.17.0.1

Untuk detail tentang "Objek Operasi Konektor Sidecar", lihat di bawah ini.

4. API Objek Operasi Konektor Sidecar

Dengan menggunakan objek operasi Konektor Sidecar, pengguna dapat memanggil Sidecar untuk mengeksekusi perintah Shell.

Parameter DFF.CONN(...) adalah sebagai berikut:

Parameter	Tipe	Wajib / Nilai Default	Deskripsi
data_source_id	str	Wajib	ID Konektor

SidecarHelper.shell(...)

Memanggil Sidecar untuk mengeksekusi perintah Shell, parameter sebagai berikut:

Parameter	Tipe	Wajib / Nilai Default	Deskripsi
cmd	str	Wajib	Perintah Shell yang akan dieksekusi Contoh: "ls -l"
wait	bool	True	Apakah menunggu hingga eksekusi selesai Jika diatur ke False, fungsi ini akan segera kembali dan tidak akan mengembalikan output terminal
workdir	str	None	Direktori kerja untuk eksekusi perintah Shell Contoh: "/home/dev"
envs	dict	None	Variabel lingkungan, kunci dan nilai semuanya berupa string Contoh: {"MY_NAME": "Tom"}
callback_url	str	None	Alamat callback. Setelah perintah dieksekusi, stdout dan stderr akan dikirim ke URL yang ditentukan menggunakan metode POST Biasanya digunakan bersama parameter wait=False untuk mewujudkan callback asinkron
timeout	int	3	Waktu tunggu permintaan Catatan: parameter ini bukan waktu tunggu perintah Shell, melainkan waktu tunggu permintaan Func ke Sidecar Artinya, permintaan Func ke Sidecar mungkin mengalami timeout, tetapi perintah Shell yang dieksekusi tidak akan berhenti karenanya

Callback Setelah Eksekusi

Setelah memanggil SidecarHelper.shell(...) dan menentukan parameter callback_url, Sidecar akan mengirimkan output standar stdout dan error standar stderr ke alamat tersebut menggunakan metode POST setelah selesai mengeksekusi perintah Shell.

Struktur spesifiknya adalah sebagai berikut:

POST {callback_url}
Content-Type: application/json

{
  "kwargs": {
    "stdout": "<teks output standar>",
    "stderr": "<teks error standar>"
  }
}

Struktur ini cocok dengan metode POST standar dari "API Fungsi" DataFlux Func, sehingga Anda dapat langsung menggunakan "API Fungsi" untuk menerima callback setelah eksekusi

5. Perawatan Rutin

Secara default, lokasi pemasangan program yang dapat dieksekusi adalah /usr/local/bin/dataflux-func-sidecar

5.1 Memutakhirkan Sistem

Cukup jalankan kembali proses instalasi; Skrip instalasi otomatis akan mengganti program yang dapat dieksekusi dan me-restart layanan.

Selain itu, isi file konfigurasi sebelumnya akan dipertahankan.

5.2 Memulai/Menutup/Merestart Layanan

Layanan Sidecar dikelola menggunakan systemd, cukup gunakan systemctl untuk mengoperasikannya:

sudo systemctl start dataflux-func-sidecar    # Memulai
sudo systemctl stop dataflux-func-sidecar     # Menghentikan
sudo systemctl restart dataflux-func-sidecar  # Merestart

5.3 Melihat Konfigurasi

File konfigurasi terletak di /etc/dataflux-func-sidecar.

6. Penghapusan Instalasi

Jalankan perintah-perintah berikut secara berurutan:

sudo systemctl disable --now dataflux-func-sidecar.service   # Menghentikan layanan Sidecar dan menonaktifkan startup otomatis saat boot
sudo rm -f /etc/systemd/system/dataflux-func-sidecar.service # Menghapus konfigurasi layanan systemd Sidecar
sudo systemctl daemon-reload                                 # Memuat ulang konfigurasi systemd agar penghapusan layanan berlaku
sudo rm -f /usr/local/bin/dataflux-func-sidecar              # Menghapus file eksekusi Sidecar
sudo rm -f /etc/dataflux-func-sidecar                        # Menghapus file konfigurasi yang berisi BIND dan SECRET_KEY
sudo userdel dffs                                            # Menghapus pengguna sistem Sidecar yang dibuat saat instalasi

6.1 Verifikasi

systemctl status dataflux-func-sidecar.service                      # Memeriksa apakah layanan sudah dihapus; saat penghapusan berhasil, seharusnya muncul pesan bahwa layanan tidak ditemukan
test ! -e /usr/local/bin/dataflux-func-sidecar && echo "Program telah dihapus" # Memastikan file eksekusi sudah dihapus
test ! -e /etc/dataflux-func-sidecar && echo "Konfigurasi telah dihapus"       # Memastikan file konfigurasi sudah dihapus
getent passwd dffs || echo "Pengguna telah dihapus"                             # Memastikan pengguna dffs sudah tidak ada

/etc/dataflux-func-sidecar berisi BIND dan SECRET_KEY. Jika Anda ingin mempertahankan konfigurasi untuk instalasi ulang, cadangkan file tersebut sebelum penghapusan instalasi.

Jika pengguna dffs masih digunakan oleh program lain, jangan jalankan sudo userdel dffs.

7. Catatan Keamanan

Karena pola penggunaan Sidecar pada dasarnya adalah mengirimkan kode yang dapat dieksekusi secara arbitrer ke host tempatnya berjalan, hal ini bersifat berbahaya.

Oleh karena itu, Sidecar memiliki batasan-batasan berikut dalam implementasi dan penerapannya:

1. Layanan Sidecar berjalan sebagai pengguna dffs (yaitu singkatan dari DataFlux Func Sidecar)
2. Sidecar harus dikonfigurasi dengan SecretKey agar dapat memanggil dan mengeksekusi perintah Shell secara normal.
3. SidecarHelper.shell(...) secara internal mengimplementasikan tanda tangan HmacSha1 untuk mencegah manipulasi dan serangan replay.

Karena layanan Sidecar berjalan sebagai pengguna dffs, layanan ini tidak dapat menjalankan perintah yang memerlukan hak akses root atau mengakses file milik pengguna lain. Jika diperlukan, pengguna dffs dapat ditambahkan ke dalam grup pengguna, atau izin terkait file dapat diubah.