Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Eksekusi kode di Cloud Run

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 mengeksekusi kode tidak tepercaya yang ditulis dalam bahasa apa pun, di lingkungan sandbox yang sangat dioptimalkan, yang diisolasi dari container Anda yang lain.

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 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, rahasia, 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.

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Instal dan lakukan inisialisasi gcloud CLI.
Deploy layanan Cloud Run di lingkungan eksekusi generasi kedua.

Mengaktifkan sandbox

Saat Anda mengaktifkan sandbox, layanan Cloud Run Anda di-deploy di lingkungan eksekusi generasi kedua. Untuk mengaktifkan sandbox di layanan Cloud Run, gunakan Google Cloud CLI atau konfigurasi YAML:

gcloud

Untuk men-deploy atau mengupdate layanan, tentukan flag --sandbox-launcher:

Untuk men-deploy layanan baru, jalankan perintah berikut:
```
gcloud beta run deploy SERVICE --image IMAGE_URL --sandbox-launcher
```
Ganti kode berikut:
- SERVICE: nama layanan Cloud Run Anda.
- IMAGE_URL: referensi ke image container, misalnya, us-docker.pkg.dev/cloudrun/container/hello:latest. Jika Anda menggunakan Artifact Registry, repositori REPO_NAME harus sudah dibuat. URL mengikuti format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

Untuk mengupdate layanan yang ada, jalankan perintah berikut:

gcloud beta run services update SERVICE --sandbox-launcher

YAML

Jika Anda membuat layanan baru, lewati langkah ini. Jika Anda mengupdate layanan yang sudah ada, download konfigurasi YAML-nya:
```
gcloud run services describe SERVICE --format export > service.yaml
```
Perbarui file YAML layanan Anda untuk menyertakan atribut sandboxLauncher yang ditetapkan ke true di dalam konfigurasi container Anda:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    spec:
      containers:
      - name: CONTAINER
        image: IMAGE_URL
        sandboxLauncher: true
        port: 8080
```
Ganti kode berikut:
- SERVICE: nama layanan Cloud Run Anda.
- CONTAINER: nama container Anda.
- IMAGE_URL: referensi ke image container, misalnya, us-docker.pkg.dev/cloudrun/container/hello:latest. Jika Anda menggunakan Artifact Registry, repositori REPO_NAME harus sudah dibuat. URL mengikuti format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
Buat atau update layanan menggunakan perintah berikut:
```
gcloud run services replace service.yaml
```
Perintah gcloud run services replace secara default akan menggunakan file service.yaml jika ada.

Sandbox berbagi CPU dan memori yang dialokasikan ke host container. Pastikan batas container utama Anda untuk CPU dan memori cukup untuk mengakomodasi aplikasi Anda dan sandbox aktif yang Anda jalankan secara bersamaan.

Menonaktifkan sandbox

Untuk menonaktifkan kemampuan meluncurkan sandbox di layanan Anda, gunakan Google Cloud CLI atau konfigurasi YAML:

gcloud

Perbarui layanan menggunakan tanda --no-sandbox-launcher dengan menjalankan perintah berikut:

gcloud beta run services update SERVICE --no-sandbox-launcher

Ganti SERVICE dengan nama layanan Anda.

YAML

Jika Anda membuat layanan baru, lewati langkah ini. Jika Anda mengupdate layanan yang sudah ada, download konfigurasi YAML-nya:
```
gcloud run services describe SERVICE --format export > service.yaml
```
Perbarui file YAML layanan Anda untuk menghapus atribut sandboxLauncher di dalam konfigurasi penampung Anda:
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
spec:
  template:
    spec:
      containers:
      - name: CONTAINER
        image: IMAGE_URL
        port: 8080
```
Ganti kode berikut:
- SERVICE: nama layanan Cloud Run Anda.
- CONTAINER: nama container Anda.
- IMAGE_URL: referensi ke image container, misalnya, us-docker.pkg.dev/cloudrun/container/hello:latest. Jika Anda menggunakan Artifact Registry, repositori REPO_NAME harus sudah dibuat. URL mengikuti format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
Buat atau update layanan menggunakan perintah berikut:
```
gcloud run services replace service.yaml
```
Perintah gcloud run services replace secara default akan menggunakan file service.yaml jika ada.

Meluncurkan sandbox

Setelah mengaktifkan sandbox, Anda dapat meluncurkan sandbox dari dalam lingkungan eksekusi penampung. Biner sandbox terletak di /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(`/usr/local/gcp/bin/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(
    ["/usr/local/gcp/bin/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("/usr/local/gcp/bin/sandbox", "do", "--", "/bin/echo", "Hello")
out, err := cmd.CombinedOutput()

Sandbox CLI

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

/usr/local/gcp/bin/sandbox do -- /bin/echo "Hello"

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

Untuk melihat daftar lengkap perintah yang tersedia, jalankan perintah /usr/local/gcp/bin/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:

Membuat lingkungan sandbox (sandbox run).
Menjalankan perintah yang Anda tentukan (sandbox exec).
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 mengeksekusi 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 bind mount 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:

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"

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 headless, atau server latar belakang, seperti loop agen latar belakang yang terus memproses permintaan masuk, gunakan tanda --detach.

Misalnya, jalankan perintah berikut untuk memulai sandbox terpisah 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 alur kerja agen yang berjalan lama, jalankan perintah terhadap sandbox secara dinamis, dan ambil status sistem file yang diubah ke dalam file arsip tar.

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:

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"

Buat snapshot sistem file yang dimodifikasi dari sandbox yang sedang berjalan menggunakan perintah sandbox tar:
```
sandbox tar my-sandbox --file=/tmp/foo.tar
```
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.

Untuk memverifikasi akses hanya baca default, jalankan perintah berikut:

Buat skrip Python di container host:

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

Verifikasi bahwa file ada secara lokal:
```
cat /tmp/my-scripts/task.py
```
Jalankan file di dalam sandbox Anda:
```
sandbox do -- /usr/bin/python3 /tmp/my-scripts/task.py
```
Perintah ini akan 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:

Buat direktori volume bersama di penampung host dan isi dengan file awal:

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

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.

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"

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

Eksekusi kode di Cloud Run Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Mengaktifkan sandbox

gcloud

YAML

Menonaktifkan sandbox

gcloud

YAML

Meluncurkan sandbox

Node.js

Python

Go

Sandbox CLI

Menggunakan kemampuan command line sandbox

Menjalankan perintah di sandbox Anda

Node.js

Python

Go

Sandbox CLI

Mempertahankan data di berbagai eksekusi

Menjalankan perintah di latar belakang

Mengonfigurasi variabel lingkungan

Membuat snapshot sistem file

Mengonfigurasi jaringan

Mengakses sistem file

Akses hanya baca default

Membagikan data menggunakan pemasangan bind

Mengonfigurasi pemasangan hanya baca

Melihat log

Node.js

Python

Go

Langkah berikutnya

Eksekusi kode di Cloud Run