Mengelola akses ke API Google Cloud untuk agen

Developer aplikasi dapat meminta identitas agen untuk agen AI yang berjalan di Google Kubernetes Engine (GKE). Identitas agen adalah identitas per-Pod yang dapat terikat secara kriptografis ke setiap Pod dalam workload. Kemudian, agen dapat mengautentikasi ke Google Cloud API menggunakan identitas agen. Anda dapat mengontrol resource yang dapat diakses agen dengan menyertakan agen sebagai pokok dalam kebijakan Identity and Access Management (IAM). Dokumen ini menjelaskan cara mengelola akses ke Google Cloud API dan layanan untuk agen yang menggunakan identitas agen.

Dokumen ini ditujukan untuk administrator keamanan dan administrator platform yang mengelola otorisasi untuk agen yang di-deploy developer ke cluster GKE. Anda seharusnya sudah memahami topik berikut:

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.
  • Pastikan Anda memiliki cluster Autopilot yang sudah ada atau cluster Standard yang telah mengaktifkan Workload Identity Federation untuk GKE dan menjalankan GKE versi 1.37.0-gke.3503000 atau yang lebih baru.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mengelola akses ke Google Cloud API untuk agen, minta administrator untuk memberi Anda peran IAM berikut di Google Cloud project:

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.

Menemukan ID utama agen

Bagian ini menjelaskan cara membuat ID prinsipal untuk agen. Anda dapat menggunakan ID ini dalam kebijakan IAM untuk mengontrol resource yang dapat diakses oleh agen.

Setiap workload agen yang meminta identitas agen akan mendapatkan string identitas SPIFFE yang unik untuk workload tersebut. Saat aplikasi memanggil Google Cloud API, panggilan diautentikasi menggunakan token akses identitas agen yang memvalidasi bahwa workload memiliki identitas agen. Token akses ini mencakup ID akun utama IAM untuk workload agen, yang dapat Anda sertakan dalam kebijakan IAM untuk mengontrol resource yang dapat diakses oleh agen tersebut.

Saat mendesain kebijakan IAM, Anda dapat membuat ID prinsipal untuk agen menggunakan informasi berikut:

  • Hierarki resource project.
  • Nama cluster.
  • Namespace Kubernetes dan ServiceAccount Kubernetes di namespace tersebut.

Saat men-deploy agen yang mendapatkan identitas agen yang cocok dengan ID prinsipal, agen akan mewarisi akses yang Anda tentukan dalam kebijakan Anda.

Untuk menemukan ID utama yang akan digunakan dalam kebijakan Anda, ikuti langkah-langkah berikut:

  1. Mengidentifikasi domain tepercaya untuk identitas. Domain tepercaya bergantung pada apakah project berada dalam organisasi, sebagai berikut:

    • Project yang berada dalam organisasi:

      agents.global.org-ORGANIZATION_ID.system.id.goog

      Ganti ORGANIZATION_ID dengan ID organisasi.

    • Project yang tidak berada dalam organisasi:

      agents.global.proj-PROJECT_NUMBER.system.id.goog

      Ganti PROJECT_NUMBER dengan nomor project untuk project cluster.

  2. Identifikasi informasi berikut tentang cluster:

    • Nama cluster GKE.
    • Lokasi bidang kontrol cluster, seperti us-central1.
    • Namespace Kubernetes tempat developer men-deploy workload.
    • Nama ServiceAccount Kubernetes yang harus digunakan developer untuk workload agen.

    Jika Anda tidak mengetahui informasi ini, tanyakan kepada tim platform Anda. Tim platform harus menyiapkan namespace, ServiceAccount, dan kebijakan RBAC di cluster sehingga agen yang memiliki persyaratan akses yang berbeda mendapatkan identitas yang berbeda.

  3. Buat ID utama:

    principal://TRUST_DOMAIN/resources/container/projects/PROJECT_NUMBER/locations/CONTROL_PLANE_LOCATION/clusters/CLUSTER_NAME/ns/KUBERNETES_NAMESPACE/sa/KUBERNETES_SERVICEACCOUNT

    Ganti kode berikut:

    • TRUST_DOMAIN: domain tepercaya untuk identitas agen.
    • PROJECT_NUMBER: nomor project dari project cluster.
    • CONTROL_PLANE_LOCATION: region atau zona bidang kontrol cluster.
    • CLUSTER_NAME: nama cluster.
    • KUBERNETES_NAMESPACE: nama namespace Kubernetes.
    • KUBERNETES_SERVICEACCOUNT: nama ServiceAccount Kubernetes.

Menggunakan kebijakan untuk mengontrol akses

Bagian ini menjelaskan cara menggunakan ID utama agen untuk mengontrol API Google Cloud dan layanan yang dapat diakses agen. Untuk mengontrol akses, sertakan ID akun utama dalam salah satu kebijakan IAM berikut:

Setelah Anda membuat atau memperbarui kebijakan, setiap agen yang meminta identitas agen dan berjalan di namespace tersebut serta menggunakan ServiceAccount tersebut akan memiliki akses yang Anda tentukan dalam kebijakan Anda.

Mengizinkan agen mengakses pengelola autentikasi

Pengelola autentikasi Identitas Agen adalah broker autentikasi dan brankas kredensial yang dapat digunakan agen untuk mendapatkan kredensial guna mengakses alat dan layanan eksternal, baik sebagai identitas agen itu sendiri maupun atas nama pengguna akhir. Pengelola otorisasi dapat memiliki satu atau beberapa penyedia otorisasi, yang masing-masing menangani alur otentikasi dan perolehan kredensial tertentu untuk layanan tertentu. Untuk memberikan akses agen GKE ke penyedia autentikasi tertentu, ikuti langkah-langkah berikut:

  1. Temukan ID utama untuk agen.
  2. Mendapatkan nama penyedia autentikasi yang perlu diakses agen.

  3. Berikan peran Agent Identity User (roles/agentidentity.user) pada penyedia otorisasi ke akun utama agen:

    gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
    --location=AUTH_PROVIDER_LOCATION \
    --member=PRINCIPAL_IDENTIFIER \
    --role=roles/agentidentity.user

    Ganti kode berikut:

    • AUTH_PROVIDER_NAME: nama penyedia autentikasi.
    • AUTH_PROVIDER_LOCATION: region penyedia autentikasi.
    • PRINCIPAL_IDENTIFIER: ID principal agen.

    Atau, untuk agen yang terdaftar di Agent Registry, Anda dapat mengelola akses ke penyedia autentikasi dengan membuat binding penyedia autentikasi.

Langkah berikutnya