Kontrak runtime container

Halaman ini berisi daftar persyaratan dan perilaku utama container di Cloud Run. Ada beberapa perbedaan antara layanan Cloud Run dan tugas Cloud Run: hal ini disebutkan jika diperlukan.

Bahasa dan gambar yang didukung

Image container Anda dapat menjalankan kode yang ditulis dalam bahasa pemrograman pilihan Anda dan menggunakan image dasar apa pun, asalkan image tersebut mematuhi batasan yang tercantum di halaman ini.

File yang dapat dieksekusi di image container harus dikompilasi untuk Linux 64-bit. Cloud Run secara khusus mendukung format ABI x86_64 Linux.

Cloud Run menerima image container di format gambar Docker Image Manifest V2, Schema 1, Schema 2, dan OCI.

Jika men-deploy image multiarsitektur, daftar manifes harus menyertakan linux/amd64.

Memproses permintaan pada port yang benar (layanan)

Layanan Cloud Run memulai instance Cloud Run untuk menangani permintaan yang masuk. Instance Cloud Run selalu memiliki satu container masuk, dan memiliki satu atau beberapa container file bantuan opsional. Detail konfigurasi port berikut hanya berlaku untuk container masuk, bukan untuk file bantuan.

Container ingress dalam sebuah instance harus memproses permintaan pada 0.0.0.0 di port tujuan pengiriman permintaan. Secara default, permintaan akan dikirim ke 8080, tetapi Anda dapat mengonfigurasi Cloud Run untuk mengirim permintaan ke port pilihan Anda. Cloud Run memasukkan variabel lingkungan PORT ke dalam container masuk.

Container yang berjalan dalam eksekusi tugas harus keluar setelah selesai

Untuk tugas Cloud Run, container harus keluar dengan kode keluar 0 saat tugas berhasil diselesaikan, dan keluar dengan kode keluar bukan nol saat tugas gagal.

Karena tugas tidak boleh melayani permintaan, container tidak boleh memproses port atau memulai server web.

Enkripsi lapisan transpor (TLS)

Container tidak boleh menerapkan keamanan lapisan transport secara langsung. TLS dihentikan oleh Cloud Run untuk HTTPS dan gRPC, lalu permintaan akan di-proxy-kan sebagai HTTP/1 atau gRPC ke container tanpa TLS.

Jika Anda mengonfigurasi layanan Cloud Run untuk menggunakan HTTP/2 secara menyeluruh, container Anda harus menangani permintaan dalam format cleartext (h2c) HTTP/2, karena TLS masih dihentikan secara otomatis oleh Cloud Run.

Respons (layanan)

Untuk layanan Cloud Run, container Anda harus mengirim respons dalam waktu yang ditentukan di setelan waktu tunggu permintaan setelah menerima permintaan, termasuk waktu startup container. Jika tidak, permintaan akan berakhir dan error 504 akan ditampilkan.

Variabel lingkungan

Berbagai variabel lingkungan tersedia untuk layanan dan tugas Cloud Run.

Variabel lingkungan untuk layanan

Variabel lingkungan berikut akan otomatis ditambahkan ke semua container yang berjalan, kecuali PORT. Variabel PORT hanya ditambahkan ke container masuk:

Nama	Deskripsi	Contoh
`PORT`	Port yang akan diproses oleh server HTTP Anda.	`8080`
`K_SERVICE`	Nama layanan Cloud Run yang sedang dijalankan.	`hello-world`
`K_REVISION`	Nama revisi Cloud Run yang sedang dijalankan.	`hello-world.1`
`K_CONFIGURATION`	Nama konfigurasi Cloud Run yang membuat revisi.	`hello-world`

Variabel lingkungan untuk tugas

Untuk tugas Cloud Run, variabel lingkungan berikut telah ditetapkan:

Nama	Deskripsi	Contoh
`CLOUD_RUN_JOB`	Nama tugas Cloud Run yang sedang dijalankan.	`hello-world`
`CLOUD_RUN_EXECUTION`	Nama eksekusi Cloud Run yang sedang dijalankan.	`hello-world-abc`
`CLOUD_RUN_TASK_INDEX`	Indeks tugas ini. Dimulai dari 0 untuk tugas pertama dan bertambah 1 untuk setiap tugas yang berurutan, hingga jumlah maksimum tugas minus 1. Jika Anda menetapkan `--parallelism` ke lebih besar dari 1, tugas mungkin tidak mengikuti urutan indeks. Misalnya, tugas 2 dapat dimulai sebelum tugas 1.	`0`
`CLOUD_RUN_TASK_ATTEMPT`	Frekuensi percobaan ulang tugas ini. Dimulai dari 0 untuk percobaan pertama dan akan bertambah 1 untuk setiap percobaan ulang berturut-turut, hingga nilai percobaan ulang mencapai batas maksimum.	`0`
`CLOUD_RUN_TASK_COUNT`	Jumlah tugas yang ditentukan dalam parameter `--tasks`.	`1`

