Menginstal Agent Substrate di GKE

Agent Substrate di GKE menjalankan workload agentic secara efisien di cluster GKE dengan menangguhkan agen yang tidak aktif dan memulihkan agen tersebut saat perlu bertindak lagi. Agent Substrate di GKE adalah software open source yang dapat Anda instal ke cluster GKE Standard.

Dokumen ini membantu Anda menyiapkan Google Cloud project dan cluster GKE untuk Agent Substrate di GKE, menjelaskan cara menjalankan penginstal, dan menjelaskan resource yang dibuat oleh penginstalan.

Harga

Agent Substrate di GKE ditawarkan tanpa biaya tambahan. Harga GKE berlaku untuk resource yang Anda buat.

Batasan

Agent Substrate di GKE memiliki batasan penginstalan berikut:

  • Cloud Shell: Anda tidak dapat menginstal Agent Substrate di GKE di Cloud Shell karena Cloud Shell menyediakan penyimpanan persistent disk sebesar 5 GB, yang tidak cukup untuk penginstalan. Anda harus menjalankan penginstal di komputer lokal Anda.
  • Mode cluster: Anda hanya dapat menginstal Agent Substrate di GKE di cluster GKE Standard. Cluster Autopilot tidak didukung.
  • Cluster yang ada dan API beta: jika Anda mengaktifkan API beta yang diperlukan (podcertificaterequests dan clustertrustbundles) di cluster yang ada yang menjalankan versi 1.36, Anda harus mengganti node yang ada sebelum menginstal Agent Substrate di GKE. Node yang dibuat sebelum update tidak mengaktifkan proyeksi sertifikat Pod (MountVolume.SetUp failed: unimplemented). Di cluster yang menjalankan versi 1.37 atau yang lebih baru, node yang ada tidak perlu diganti.
  • Jenis mesin: Anda tidak dapat menggunakan seri mesin yang berjalan pada arsitektur CPU campuran (seperti jenis mesin E2).

Sebelum memulai

Sebelum memulai, pastikan Anda telah melakukan tugas berikut:

  • Aktifkan Google Kubernetes Engine API.
    • Aktifkan Google Kubernetes Engine API
  • Jika ingin menggunakan Google Cloud CLI untuk tugas ini, instal lalu lakukan inisialisasi gcloud CLI. Jika sebelumnya Anda telah menginstal gcloud CLI, dapatkan versi terbaru dengan menjalankan perintah gcloud components update. Versi gcloud CLI yang lebih lama mungkin tidak mendukung menjalankan perintah dalam dokumen ini.
  • Instal komponen berikut di gcloud CLI:
    • kubectl
    • gke-gcloud-auth-plugin
  • Pastikan alat berikut diinstal di komputer lokal Anda:
    • Git untuk meng-clone repositori Agent Substrate.
    • Buka untuk menjalankan program penginstal, yang didistribusikan sebagai kode sumber.
    • make untuk memulai penginstal.

  • Karena penginstal bertindak atas nama Anda untuk mengaktifkan API dan menyediakan resource, siapkan Kredensial Default Aplikasi (ADC) dengan menjalankan perintah berikut:

    gcloud auth application-default login

    Untuk mengetahui informasi selengkapnya tentang autentikasi dengan ADC, lihat Menyiapkan Kredensial Default Aplikasi.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menginstal Agent Substrate di GKE, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Persyaratan cluster

Jika Anda mengizinkan penginstal membuat cluster untuk Anda, penginstal akan otomatis mengonfigurasi cluster yang memenuhi semua persyaratan untuk Agent Substrate di GKE.

Jika Anda memilih untuk menginstal Agent Substrate di GKE di cluster yang ada, cluster tersebut harus memenuhi persyaratan berikut:

  • Berjalan di GKE Standard (Agent Substrate di GKE hanya didukung di cluster Standard).
  • Menjalankan GKE versi 1.36 (dengan flag beta diaktifkan) atau versi 1.37 atau yang lebih baru.
  • Menggunakan jenis mesin c3-standard-4 atau yang lebih besar untuk node.

  • Mengaktifkan Kubernetes API PodCertificateRequest dan ClusterTrustBundle (certificates.k8s.io/v1beta1/podcertificaterequests dan certificates.k8s.io/v1beta1/clustertrustbundles). Untuk mengaktifkan API ini di cluster yang ada, jalankan perintah berikut:

    gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-kubernetes-unstable-apis=certificates.k8s.io/v1beta1/podcertificaterequests,certificates.k8s.io/v1beta1/clustertrustbundles
    • Versi 1.36: setelah mengaktifkan API, Anda harus mengganti node yang ada—misalnya, dengan mengupgrade node pool atau membuat ulang node-nya. Proyeksi sertifikat Pod tidak diaktifkan di node yang ada sebelum update (MountVolume.SetUp failed: unimplemented).
    • Versi 1.37 atau yang lebih baru: Proyeksi sertifikat Pod sudah diaktifkan di node yang ada, sehingga Anda tidak perlu mengganti node setelah mengaktifkan API.

Menginstal Agent Substrate di GKE

