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.

Sandbox Cloud Run memungkinkan Anda mengeksekusi kode yang tidak tepercaya di lingkungan terisolasi langsung dalam workload container. Kemampuan ini membantu agen AI menjalankan sub-agen dengan aman, menjalankan tugas komputasi, atau meluncurkan browser otomatis tanpa membahayakan sistem host.

Keunggulan utama

Sandbox Cloud Run memberikan keunggulan 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 akan mengurangi waktu pembuatan 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 metadata Google Cloud . Semua sandbox sepenuhnya terisolasi satu sama lain.

• Kontrol akses dan lingkungan: Proses dijalankan 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 atau data peta tertentu ke bucket Cloud Storage.

Sebelum memulai

1. 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

2. Verify that billing is enabled for your Google Cloud project.

3. Instal dan lakukan inisialisasi gcloud CLI.
4. Deploy resource Cloud Run, seperti layanan, tugas, kumpulan worker, atau instance generasi kedua .

Mengaktifkan sandbox

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

• Layanan
• Pekerjaan
• Worker pool
• 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 mengeksekusi biner dengan mereferensikan jalur absolutnya dalam kode sumber Anda. Misalnya, untuk mencetak Hello di dalam sandbox yang 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()

CLI Sandbox

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

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

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

Misalnya, untuk melakukan penghitungan matematika di dalam sandbox, jalankan cuplikan kode berikut untuk bahasa pilihan Anda. Pastikan perintah atau alat apa pun 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 binding untuk membagikan 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.

Direktori /tmp di dalam sandbox bukan bagian dari overlay sistem file root, sehingga file arsip tidak menyertakan file yang ditulis ke /tmp. Untuk mempertahankan data, tulis data ke direktori lain, seperti /workspace.

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 /workspace && echo 'task-complete' > /workspace/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 /workspace/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 dihentikan, Cloud Run akan menghapus secara permanen file overlay sementara yang tidak diekspor ke file arsip.

Menjalankan perintah di latar belakang

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

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

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 menyediakannya secara eksplisit menggunakan flag --env saat menjalankan perintah sandbox.

Misalnya, untuk meneruskan variabel konfigurasi ke dalam 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

Men-deploy sandbox bernama di latar belakang untuk menangani tugas berkelanjutan seperti server web atau Agentic Workflows yang berjalan lama, menjalankan perintah terhadap sandbox secara dinamis, dan mengambil status sistem filenya yang telah 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 nonaktif, 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, menulis file ke overlay-nya, dan membuat snapshot statusnya untuk memverifikasi bahwa data telah diambil, jalankan perintah berikut:

1. Men-deploy sandbox bernama di latar belakang dengan akses tulis diaktifkan, sehingga membuat file dalam ruang kerjanya. Tulis file ke jalur di luar /tmp, karena file yang ditulis ke /tmp di dalam sandbox tidak diambil dalam snapshot:

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

2. Buat snapshot sistem file yang dimodifikasi 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:

   ./
   ./workspace/
   ./workspace/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 ikat.

Direktori /tmp di dalam sandbox selalu dapat ditulis, bahkan tanpa flag --write. Direktori /tmp akan dihapus saat sandbox dihapus, dan tidak disertakan dalam snapshot atau file arsip.

Akses hanya baca default

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

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

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 tersebut 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 direktori root (/) 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' > /testfile.txt"
   

   Perintah gagal dengan error berikut:

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

Berbagi data menggunakan pemasangan binding

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 ikat:

   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 akan 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. Pastikan di container host bahwa sandbox berhasil mengubah file:

   cat /tmp/my-volume/readwrite.txt
   

   Perintah ini akan menampilkan write.

Mengonfigurasi pemasangan hanya baca

Untuk memberi sandbox akses 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 binding 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 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 mencatat peristiwa siklus proses sandbox, seperti memulai dan menghentikan eksekusi, di Cloud Logging.

sandbox CLI menulis output standar (stdout) dan error standar (stderr) dari perintah yang di-sandbox langsung ke aliran standar proses pemanggilan. Untuk melihat log ini di Cloud Logging, arahkan aliran data 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.
• Pelajari otomatisasi browser dan OS di Cloud Run.
• Tinjau kontrak runtime container.