Persyaratan header respons dan permintaan (layanan)

Untuk layanan Cloud Run, nama header dibatasi untuk ASCII non-spasi yang dapat dicetak, dan tidak boleh berisi titik dua. Nilai header dibatasi untuk karakter ASCII yang terlihat, ditambah spasi dan tab horizontal sesuai dengan IETF RFC 7230

Akses sistem file

Sistem file di setiap container Anda dapat ditulis dan tunduk pada perilaku berikut:

Ini adalah sistem file dalam memori, sehingga penulisan ke file ini akan menggunakan memori instance.
Data yang ditulis ke sistem file tidak akan bertahan saat instance dihentikan.

Perlu diperhatikan bahwa Anda tidak dapat menentukan batas ukuran untuk sistem file ini, sehingga Anda berpotensi menggunakan semua memori yang dialokasikan untuk instance dengan menulis ke sistem file dalam memori, yang akan menyebabkan instance mengalami error. Anda dapat menghindari masalah ini jika menggunakan volume dalam memori khusus dengan batas ukuran.

Siklus proses instance

Karakteristik siklus proses berbeda untuk tugas dan layanan Cloud Run, sehingga nanti akan dijelaskan secara terpisah di subbagian berikut.

Untuk layanan

Hal berikut hanya berlaku untuk layanan.

Penskalaan layanan

Layanan Cloud Run secara otomatis diskalakan ke jumlah instance yang diperlukan untuk menangani semua permintaan masuk, peristiwa, atau penggunaan CPU.

Setiap instance menjalankan sejumlah container tetap – satu container masuk dan secara opsional satu atau beberapa container file bantuan.

Jika revisi tidak menerima traffic apa pun, revisi tersebut akan diskalakan ke jumlah minimum instance yang dikonfigurasi (nol secara default).

Startup

Untuk layanan Cloud Run, instance Anda harus memproses permintaan dalam waktu 4 menit setelah dimulai dan semua container dalam instance harus responsif. Selama waktu startup ini, instance diberi alokasi CPU. Anda dapat mengaktifkan peningkatan CPU startup untuk meningkatkan alokasi CPU sementara selama startup instance guna mengurangi latensi pengaktifan.

Permintaan akan dikirim ke container masuk segera setelah memproses port yang dikonfigurasi.

Permintaan yang menunggu instance akan disimpan dalam antrean sebagai berikut:

Jika instance baru dimulai, seperti selama penyebaran skala, permintaan akan menunggu setidaknya selama waktu startup rata-rata instance container layanan ini. Hal ini termasuk saat permintaan memulai penyebaran skala, seperti saat menskalakan dari nol.
Jika waktu startup kurang dari 10 detik, permintaan akan dilanjutkan hingga 10 detik.
Jika tidak ada instance dalam proses awal dan permintaan tidak memulai penyebaran skala, permintaan akan menunggu hingga 10 detik.

Anda dapat mengonfigurasi pemeriksaan startup untuk menentukan apakah container telah dimulai dan siap menyalurkan permintaan.

Untuk layanan Cloud Run yang terdiri dari instance multi-container, Anda dapat menentukan urutan dimulainya container dalam instance dengan mengonfigurasi urutan startup container.

Memproses permintaan

Untuk layanan Cloud Run, CPU selalu dialokasikan ke semua container. Termasuk ke file bantuan dalam instance selama revisi Cloud Run memproses setidaknya satu permintaan

Tidak ada aktivitas

Untuk layanan Cloud Run, instance yang tidak ada aktivitas adalah instance yang tidak memproses permintaan apa pun.

CPU yang dialokasikan ke semua container dalam instance yang tidak ada aktivitas bergantung pada alokasi CPU yang dikonfigurasi.

Kecuali jika instance harus dibiarkan tidak beraktivitas karena setelan konfigurasi jumlah minimum instance, maka instance tidak akan dibiarkan menganggur selama lebih dari 15 menit.