Untuk menginstal Agent Substrate di GKE, jalankan perintah berikut di terminal lokal Anda:

curl -sSL https://raw.githubusercontent.com/ai-on-gke/substrate-gke/main/install.sh | bash

Penginstal interaktif akan meminta Anda memasukkan setelan project, cluster, dan penyimpanan. Penginstal akan menyarankan default yang direkomendasikan jika memungkinkan, yang dapat Anda terima atau sesuaikan:

  • Project ID (wajib): tentukan Google Cloud project tempat resource akan disediakan. Jika Anda mengonfigurasi project default untuk gcloud CLI, penginstal akan menggunakan project ID tersebut.
  • Cluster (wajib): pilih apakah akan mengizinkan penginstal membuat cluster GKE baru dengan default yang direkomendasikan atau menginstal Agent Substrate di GKE di cluster yang ada. Jika Anda memilih untuk menginstal di cluster yang ada, pastikan cluster tersebut memenuhi persyaratan di bagian Persyaratan cluster.
  • Bucket snapshot (opsional): tentukan nama bucket Cloud Storage kustom, atau biarkan kosong agar penginstal membuat bucket default bernama ate-snapshots-<project>-<zone>.

Saat diminta untuk memilih sumber image container, Anda dapat memilih dari opsi berikut:

  • Image bawaan: mengambil image yang dipublikasikan dari Container Registry. Karena tidak ada yang di-build atau dikirim, project Google Cloud Anda tidak memerlukan Container Registry sendiri.
  • Build dari sumber: mem-build image dari repositori Agent Substrate upstream (atau cabang kustom) dan mengirimkannya ke registry Artifact Registry project Anda.

Tindakan yang dilakukan penginstal

Penginstal menjalankan program berikut atas nama Anda:

  • setup-gcp: membuat atau memverifikasi resource yang diperlukan Google Cloud , mengaktifkan API, membuat cluster GKE (jika Anda memilih untuk tidak menggunakan cluster yang ada) dan bucket Cloud Storage, serta mengonfigurasi kebijakan IAM.
  • ate-setup: men-deploy image container dan pengontrol Agent Substrate bawaan di GKE ke cluster GKE Anda.

Pertama, penginstal membuat perubahan berikut pada project Google Cloud Anda:

  1. Mengaktifkan Google Cloud APIs yang diperlukan Agent Substrate di GKE.
  2. Membuat cluster GKE Standard (jika tidak menggunakan cluster yang ada) yang memiliki setelan berikut:
    • Workload Identity Federation for GKE: memungkinkan Agent Substrate di GKE mengakses Cloud Storage tanpa menyimpan kunci di node.
    • GKE Dataplane V2: menangani jaringan yang diperlukan untuk merutekan permintaan masuk ke agen Anda.
    • API Sertifikat (PodCertificateRequest dan ClusterTrustBundle): mengaktifkan API beta Kubernetes ini untuk menerbitkan sertifikat untuk komunikasi TLS antara komponen Agent Substrate di GKE.
    • OpenTelemetry Terkelola: mengumpulkan metrik dan trace dari cluster Anda.
  3. Membuat bucket Cloud Storage tempat Agent Substrate di GKE menulis snapshot Anda.
  4. Memberikan akses Agent Substrate di GKE ke Cloud Storage untuk menyimpan snapshot. Jika Anda memilih untuk mem-build dari sumber, penginstal juga akan memberikan akses ke Artifact Registry untuk image container.
  5. Membuat dasbor Cloud Monitoring yang memetakan latensi perutean Agent Substrate di GKE, ukuran snapshot, dan traffic gRPC.

Selanjutnya, penginstal membuat perubahan berikut pada cluster Anda:

  1. Menambahkan grup dan resource Agent Substrate di GKE API ke cluster Anda. Ini adalah resource kustom Kubernetes, seperti ActorTemplate (yang menentukan image dan resource container yang digunakan agen Anda) dan WorkerPool (yang menentukan jumlah sandbox tidak aktif yang tetap siap).
  2. Menyiapkan otoritas sertifikat yang menerbitkan sertifikat yang mengidentifikasi komponen Agent Substrate di GKE dan Aktor Anda. Komponen menampilkan sertifikat ini untuk mengautentikasi satu sama lain menggunakan mTLS.
  3. Men-deploy komponen Agent Substrate di GKE ke cluster Anda, beserta database PostgreSQL yang melacak status Aktor dan Pekerja Anda. Penginstal menunggu database dan semua Pod bidang kontrol siap.

Agent Substrate di GKE men-deploy komponennya sebagai workload biasa dalam namespace ate-system dan podcertificate-controller-system. Penginstalan tidak mengubah bidang kontrol GKE.

Komponen yang di-deploy mencakup runtime berbasis gVisor yang digunakan Agent Substrate di GKE secara default untuk mengisolasi setiap agen Anda dari node tempatnya berjalan. Penginstal tidak mengonfigurasi runtime microVM. Untuk menggunakan runtime microVM, Anda harus men-deploy-nya secara manual ke node pool yang mengaktifkan virtualisasi bertingkat. Untuk mengetahui detailnya, lihat petunjuk runtime microVM di repositori Agent Substrate upstream.

