Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Meminta identitas agen untuk agen GKE

Autopilot Standard

Workload agen yang Anda deploy di cluster Google Kubernetes Engine (GKE) sering kali perlu mengakses alat dan layanan eksternal, baik sebagai identitas agen itu sendiri maupun atas nama pengguna akhir. Administrator keamanan dan administrator platform juga ingin mengetahui tindakan agen yang di-deploy di seluruh layanan Google Cloud. Dokumen ini menunjukkan cara mengonfigurasi autentikasi untuk workload agen dengan meminta Agent Identity untuk Pod Anda. Dengan identitas agen ini, Anda dapat mengonfigurasi autentikasi tanpa harus mengelola kredensial secara manual untuk alur kerja yang berbeda, dan mengintegrasikan agen GKE Anda dengan Gemini Enterprise Agent Platform. Dokumen ini ditujukan bagi developer aplikasi yang membangun dan menjalankan workload agen di cluster GKE.

Anda seharusnya sudah memahami topik berikut:

Harga

Identitas Agen disediakan tanpa biaya tambahan di GKE.

Batasan

Anda hanya dapat mendaftarkan Deployment secara otomatis di Agent Registry. Pengontrol workload lain dan Pod statis tidak mendukung pendaftaran otomatis. Meskipun Anda dapat meminta identitas agen untuk semua jenis workload, pendaftaran di Agent Registry memungkinkan Anda mengintegrasikan identitas tersebut dengan Agent Platform.
Token akses identitas agen terikat hanya menggunakan cakupan OAuth https://www.googleapis.com/auth/cloud-platform. Anda tidak dapat menentukan cakupan yang berbeda untuk token akses terikat.

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.
Catatan: Untuk penginstalan gcloud CLI yang ada, pastikan untuk menyetel properti compute/region. Jika Anda terutama menggunakan cluster zona, tetapkan compute/zone sebagai gantinya. Dengan menyetel lokasi default, Anda dapat menghindari error di gcloud CLI yang seperti ini: One of [--zone, --region] must be supplied: Please specify location. Anda mungkin perlu menentukan lokasi dalam perintah tertentu jika lokasi cluster Anda berbeda dengan lokasi default yang Anda tetapkan.

Aktifkan Agent Registry API, jika belum diaktifkan:
Peran yang diperlukan untuk mengaktifkan API
Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.
```
gcloud services enable agentregistry.googleapis.com
```
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.
Pastikan Anda memiliki kuota yang cukup untuk operasi pertukaran token. Kuota ini memiliki nama Permintaan Token Workload Identity Exchange per menit per region. Untuk mengetahui informasi selengkapnya, lihat Kuota dan batas.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna meminta identitas agen dan men-deploy workload, minta administrator untuk memberi Anda peran IAM Kubernetes Engine Developer (roles/container.developer) di project Google Cloud 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.

Meminta identitas agen untuk workload

Untuk mendapatkan identitas agen untuk Pod, Anda menambahkan anotasi ke spesifikasi Pod untuk meminta ID SPIFFE bagi beban kerja dan menyuntikkan paket sertifikat X.509 ke setiap Pod. Untuk Pod yang dikelola oleh Deployment, Anda juga harus menambahkan anotasi dan label untuk mendaftarkan agen di Agent Registry. Meskipun pendaftaran bersifat opsional, hanya agen terdaftar yang dapat menggunakan layanan Platform Agen seperti Agent Gateway. Untuk mengetahui informasi selengkapnya tentang anotasi dan label tertentu, lihat Konfigurasi tingkat workload.

Langkah-langkah berikut menunjukkan cara membuat contoh Deployment yang meminta identitas agen:

Temukan ID organisasi Anda. Jika project Anda tidak berada dalam organisasi, lewati langkah ini dan temukan nomor project Anda.
```
gcloud projects get-ancestors PROJECT_ID
```
Ganti PROJECT_ID dengan project ID cluster.

Outputnya mirip dengan hal berikut ini:
```
ID: my-project
TYPE: project
ID: 811159889184
TYPE: folder
ID: 301928500920
TYPE: organization
```
Catat nilai di kolom ID untuk resource organization.
Buat koneksi ke cluster Anda:
```
gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION
```
Ganti kode berikut:
- CLUSTER_NAME: nama cluster Anda.
- CONTROL_PLANE_LOCATION: region atau zona bidang kontrol cluster Anda.
Buat namespace untuk menjalankan contoh Deployment:
```
kubectl create namespace NAMESPACE_NAME
```
Ganti NAMESPACE_NAME dengan nama untuk namespace.
Buat ServiceAccount Kubernetes untuk Deployment:
```
kubectl create serviceaccount SERVICEACCOUNT_NAME \
    --namespace=NAMESPACE_NAME
```
Ganti SERVICEACCOUNT_NAME dengan nama untuk ServiceAccount.

Simpan manifes Deployment berikut sebagai agent-identity-deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: agent-identity-deployment
  namespace: NAMESPACE_NAME
  # Add the agent to Agent Registry
  labels:
    registry.gke.io/functional-type: "AGENT"
  annotations:
    # A2A protocol metadata annotation for automated Agent Card discovery
    a2a-protocol.org/agent-card: |
      card:
        endpoint: /.well-known/agent-card.json
        protocol: HTTP
        port: 8080
