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 Standard GKE.

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: Anda tidak dapat mengaktifkan API beta yang diperlukan (podcertificaterequests dan clustertrustbundles) di cluster yang ada. Jika Anda menginstal di cluster yang sudah ada yang menjalankan versi 1.36, API ini harus telah diaktifkan saat cluster dibuat.
  • 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 (Substrat Agen 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.
  • Apakah PodCertificateRequest dan ClusterTrustBundle Kubernetes API telah diaktifkan (certificates.k8s.io/v1beta1/podcertificaterequests dan certificates.k8s.io/v1beta1/clustertrustbundles). API ini tersedia di Kubernetes versi 1.37 atau yang lebih baru, yang berarti API ini diaktifkan di cluster yang menjalankan versi 1.37 atau yang lebih baru. Anda hanya perlu mengaktifkannya secara manual di cluster yang ada yang menjalankan versi patch 1.36. Untuk mengetahui petunjuknya, lihat Mengaktifkan API beta di cluster yang ada.

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 setelan project, cluster, dan penyimpanan. Jika memungkinkan, setelan ini menyarankan default yang direkomendasikan, 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 sudah 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 registry container. Karena tidak ada yang dibangun atau di-push, project Google Cloud Anda tidak memerlukan registri penampung 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 sudah ada) dan bucket Cloud Storage, serta mengonfigurasi kebijakan IAM.
  • ate-setup: men-deploy image container dan pengontrol 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 tempat Agent Substrate menulis snapshot Anda.
  4. Memberikan akses Agent Substrate ke Cloud Storage untuk menyimpan snapshot. Jika Anda memilih untuk membangun dari sumber, akses ke Artifact Registry untuk image container juga akan diberikan.
  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 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 dan Aktor Anda. Komponen menyajikan 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 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 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 di titik mana pun (misalnya, karena error jaringan sementara atau masa berlaku token habis), jalankan kembali perintah. Penginstal akan mempertahankan resource yang ada dan melanjutkan dari titik terakhir.

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 GKE Filestore terkelola, 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 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

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 hanya menjalankan Worker 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 pelabelan node berikut:

  • Kumpulan pekerja: saat Anda membuat WorkerPool, konfigurasikan agar menargetkan tag versi ini. Untuk contoh, 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—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 dan workload 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 "Tearing down" di README substrate-gke.

Langkah berikutnya