Jika penginstalan gagal pada titik mana pun (misalnya, karena error jaringan sementara atau masa berlaku token berakhir), jalankan kembali perintah tersebut. Penginstal akan mempertahankan resource yang ada dan melanjutkan dari tempat penginstalan dihentikan.

Untuk mengupgrade Agent Substrate di GKE di cluster yang ada, jalankan penginstal dan pilih Upgrade an installed cluster. Untuk mengetahui detailnya, lihat Mengupgrade cluster yang diinstal di substrate-gke README.

Langkah opsional

Setelah men-deploy komponen inti, penginstal menawarkan langkah opsional berikut:

  • Driver CSI Filestore: menginstal driver CSI Filestore yang dikonfigurasi untuk Agent Substrate di GKE. Pilih opsi ini jika agen Anda memerlukan penyimpanan file bersama di seluruh Pod, seperti ruang kerja atau repositori bersama. Jika cluster Anda mengaktifkan add-on GKE Filestore terkelola, penginstal akan menonaktifkannya sebelum men-deploy driver.
  • Penskalaan otomatis node pool: mengaktifkan pensakalaan otomatis cluster GKE di node pool Anda. Anda menentukan jumlah node minimum dan maksimum untuk pool. Pilih opsi ini jika Anda ingin GKE otomatis menambahkan node selama lonjakan permintaan dan menghapus node saat agen ditangguhkan. Lewati opsi ini jika Anda lebih memilih jumlah node tetap dengan biaya komputasi yang dapat diprediksi.
  • Demo penghitung: men-deploy contoh workload yang menunjukkan penangguhan dan pemulihan agen. Pilih opsi ini jika Anda ingin menguji cluster setelah penginstalan. Untuk mengetahui detailnya, lihat Mencoba demo Penghitung.

Memverifikasi penginstalan

Untuk memverifikasi bahwa penginstalan berhasil dan komponen inti berjalan, jalankan perintah berikut dan pastikan semua Pod memiliki status Running:

kubectl get pods -n ate-system
kubectl get pods -n podcertificate-controller-system

Pemberian label dan versi node

Penginstal menerapkan label ate.dev/substrate-version ke setiap node di cluster Anda. Label ini menentukan versi Agent Substrate di GKE yang diinstal di cluster Anda, dan Agent Substrate di GKE hanya menjalankan Pekerja di node yang memiliki label versi ini.

Untuk memeriksa versi Agent Substrate di GKE yang diinstal di cluster Anda, jalankan perintah berikut:

kubectl get ds -n ate-system -l app=atelet -L ate.dev/substrate-version

Pertimbangkan detail pemberian label node berikut:

  • Pool pekerja: saat Anda membuat WorkerPool, konfigurasikan untuk menargetkan tag versi ini. Untuk mengetahui contohnya, lihat Menyematkan pool ke versi substrate yang diinstal dalam panduan Substrate API.
  • Node baru: penginstal memberi label pada node individual, bukan node pool. Karena hal ini, node baru yang ditambahkan setelah penginstalan—bahkan di node pool yang dibuat oleh penginstal—akan dimulai tanpa label versi. Anda harus memberi label pada node pool GKE agar node baru otomatis menerima label.

Mencoba demo Penghitung

Jika Anda memilih untuk men-deploy demo Penghitung saat diminta oleh penginstal, Anda dapat mengamati kemampuan penangguhan dan pemulihan Agent Substrate di GKE. Demo ini menjalankan server web kecil yang menyimpan hitungan dalam memori.

Setelah men-deploy WorkerPool dan ActorTemplate demo, penginstal akan mencetak perintah yang Anda perlukan untuk membuat Actor dari ActorTemplate dan mengirim permintaan ke Actor tersebut. README demo Penghitung di repositori Agent Substrate upstream menjelaskan langkah-langkah berikutnya yang harus dilakukan.

Meng-uninstal Agent Substrate di GKE

Setelah penginstalan selesai dan keluar, penginstal akan mencetak perintah pembersihan yang disesuaikan untuk lingkungan Anda.

Untuk menghapus resource yang dibuat selama penginstalan, pilih salah satu opsi berikut:

  • Menghapus Agent Substrate di GKE dari cluster yang ada: jika Anda menginstal di cluster yang ada dan ingin mempertahankan cluster serta workload lainnya, hapus hanya komponen Agent Substrate di GKE dengan menjalankan perintah ate-setup delete ate-system yang dicetak penginstal. Penginstal akan mengisi otomatis perintah ini dengan nilai project, cluster, dan lokasi yang dikonfigurasi selama penginstalan.

  • Menghapus semua resource (termasuk cluster): untuk menghapus cluster GKE, bucket snapshot, binding IAM, dan dasbor, jalankan perintah cleanup-gcp yang dicetak penginstal. Penginstal akan mengisi otomatis perintah ini dengan nilai project, cluster, lokasi, dan bucket yang dikonfigurasi selama penginstalan. Untuk mengetahui detailnya, lihat bagian "Tearing down" dari README substrate-gke.

Langkah berikutnya