Eksekusi kode di Cloud Run

Pratinjau — Sandbox Cloud Run

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Cloud Run sudah di-sandbox dan diisolasi, sehingga ideal untuk menghosting agen AI. Saat Anda mengaktifkan sandbox Cloud Run, alat command line sandbox akan tersedia di container Anda. Gunakan alat command line ini untuk menjalankan kode yang tidak tepercaya yang ditulis dalam bahasa apa pun, di lingkungan sandbox yang sangat dioptimalkan, yang diisolasi dari bagian container lainnya.

Agen AI dapat memanfaatkan sandbox untuk menjalankan sub-agen dengan aman, melakukan tugas komputasi, atau membuka browser di lingkungan yang cepat dan terisolasi tanpa membahayakan sistem host.

Sandbox Cloud Run memberikan keuntungan utama berikut:

• Pembuatan cepat: Sandbox bersifat interaktif dan siap menjalankan perintah hampir secara instan. Dengan membuat sandbox dalam resource Cloud Run yang ada tempat agen Anda berjalan, Anda mengurangi waktu pembuatan jika dibandingkan dengan membuat resource Cloud Run baru untuk setiap tugas. Efisiensi ini membantu memastikan agen Anda tetap responsif.

• Keamanan: Sandbox mengisolasi eksekusi proses. Secara default, sandbox tidak memiliki akses ke workload induk, variabel lingkungan, secret, atau server Google Cloud metadata. Semua sandbox sepenuhnya terisolasi satu sama lain.

• Kontrol akses dan lingkungan: Proses berjalan dengan hak istimewa sudo sebagai pengguna non-root, sehingga Anda dapat menginstal alat menggunakan pengelola paket seperti apt, pip, atau npm selama eksekusi. Meskipun lingkungan sandbox bersifat sementara dan dihapus setelah selesai, Anda dapat menggunakan direktori persisten atau snapshot untuk menyimpan ruang kerja tertentu atau memetakan data ke bucket Cloud Storage.

Sebelum memulai

Login keakun Anda. Google Cloud Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Instal dan lakukan inisialisasi gcloud CLI.
2. Deploy resource Cloud Run, seperti layanan generasi kedua , tugas, kumpulan pekerja, atau instance.

Mengaktifkan sandbox

Untuk menggunakan sandbox, Anda harus mengaktifkannya terlebih dahulu di resource Cloud Run menggunakan flag --sandbox-launcher atau atribut YAML sandboxLauncher. Untuk langkah-langkah konfigurasi mendetail, pilih dari jenis resource berikut:

• Layanan
• Tugas
• Kumpulan pekerja
• Instance (Pratinjau)

Meluncurkan sandbox

Setelah mengaktifkan sandbox, Anda dapat meluncurkan sandbox dari dalam lingkungan eksekusi container. Biner sandbox terletak di /usr/local/gcp/bin/sandbox.

Contoh dalam panduan ini menggunakan perintah sandbox, bukan jalur absolutnya /usr/local/gcp/bin/sandbox.

Anda dapat menjalankan program biner dengan mereferensikan jalur absolutnya dalam kode sumber. Misalnya, untuk mencetak Hello di dalam sandbox terisolasi, pilih salah satu opsi berikut:

Node.js

Untuk menjalankan perintah sandbox dari aplikasi Node.js, sertakan kode berikut:

