Halaman ini memberikan tips untuk menulis plugin Service Extensions yang benar, berperforma baik, dan terisolasi dengan baik. Koreksi sangat penting karena plugin berjalan di sandbox mesin yang dibatasi dengan platform API terbatas. Performa sangat penting karena plugin berjalan selama permintaan pengguna akhir, dengan sejumlah kecil resource. Isolasi disediakan di tingkat project.
Memulai
Mulai dari contoh
Gunakan API yang didukung
Jalankan pengujian fungsional dan tolok ukur
Mulai dari contoh
Cara yang baik untuk memulai adalah dengan menjelajahi contoh kode plugin kami. Berikut adalah contoh pola plugin umum, seperti parsing jalur atau kueri, penulisan ulang header, logging kustom, dan autentikasi kustom.
Menggunakan API yang didukung
Plugin harus dikompilasi terhadap antarmuka biner (ABI) Proxy-Wasm. Ekstensi Layanan mendukung subset ABI Proxy-Wasm
yang mencakup mutasi header dan isi HTTP, respons lokal, logging kustom,
dan konfigurasi plugin. Proxy-Wasm juga mendukung subset kecil
WASI preview 1,
termasuk stdout dan stderr untuk logging, clock_time_get dan random_get.
Service Extensions tidak mendukung timer, metrik kustom, data bersama, antrean bersama, atau panggilan jaringan keluar. Ekstensi Layanan juga tidak mendukung nilai yang ditampilkan callback plugin yang mencoba menjeda pemrosesan permintaan, dan mengabaikannya.
Menjalankan pengujian fungsional dan tolok ukur
Untuk mengevaluasi kebenaran dan performa, kami menyediakan alat penguji plugin lokal yang dapat menjalankan, menguji, dan mengukur performa plugin Anda. Anda memanggil alat ini di container Docker, dengan meneruskan biner plugin dan proto teks input dan ekspektasi. Lihat dokumentasi penguji lokal dan contoh input pengujian.
Ketepatan
Jangan mengandalkan jam
Untuk alasan keamanan, waktu jam ditetapkan saat pembuatan konteks (untuk plugin atau permintaan) dan tetap tidak berubah selama pemanggilan plugin. Artinya, plugin WebAssembly tidak boleh tidur; waktu tidur akan habis karena waktu tidak bertambah. Hal ini juga berarti plugin tidak dapat mengukur waktu eksekusinya sendiri, meskipun informasi ini tersedia di Cloud Monitoring.
Perlakukan nama header sebagai tidak peka huruf besar/kecil
Menurut semantik HTTP, nama kolom header HTTP harus diperlakukan sebagai tidak peka huruf besar/kecil. Huruf kapital di header yang ditulis oleh plugin dapat diubah sebelum dikirim ke klien atau backend.
Performa
Hindari error plugin
Kompilasi untuk kecepatan eksekusi
Mengompilasi ekspresi reguler sebelumnya
Hindari penyalinan data ke dalam konteks HTTP
Menghindari tabrakan plugin
Saat plugin mengalami error, permintaan pemicu akan menerima error. Jika hal ini sering terjadi, mulai ulang plugin akan dibatasi, yang menyebabkan error beruntun yang memengaruhi beberapa pengguna.
Untuk menghindari error plugin, coba lakukan hal berikut:
- Hindari pernyataan dalam bentuk apa pun. Sebagai gantinya, konfigurasikan logging error atau respons lokal kepada pengguna.
- Di Rust, hindari penggunaan metode, seperti
unwrap, yang dapat menyebabkan panik. Selain itu, Anda dapat mengonfigurasi plugin untuk menangani error dengan menggunakanpanic::set_hook. - Uji plugin Anda menggunakan penguji plugin yang disediakan Google dan pastikan input yang salah format atau kosong ditangani tanpa menyebabkan plugin error.
Mengompilasi untuk kecepatan eksekusi
Kompilasi kode WebAssembly Anda untuk mencapai kecepatan eksekusi terbaik dengan menggunakan
opsi build -O3 (untuk C++) atau opt-level=3 (untuk Rust).
Mengompilasi ekspresi reguler sebelumnya
Hindari operasi berat komputasi di jalur per permintaan (di handler HTTP). Sebagai gantinya, lakukan pekerjaan yang tidak spesifik per permintaan pada waktu konfigurasi plugin, dan teruskan status yang telah dihitung sebelumnya ke setiap konteks permintaan HTTP (juga dikenal sebagai konteks streaming).
Khususnya, lakukan prakompilasi ekspresi reguler apa pun pada waktu konfigurasi plugin. Contoh kode regex kami menunjukkan cara melakukannya.
Menghindari penyalinan data ke dalam konteks HTTP
Saat membagikan data antara konteks root dan konteks HTTP, hindari panggilan salinan atau clone yang mahal. Sebagai gantinya, bagikan penunjuk atau referensi. Di C++, hal ini dapat dilakukan dengan std::shared_ptr atau pointer dan referensi mentah karena konteks root lebih lama dari konteks HTTP. Di Rust, nilai dapat dibagikan menggunakan
std::rc::Rc. Di Go, nilai dapat dibagikan dengan menyimpan pointer ke nilai,
yang dihapus oleh pengumpul sampah.
Keamanan
Mengisolasi workload menurut project
Di infrastruktur Google, plugin yang dimiliki oleh project yang sama dapat berjalan di sandbox aman yang sama. Google Cloud Artinya, runtime WebAssembly adalah satu-satunya penghalang keamanan antara plugin dalam project yang sama.
Gunakan project Google Cloud terpisah untuk workload yang memerlukan pemisahan keamanan. Praktik ini juga memberikan pemisahan resource dan izin.
Membatasi secret di Media CDN
Secara desain, Media CDN berjalan di sejumlah hardware yang dioperasikan di luar kontrol fisik Google. Saat menulis plugin terkait keamanan untuk Media CDN, gunakan nama host atau subdomain khusus, dan konfigurasi plugin dengan kunci penandatanganan yang sering diubah.