spec:
  replicas: 2
  selector:
    matchLabels:
      workload-type: agent
  template:
    metadata:
      name: agent-identity-pod
      annotations:
        iam.gke.io/identity: "spiffe://TRUST_DOMAIN/*" # The trust domain from which to assign SPIFFE IDs.
        iam.gke.io/inject-podcertificates: "true" # Inject X.509 certificates and per-Pod private key into each Pod.
        iam.gke.io/spiffe-identity-type: "agent-identity" # Required for Agent Registry registration.
      labels:
        workload-type: agent
    spec:
      serviceAccountName: SERVICEACCOUNT_NAME
      containers:
      - name: agent
        image: python:3.11-slim
        command: ["sleep","infinity"]

Ganti TRUST_DOMAIN dengan domain tepercaya yang menerbitkan identitas untuk agen di project Anda. Nilai ini harus menggunakan salah satu sintaksis berikut, bergantung pada apakah project Anda berada dalam organisasi:

Project yang berada dalam organisasi: agents.global.org-ORGANIZATION_ID.system.id.goog, dengan ORGANIZATION_ID adalah ID organisasi.
Project yang tidak berada dalam organisasi: agents.global.proj-PROJECT_NUMBER.system.id.goog, dengan PROJECT_NUMBER adalah nomor project dari project cluster.

Deployment ini meminta identitas agen untuk beban kerja, menambahkan sertifikat X.509 per-Pod ke Pod, dan mendaftarkan agen di Agent Registry.

Membuat Deployment:

kubectl apply -f agent-identity-deployment.yaml

Verifikasi bahwa Pod sedang berjalan:

kubectl get pods -l workload-type=agent -n NAMESPACE_NAME

Memeriksa identitas agen yang ditetapkan

Setelah men-deploy workload yang meminta identitas agen, Anda dapat memverifikasi identitas dengan memeriksa sertifikat X.509. Jika Anda menonaktifkan penyisipan sertifikat, Anda bisa mendapatkan token identitas yang tidak terikat dari server metadata GKE untuk memeriksa kolom subjek, seperti yang dijelaskan dalam Mengautentikasi ke Google Cloud API.

Untuk membaca sertifikat X.509 di Pod, ikuti langkah-langkah berikut:

Periksa apakah Pod memiliki akses ke sertifikat X.509 dan kunci pribadi:
```
kubectl get pod POD_NAME -n NAMESPACE_NAME \
    -o=jsonpath='{range .spec.volumes[*]}{.name}{"\n"}{end}'
```
Ganti POD_NAME dengan nama Pod yang menggunakan Identitas Agen.

Outputnya mirip dengan hal berikut ini:
```
kube-api-access-bx86g
gke-workload-spiffe-credentials
```
Dalam output ini, volume gke-workload-spiffe-credentials adalah lokasi sertifikat yang disisipkan. Jika Anda tidak melihat volume ini, pastikan anotasi iam.gke.io/inject-podcertificates disetel ke nilai true dalam spesifikasi Pod.

Buat sesi shell interaktif di Pod:

kubectl exec -n NAMESPACE_NAME -it POD_NAME -- /bin/bash

Dalam sesi shell, cantumkan kredensial di volume gke-workload-spiffe-credentials:
```
ls -1 /var/run/secrets/workload-spiffe-credentials/
```
Outputnya mirip dengan hal berikut ini:
```
x509.credential-bundle.private-key.pem
TRUST_DOMAIN.spiffe-trust-bundle.pem
```
Outputnya menampilkan file berikut:
- x509.credential-bundle.private-key.pem: paket kredensial identitas agen, yang mencakup rantai sertifikat X.509 dan kunci pribadi yang unik untuk Pod. Paket kredensial ini digunakan untuk meminta token akses dan token ID serta untuk melakukan autentikasi ke API Google Cloud dengan menggunakan mTLS.
- TRUST_DOMAIN.spiffe-trust-bundle.pem: paket kepercayaan CA root, yang berisi sertifikat yang ditandatangani sendiri yang membentuk anchor kepercayaan untuk kredensial identitas agen. Paket kepercayaan ini terutama digunakan untuk memvalidasi sertifikat TLS dari workload lain selama handshake mTLS.

Untuk mendapatkan ID SPIFFE yang terkait dengan Pod, baca sertifikat X.509:

openssl x509 -in /var/run/secrets/workload-spiffe-credentials/x509.credential-bundle.private-key.pem -text -noout

Outputnya mirip dengan hal berikut ini:

Certificate:
    Data:
    # Multiple lines are omitted here
        X509v3 extensions:
            # Multiple lines are omitted here
            X509v3 Subject Alternative Name: critical
                URI:spiffe://agents.global.org-301928500920.system.id.goog/resources/container/projects/729788050015/locations/us-central1/clusters/cluster-2/ns/agent-identity-ns/sa/agent-identity-sa
    # Multiple lines are omitted here

Dalam output ini, nilai yang ada di kolom URI untuk kolom X509v3 Subject Alternative Name adalah ID SPIFFE agen.

Jika Pod agen Anda memiliki SPIFFE ID yang ditetapkan, permintaan Anda untuk identitas agen berhasil. Anda dapat menggunakan identitas yang ditetapkan untuk melakukan autentikasi ke berbagai alat dan layanan.