exec(`sandbox do -- /bin/echo "Hello"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

Python

Untuk menjalankan perintah sandbox dari aplikasi Python, sertakan kode berikut:

import subprocess
result = subprocess.run(
    ["sandbox", "do", "--", "/bin/echo", "Hello"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

Go

Untuk menjalankan perintah sandbox dari aplikasi Go, sertakan kode berikut:

cmd := exec.Command("sandbox", "do", "--", "/bin/echo", "Hello")
out, err := cmd.CombinedOutput()

Sandbox CLI

Untuk menjalankan perintah sandbox langsung dari command line, jalankan perintah berikut:

sandbox do -- /bin/echo "Hello"

Untuk melihat daftar lengkap perintah yang tersedia, jalankan perintah sandbox -h.

Menggunakan kemampuan command line sandbox

Alat command line sandbox berisi perintah untuk menjalankan, mengonfigurasi, dan mengelola sandbox.

Menjalankan perintah di sandbox

Anda dapat menjalankan instruksi di sandbox baru yang bersifat sementara menggunakan perintah sandbox do. Perintah sandbox do melakukan tugas berikut:

1. Menyiapkan lingkungan sandbox (sandbox run).
2. Menjalankan perintah yang Anda tentukan (sandbox exec).
3. Menghapus sandbox setelah eksekusi berhasil (sandbox delete).

Misalnya, untuk melakukan perhitungan matematika di dalam sandbox, jalankan cuplikan kode berikut untuk bahasa pilihan Anda. Pastikan perintah atau alat yang Anda jalankan, seperti python3, diinstal di image container Anda:

Node.js

Untuk menjalankan perintah sandbox dari aplikasi Node.js:

exec(`sandbox do -- /usr/bin/python3 -c "print(1+2)"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

Python

Untuk menjalankan perintah sandbox dari aplikasi Python:

import subprocess
result = subprocess.run(
    ["sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

Go

Untuk menjalankan perintah sandbox dari aplikasi Go:

cmd := exec.Command("sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)")
out, err := cmd.CombinedOutput()

Sandbox CLI

Untuk menjalankan perintah sandbox langsung dari command line:

sandbox do -- /usr/bin/python3 -c "print(1+2)"

Jika Anda menjalankan perintah berdasarkan nama tanpa jalur absolutnya, seperti python3, bukan /usr/bin/python3, konfigurasikan variabel lingkungan PATH secara eksplisit di sandbox menggunakan flag --env.

Mempertahankan data di berbagai eksekusi

Sandbox bersifat sementara secara default. Untuk mempertahankan data di berbagai eksekusi sandbox dalam instance Cloud Run yang sama, Anda dapat mengimpor dan mengekspor status sistem file ruang kerja menggunakan file arsip tar standar. Atau, Anda dapat mengonfigurasi pemasangan bind untuk berbagi direktori secara langsung antara container host dan lingkungan sandbox.

Gunakan flag berikut saat menjalankan perintah sandbox do:

• --export-tar: Mengambil file overlay yang diubah ke dalam file arsip tar setelah selesai.
• --import-tar: Mengekstrak file dari file arsip tar ke dalam sandbox sebelum eksekusi.
• --sync-tar: Melakukan sinkronisasi dua arah dengan mengimpor sebelum eksekusi dan mengekspor setelah selesai.

Misalnya, untuk meneruskan data antara dua panggilan sandbox menggunakan file arsip, jalankan perintah berikut:

1. Tulis data di dalam sandbox dan ekspor status ke file arsip:

   sandbox do --write --export-tar=/tmp/work.tar \
     -- /usr/bin/bash -c "mkdir -p /tmp/work && echo 'task-complete' > /tmp/work/status.txt"
   

2. Impor file arsip dalam panggilan berikutnya untuk mengambil data:

   sandbox do --write --import-tar=/tmp/work.tar \
     -- /usr/bin/bash -c "cat /tmp/work/status.txt"
   

Atau, untuk mengimpor status arsip yang ada secara otomatis dan mengekspor perubahan baru dalam satu perintah, gunakan --sync-tar=/tmp/work.tar. Saat proses sandbox berakhir, Cloud Run akan menghapus file overlay sementara yang tidak diekspor ke file arsip secara permanen.

Menjalankan perintah di latar belakang

Untuk menjalankan proses yang berjalan lama, browser tanpa tampilan, atau server latar belakang, seperti loop agen latar belakang yang terus memproses permintaan masuk, gunakan flag --detach.

Misalnya, jalankan perintah berikut untuk memulai sandbox terpisah dengan program latar belakang atau tidak aktif:

sandbox run my-web-server --detach -- /usr/bin/long_running_or_idle_program

Anda dapat menggunakan flag detach untuk menggunakan kembali sandbox yang sama untuk beberapa pengujian. Untuk berinteraksi dengan atau menjalankan perintah tambahan di dalam sandbox terpisah yang sedang berjalan, gunakan perintah sandbox exec dan targetkan sandbox Anda berdasarkan namanya.

Misalnya, untuk menjalankan perintah pengujian di dalam sandbox latar belakang my-web-server yang ada, jalankan perintah berikut:

sandbox exec my-web-server -- /usr/bin/python3 -c "print('test-complete')"

Mengonfigurasi variabel lingkungan

Konfigurasikan variabel lingkungan di sandbox seperti yang Anda lakukan pada container lainnya. Sandbox tidak mewarisi variabel lingkungan dari container host. Anda harus memberikannya secara eksplisit menggunakan flag --env saat menjalankan perintah sandbox.

Misalnya, untuk meneruskan variabel konfigurasi ke sandbox, jalankan perintah berikut:

sandbox do --env AGENT_MODE="test" -- /usr/bin/bash -c "echo \$AGENT_MODE"

Hindari meneruskan secret menggunakan flag env karena secret tersebut mungkin terlihat oleh proses sandbox.

Membuat snapshot sistem file

Deploy sandbox bernama di latar belakang untuk menangani tugas berkelanjutan seperti server web atau alur kerja agen yang berjalan lama, jalankan perintah terhadap sandbox secara dinamis, dan ambil status sistem filenya yang diubah ke dalam file arsip tar.

Tips: Jika Anda menjalankan banyak perintah berulang kali di satu sandbox, pertimbangkan untuk meluncurkan sandbox sekali, dengan titik entri tidak aktif, seperti sleep 12m, lalu menjalankan perintah sandbox exec yang menargetkan sandbox ini untuk eksekusi perintah yang sangat cepat.

Misalnya, untuk men-deploy sandbox latar belakang, tulis file ke overlay-nya, dan ambil snapshot statusnya untuk memverifikasi bahwa data telah diambil, jalankan perintah berikut:

1. Deploy sandbox bernama di latar belakang dengan akses tulis diaktifkan, membuat file dalam ruang kerjanya:

   sandbox run --write my-sandbox --detach -- /usr/bin/bash -c "echo 'hi' > /tmp/hello.txt && sleep 1h"
   

2. Buat snapshot sistem file yang diubah dari sandbox yang sedang berjalan menggunakan perintah sandbox tar:

   sandbox tar my-sandbox --file=/tmp/foo.tar
   

3. Ekstrak dan verifikasi bahwa file arsip snapshot berisi data yang ditulis di dalam sandbox:

   tar -xvf /tmp/foo.tar
   

   Anda akan melihat hasil berikut:

   ./
   ./tmp/
   ./tmp/hello.txt
   

Mengonfigurasi jaringan

Secara default, semua traffic keluar dari sandbox diblokir. Untuk mengizinkan akses jaringan keluar, gunakan flag --allow-egress:

Misalnya, untuk mengambil data dari endpoint eksternal, jalankan perintah berikut:

sandbox do --allow-egress -- /usr/bin/python3 -c 'import urllib.request; print(urllib.request.urlopen("https://google.com").getcode())'

Perintah ini menampilkan kode status HTTP standar 200, yang menunjukkan koneksi berhasil.

Mengakses sistem file

Secara default, proses yang Anda jalankan di dalam sandbox memiliki akses hanya baca ke sistem file root container host. Anda dapat menggunakan flag --write untuk mengaktifkan penulisan ke overlay sistem file sementara (tmpfs). Namun, penulisan akan hilang saat sandbox dihapus. Untuk mengaktifkan penulisan persisten ke container host, Anda dapat mengonfigurasi pemasangan bind.

Akses hanya baca default

Di dalam sandbox, proses dapat membaca file dari container host, dan tidak dapat menulis ke sistem file root.

Contoh berikut mengasumsikan bahwa Anda menjalankan perintah dari direktori root (/) container host.

Untuk memverifikasi akses hanya baca default, jalankan perintah berikut:

1. Buat skrip Python di container host:

   mkdir -p /tmp/my-scripts
   echo "print('hi')" > /tmp/my-scripts/task.py
   

2. Verifikasi bahwa file ada secara lokal:

   cat /tmp/my-scripts/task.py
   

3. Jalankan file di dalam sandbox Anda:

   sandbox do -- /usr/bin/python3 /tmp/my-scripts/task.py
   

   Perintah ini menampilkan hi, yang mengonfirmasi bahwa sandbox memiliki akses baca.

   Jika Anda mencoba menulis data langsung ke sistem file root sandbox tanpa konfigurasi tambahan, eksekusi akan gagal. Misalnya, mencoba menulis ke /tmp di dalam sandbox default akan menampilkan error sistem file hanya baca:

   Jalankan perintah berikut untuk menulis ke sistem file root:

   sandbox do -- /usr/bin/bash -c "echo 'hi' > /tmp/testfile.txt"
   

   Perintah akan gagal dengan error berikut:

   /usr/bin/bash: line 1: /tmp/testfile.txt: Read-only file system
   Error: failed to exec in container: cmd.Wait(exec) failed: exit status 1
   

Membagikan data menggunakan pemasangan bind

Untuk mengizinkan proses di dalam sandbox menulis data yang dapat dipertahankan, lampirkan volume bersama menggunakan flag --mount:

1. Buat direktori volume bersama di container host dan isi dengan file awal:

   mkdir -p /tmp/my-volume
   echo 'read' > /tmp/my-volume/readwrite.txt
   

2. Jalankan sandbox untuk membaca file dari jalur pemasangan bind:

   sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "cat /mnt/my-mount/readwrite.txt"
   

   Perintah ini menampilkan read.

3. Jalankan sandbox untuk menulis data baru kembali ke host dari dalam pemasangan:

   sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount -- /usr/bin/bash -c "echo 'write' > /mnt/my-mount/readwrite.txt"
   

4. Verifikasi di container host bahwa sandbox berhasil mengubah file:

   cat /tmp/my-volume/readwrite.txt
   

   Perintah ini menampilkan write.

Mengonfigurasi pemasangan hanya baca

Untuk memberikan akses sandbox ke direktori host sekaligus mencegahnya mengubah file secara eksplisit, tambahkan atribut readonly ke spesifikasi pemasangan.

Misalnya, jalankan perintah berikut untuk menguji batasan tulis pada pemasangan bind hanya baca:

sandbox do --mount type=bind,source=/tmp/my-volume,destination=/mnt/my-mount,readonly -- /usr/bin/bash -c "echo 'fails' > /mnt/my-mount/hello.txt"

Upaya penulisan akan gagal dengan error berikut:

/usr/bin/bash: line 1: /mnt/my-mount/hello.txt: Read-only file system
Error: failed to exec in container: cmd.Wait(exec) failed: exit status 1

Melihat log

Cloud Run secara otomatis mengambil peristiwa siklus proses sandbox, seperti awal dan akhir eksekusi, di Cloud Logging.

sandbox CLI menulis output standar (stdout) dan error standar (stderr) dari perintah sandbox langsung ke aliran standar proses pemanggilan. Untuk melihat log ini di Cloud Logging, arahkan aliran ke output standar dan error standar container Anda:

Node.js

const { exec } = require('child_process');
const child = exec('sandbox do -- /usr/bin/python3 -c "print(1+2)"');
child.stdout.pipe(process.stdout);
child.stderr.pipe(process.stderr);

Python

subprocess.run(
    ["sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)"],
    stdout=sys.stdout,
    stderr=sys.stderr,
)

Go

cmd := exec.Command("sandbox", "do", "--", "/usr/bin/python3", "-c", "print(1+2)")
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
cmd.Run()

Langkah berikutnya

• Pelajari lebih lanjut cara menghosting agen AI di Cloud Run.
• Jelajahi otomatisasi browser dan OS di Cloud Run.
• Tinjau kontrak runtime container.