Nonaktif

Untuk layanan Cloud Run, instance yang tidak ada aktivitas dapat dihentikan kapan saja, termasuk instance tetap aktif melalui jumlah minimum instance. Jika instance yang memproses permintaan perlu dinonaktifkan, permintaan masuk baru akan dirutekan ke instance lain dan permintaan yang saat ini sedang diproses akan diberi waktu untuk menyelesaikannya. Dalam kasus yang jarang terjadi, Cloud Run mungkin memulai penonaktifan dan mengirim sinyal SIGTERM ke container yang masih memproses permintaan.

Sebelum mematikan instance, Cloud Run mengirimkan sinyal SIGTERM ke semua container dalam instance, yang menunjukkan dimulainya periode 10 detik sebelum penonaktifan yang sebenarnya terjadi. Pada saat itu Cloud Run mengirimkan permintaan sinyal SIGKILL. Selama periode ini, instance mendapatkan alokasi CPU dan akan dikenai biaya. Pada layanan yang menggunakan lingkungan eksekusi generasi pertama, jika instance tidak menangkap sinyal SIGTERM, instance akan segera dimatikan. (Lihat contoh kode untuk mempelajari cara menangkap sinyal SIGTERM.)

Penghentian paksa

Jika satu atau beberapa container Cloud Run melebihi batas total memori container, maka instance akan dihentikan. Semua permintaan yang masih diproses di instance diakhiri dengan error HTTP 500.

Untuk tugas

Untuk tugas Cloud Run, instance container akan berjalan hingga instance container keluar, atau hingga waktu tunggu tugas tercapai, atau sampai container mengalami error.

Penghentian paksa

Instance container Cloud Run yang melebihi batas memori yang diizinkan akan dihentikan. Semua permintaan yang masih diproses pada instance container berakhir dengan error HTTP 500.

Jika tugas melebihi waktu tunggu tugas, Cloud Run akan mengirimkan sinyal 'SIGTERM' yang menunjukkan dimulainya periode 10 detik sebelum penonaktifan sebenarnya terjadi. Di sini Cloud Run mengirimkan sinyal SIGKILL, yang akan menonaktifkan instance container.

Selama periode ini, instance container mendapatkan alokasi CPU untuk seluruh siklus prosesnya dan dikenai biaya.

Baca contoh kode SIGTERM untuk mempelajari cara menangkap sinyal SIGTERM.

Resource instance container

CPU

Setiap container Cloud Run dalam instance secara default mendapatkan alokasi vCPU yang telah dikonfigurasi (1 secara default). Anda dapat mengonfigurasi batas CPU pada setiap container secara terpisah.

vCPU diimplementasikan sebagai abstraksi hardware dasar untuk memberikan perkiraan waktu CPU yang setara untuk hardware hyper-thread tunggal pada platform CPU variabel. Semua platform CPU yang digunakan oleh Cloud Run mendukung kumpulan petunjuk AVX2. Perhatikan bahwa kontrak container tidak berisi detail platform CPU tambahan.

Container mungkin dijalankan di beberapa core secara bersamaan.

Untuk layanan Cloud Run, Anda dapat menentukan CPU yang akan selalu dialokasikan selama masa pakai instance atau hanya untuk dialokasikan selama startup instance dan pemrosesan permintaan. Lihat alokasi CPU untuk mengetahui detailnya.

Jika Anda telah mengonfigurasi sejumlah instance minimum, instance ini juga tunduk pada konfigurasi alokasi CPU.

Anda dapat mengaktifkan peningkatan CPU startup untuk meningkatkan alokasi CPU untuk sementara waktu selama startup instance guna mengurangi latensi startup.

Memori

Setiap container Cloud Run secara default mendapatkan alokasi memori yang telah dikonfigurasi, (512 MiB secara default). Anda dapat mengonfigurasi batas memori pada setiap container secara terpisah.

Penggunaan umum memori meliputi:

Kode yang dimuat ke dalam memori untuk menjalankan layanan
Menulis ke sistem file
Proses tambahan yang berjalan dalam container seperti server nginx
Sistem caching dalam memori seperti OpCache PHP
Penggunaan memori per permintaan
Volume dalam memori bersama

Konkurensi (layanan)

Untuk layanan Cloud Run, setiap instance Cloud Run secara default ditetapkan ke beberapa serentak, dengan container masuk dapat menerima lebih dari satu permintaan secara bersamaan. Anda dapat mengubahnya dengan menyetel konkurensi.

