Menginstal Agent Substrate di GKE

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

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

Harga

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

Batasan

Substrat Agen memiliki batasan penginstalan berikut:

  • Cloud Shell: Anda tidak dapat menginstal Agent Substrate 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 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. Node yang dibuat sebelum update tidak mengaktifkan proyeksi sertifikat Pod (MountVolume.SetUp failed: unimplemented). Pada 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
  • Untuk 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.
    • Go 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, 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.

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

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

  • Mengaktifkan PodCertificateRequest dan ClusterTrustBundle Kubernetes API (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 pada 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

Untuk menginstal Agent Substrate, 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 project, cluster, dan setelan penyimpanan. 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 setelan default yang direkomendasikan atau menginstal Agent Substrate di cluster yang ada. Jika Anda memilih untuk menginstal di cluster yang ada, verifikasi bahwa 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 memilih sumber image container, Anda dapat memilih dari opsi berikut:

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

Yang dilakukan penginstal

Penginstal menjalankan program berikut atas nama Anda:

  • setup-gcp: membuat atau memverifikasi resource Google Cloud yang diperlukan, 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 dan pengontrol container Agent Substrate yang telah dibuat sebelumnya ke cluster GKE Anda.

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

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

Selanjutnya, penginstal akan membuat perubahan berikut pada cluster Anda:

  1. Menambahkan grup dan resource Agent Substrate API ke cluster Anda. Ini adalah resource kustom Kubernetes, seperti ActorTemplate (yang menentukan image container dan resource 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 dan Aktor Anda. Komponen menghadirkan sertifikat ini untuk saling mengautentikasi menggunakan mTLS.
  3. Men-deploy komponen Agent Substrate ke cluster Anda, beserta database PostgreSQL yang melacak status Aktor dan Pekerja Anda. Penginstal menunggu hingga database dan semua Pod bidang kontrol siap.

Agent Substrate men-deploy komponennya sebagai beban kerja 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 secara default untuk mengisolasi setiap agen Anda dari node tempat agen tersebut berjalan. Penginstal tidak mengonfigurasi runtime microVM. Untuk menggunakan runtime microVM, Anda harus men-deploy-nya secara manual ke node pool yang telah mengaktifkan virtualisasi bertingkat. Untuk mengetahui detailnya, lihat petunjuk runtime microVM di repositori Agent Substrate upstream.

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

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

Langkah opsional

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

  • Driver CSI Filestore: menginstal driver CSI Filestore yang dikonfigurasi untuk Agent Substrate. Pilih opsi ini jika agen Anda memerlukan penyimpanan file bersama di seluruh Pod, seperti ruang kerja atau repositori bersama. Jika cluster Anda telah mengaktifkan add-on managed GKE Filestore, penginstal akan menonaktifkannya sebelum men-deploy driver.
  • Penskalaan otomatis node pool: mengaktifkan penskalaan otomatis cluster GKE di node pool Anda. Anda menentukan jumlah minimum dan maksimum node untuk kumpulan. 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 Coba 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

Pelabelan dan versi node

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

Untuk memeriksa versi Agent Substrate 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:

  • Kumpulan pekerja: saat Anda membuat WorkerPool, konfigurasikan agar menargetkan tag versi ini. Untuk contohnya, lihat Menyematkan kumpulan ke versi substrat yang diinstal dalam panduan Substrate API.
  • Node baru: penginstal memberi label pada setiap node, bukan node pool. Oleh karena itu, setiap 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 tersebut.

Coba demo Penghitung

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

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

Meng-uninstal Agent Substrate

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 Substrat Agen dari cluster yang ada: jika Anda menginstal di cluster yang ada dan ingin mempertahankan cluster serta beban kerja lainnya, hapus hanya komponen Substrat Agen dengan menjalankan perintah ate-setup delete ate-system yang dicetak oleh penginstal. Penginstal akan mengisi perintah ini sebelumnya dengan nilai project, cluster, dan lokasi yang dikonfigurasi selama penginstalan.

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

Langkah berikutnya