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 menjalankan kode yang tidak tepercaya di lingkungan yang terisolasi langsung dalam workload container. Kemampuan ini membantu agen AI menjalankan sub-agen, mengeksekusi tugas komputasi, atau meluncurkan browser otomatis dengan aman tanpa membahayakan sistem host.

Keunggulan utama

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 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 benar-benar 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 ke akun Google Cloud Anda. 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 worker, 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
• Pekerjaan
• 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 biner dengan mereferensikan jalur absolutnya dalam kode sumber. Misalnya, untuk mencetak Hello di 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

Anda dapat menjalankan instruksi di sandbox sementara yang baru 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 menurut 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 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 sandbox sebelum dieksekusi.
• --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. Menulis data di dalam sandbox dan mengekspor 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 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 loop agen latar belakang yang terus memproses permintaan masuk, gunakan flag --detach.

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

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

Anda dapat menggunakan tanda 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 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

Konfigurasi 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 tanda 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 Agentic Workflows yang berjalan lama, jalankan perintah terhadap sandbox secara dinamis, dan ambil status sistem filenya yang telah dimodifikasi 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, menulis file ke overlay-nya, dan mengambil snapshot statusnya untuk memverifikasi bahwa data telah diambil, jalankan perintah berikut:

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

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

Mengonfigurasi jaringan

Secara default, semua traffic keluar dari sandbox diblokir. Untuk mengizinkan akses jaringan keluar, gunakan tanda --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 tanda --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 mount 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 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 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 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 tanda --mount:

1. Buat direktori volume bersama di penampung 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 terikat:

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

   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 akan menampilkan write.

Mengonfigurasi pemasangan hanya baca

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

Misalnya, jalankan perintah berikut untuk menguji batasan penulisan 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 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 merekam peristiwa siklus proses sandbox, seperti mulai dan keluar dari eksekusi, di Cloud Logging.

CLI sandbox 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 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 hosting agen AI di Cloud Run.
• Pelajari otomatisasi browser dan OS di Cloud Run.
• Tinjau kontrak runtime container.