Sandbox container

Jika Anda menggunakan lingkungan eksekusi generasi pertama, container Cloud Run akan di-sandbox menggunakan sandbox runtime container gVisor. Seperti yang tercantum dalam referensi kompatibilitas syscall gVisor, beberapa panggilan sistem mungkin tidak didukung oleh sandbox container ini.

Jika Anda menggunakan lingkungan eksekusi generasi kedua, Anda memiliki kompatibilitas penuh dengan Linux. Tugas Cloud Run selalu menggunakan lingkungan eksekusi generasi kedua. Dalam lingkungan eksekusi generasi kedua, /sys/class/dmi/id/product_name disetel ke Google Compute Engine.

Lingkungan eksekusi generasi kedua menjalankan kode layanan Anda dalam namespace proses terpisah, sehingga dimulai sebagai proses init container yang memiliki semantik proses khusus. Di lingkungan eksekusi generasi pertama, kode layanan Anda tidak dijalankan sebagai proses init container.

Server metadata instance

Instance Cloud Run menampilkan server metadata yang dapat Anda gunakan untuk mengambil detail tentang container, seperti project ID, region, ID instance, atau akun layanan. Token ini juga dapat digunakan untuk membuat token untuk akun layanan runtime.

Anda dapat mengakses data ini dari server metadata menggunakan permintaan HTTP sederhana ke endpoint http://metadata.google.internal/ dengan header Metadata-Flavor: Google: library klien tidak diperlukan. Untuk mengetahui informasi selengkapnya, baca Mendapatkan metadata.

Tabel berikut mencantumkan beberapa informasi server metadata yang tersedia:

Jalur	Deskripsi
`/computeMetadata/v1/project/project-id`	Project ID untuk layanan atau tugas Cloud Run yang berada di dalamnya
`/computeMetadata/v1/project/numeric-project-id`	Nomor project tempat layanan atau tugas Cloud Run berada
`/computeMetadata/v1/instance/region`	Region layanan atau tugas Cloud Run ini, menampilkan `projects/PROJECT-NUMBER/regions/REGION`
`/computeMetadata/v1/instance/id`	ID unik instance (juga tersedia di log).
`/computeMetadata/v1/instance/service-accounts/default/email`	Email untuk akun layanan runtime dari layanan atau tugas Cloud Run ini.
`/computeMetadata/v1/instance/service-accounts/default/token`	Membuat token akses OAuth2 untuk akun layanan dari layanan atau tugas Cloud Run ini. Agen layanan Cloud Run digunakan untuk mengambil token. Endpoint ini akan menampilkan respons JSON dengan atribut `access_token`. Baca selengkapnya tentang cara mengekstrak dan menggunakan token akses ini.

Perhatikan bahwa Cloud Run tidak memberikan detail tentang zona Google Cloud tempat instance dijalankan. Akibatnya, atribut metadata /computeMetadata/v1/instance/zone selalu menampilkan projects/PROJECT-NUMBER/zones/REGION-1.

Nama file

Nama file yang Anda gunakan dalam container harus kompatibel dengan UTF-8, baik UTF-8 atau yang dapat dikonversi otomatis secara aman ke UTF-8. Jika nama file Anda menggunakan encoding yang berbeda, jalankan build Docker di komputer dengan nama file yang kompatibel dengan UTF-8 dan hindari menyalin file ke container yang berisi nama UTF-8 yang tidak kompatibel.

Deployment container akan gagal jika nama file tidak kompatibel dengan UTF-8. Perhatikan bahwa tidak ada batasan encoding karakter yang Anda gunakan dalam file.

Koneksi keluar

Waktu tunggu permintaan keluar

Untuk layanan dan tugas Cloud Run, ada waktu tunggu setelah 10 menit waktu tidak ada aktivitas untuk permintaan dari container Anda ke VPC. Untuk permintaan dari container ke internet, diberikan waktu tunggu setelah 20 menit tidak beraktivitas.

Koneksi keluar direset

Streaming koneksi dari container Anda ke VPC dan internet terkadang dapat dihentikan dan diganti ketika infrastruktur dasar dimulai ulang atau diperbarui. Jika aplikasi Anda menggunakan kembali koneksi yang memakan waktu lama, sebaiknya konfigurasikan aplikasi Anda agar menghubungkan koneksi kembali guna menghindari penggunaan ulang koneksi yang tidak aktif.