Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Membuat dan memberikan peran ke agen layanan

Di Google Cloud, agen layanan level project, folder, dan organisasi dibuat secara otomatis saat Anda mengaktifkan dan menggunakan layananGoogle Cloud . Terkadang, agen layanan ini juga secara otomatis diberi peran yang memungkinkan mereka untuk membuat dan mengakses resource atas nama Anda.

Jika perlu, Anda juga dapat meminta Google Cloud untuk membuat agen layanan level project, folder, dan organisasi bagi layanan sebelum Anda menggunakannya. Dengan meminta Google Cloud untuk membuat agen layanan, Anda dapat memberikan peran kepada agen layanan sebelum menggunakan layanan. Jika agen layanan belum dibuat, maka Anda tidak dapat memberikannya peran.

Opsi ini berguna jika Anda menggunakan salah satu strategi berikut untuk mengelola kebijakan izin:

Framework deklaratif seperti Terraform. Jika konfigurasi Terraform tidak menyertakan peran agen layanan, peran tersebut akan dicabut saat Anda menerapkan konfigurasi. Dengan membuat agen layanan dan memberikannya peran di konfigurasi Terraform, Anda memastikan peran ini tidak dicabut.
Sistem kebijakan sebagai kode yang menyimpan salinan kebijakan izin Anda saat ini di repositori kode. Jika Anda mengizinkan Google Cloud pemberian peran kepada agen layanan secara otomatis, peran tersebut akan muncul dalam kebijakan izin Anda yang sebenarnya, tetapi tidak dalam salinan kebijakan izin yang tersimpan. Untuk mengatasi inkonsistensi ini, Anda mungkin salah mencabut peran tersebut. Dengan membuat agen layanan dan memberikannya peran secara proaktif, Anda dapat mencegah penyimpangan antara repositori kode dan kebijakan izin yang sebenarnya.

Setelah memicu pembuatan agen layanan, Anda harus memberikan peran yang biasanya diberikan secara otomatis kepada agen layanan. Jika tidak, beberapa layanan mungkin tidak berfungsi dengan benar. Hal ini karena agen layanan yang dibuat atas permintaan pengguna tidak diberi peran secara otomatis.

Sebelum memulai

Aktifkan Resource Manager dan Workload Identity API.
Peran yang diperlukan untuk mengaktifkan API
Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.
Aktifkan API
Memahami agen layanan.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk membuat dan memberikan akses kepada agen layanan, minta administrator untuk memberi Anda peran IAM berikut pada project, folder, dan organisasi tempat Anda membuat agen layanan dan memberikan akses:

Mencantumkan layanan yang tersedia dan endpoint-nya: Service Usage Viewer (roles/serviceusage.serviceUsageViewer)
Aktifkan agen layanan: Workload Identity API Admin (roles/workloadidentity.admin)
Memberikan agen layanan akses ke project: Project IAM Admin (roles/resourcemanager.projectIamAdmin)
Memberikan agen layanan akses ke folder: Folder Admin (roles/resourcemanager.folderAdmin)
Memberikan agen layanan akses ke project, folder, dan organisasi: Admin Organisasi (roles/resourcemanager.organizationAdmin)

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

Peran bawaan ini berisi izin yang diperlukan untuk membuat dan memberikan akses ke agen layanan. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat dan memberikan akses kepada agen layanan:

Mencantumkan layanan yang tersedia dan endpoint-nya: serviceusage.services.list
Aktifkan agen layanan: workloadidentity.serviceAgents.create
Melihat operasi yang berjalan lama: workloadidentity.operations.get
Memberikan agen layanan akses ke project:
- resourcemanager.projects.getIamPolicy
- resourcemanager.projects.setIamPolicy
Memberikan agen layanan akses ke folder:
- resourcemanager.folders.getIamPolicy
- resourcemanager.folders.setIamPolicy
Memberikan agen layanan akses ke organisasi:
- resourcemanager.organizations.getIamPolicy
- resourcemanager.organizations.setIamPolicy

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Mengidentifikasi agen layanan yang akan dibuat

Untuk mengidentifikasi agen layanan yang perlu Anda buat dan resource yang perlu Anda buatkan agen layanannya, lakukan hal berikut:

Buat daftar layanan yang Anda gunakan dan endpoint API-nya. Untuk melihat semua layanan yang tersedia beserta endpoint-nya, gunakan salah satu metode berikut:
Konsol

Buka halaman API Library di konsol Google Cloud .

Buka Library API

Endpoint API adalah Nama layanan yang tercantum di bagian Detail tambahan.
gcloud

Perintah gcloud services list mencantumkan semua layanan yang tersedia untuk sebuah project.

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:
- EXPRESSION: Opsional. Ekspresi untuk memfilter hasil. Misalnya, ekspresi berikut memfilter semua layanan yang namanya berisi googleapis.com tetapi tidak berisi sandbox:
  name ~ googleapis.com AND name !~ sandbox
  Untuk daftar ekspresi filter, lihat gcloud topic filters.
- LIMIT: Opsional. Jumlah hasil maksimum yang akan ditampilkan. Dafaultnya adalah unlimited.
Jalankan perintah berikut:
Linux, macOS, atau Cloud Shell
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
Windows (PowerShell)
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
Windows (cmd.exe)

Catatan: Jika perintah ini menggunakan ' untuk mengutip konten, ganti tanda kutip tunggal dengan tanda kutip ganda. Jika kutipan bertingkat, gunakan \" untuk meng-escape tanda kutip dalam.
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
Respons ini berisi nama dan judul semua layanan yang tersedia. Endpoint API adalah nilai di kolom NAME.
REST

Metode Service Usage API services.list mencantumkan semua layanan yang tersedia untuk sebuah project.

Sebelum menggunakan salah satu dari data permintaan, lakukan penggantian berikut:
- RESOURCE_TYPE: Jenis resource yang ingin Anda cantumkan untuk layanan yang tersedia. Gunakan projects, folders, atau organizations.
- RESOURCE_ID: ID Google Cloud project, folder, atau organisasi yang ingin Anda cantumkan untuk layanan yang tersedia. Project ID adalah string alfanumerik, seperti my-project. Folder dan ID organisasi berupa numerik, seperti 123456789012.
- PAGE_SIZE: Opsional. Jumlah layanan yang akan disertakan dalam respons. Nilai defaultnya adalah 50 dan nilai maksimumnya adalah 200. Jika jumlah layanan lebih besar dari ukuran halaman, respons akan berisi token penomoran halaman yang dapat Anda gunakan untuk mengambil halaman hasil berikutnya.
- NEXT_PAGE_TOKEN: Opsional. Token penomoran halaman yang ditampilkan dalam respons sebelumnya dari metode ini. Jika ditentukan, daftar layanan akan dimulai dari tempat permintaan sebelumnya berakhir.
Metode HTTP dan URL:
GET https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN
Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:
curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Jalankan perintah berikut:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN"
PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Jalankan perintah berikut:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN" | Select-Object -Expand Content
Respons berisi nama dan judul semua layanan yang tersedia untuk resource. Jika jumlah layanan yang tersedia lebih besar dari ukuran halaman, respons juga berisi token penomoran halaman.

Endpoint API adalah nilai di kolom name.

Untuk setiap endpoint API yang akan Anda gunakan, buat daftar resource tempat Anda perlu membuat agen layanan endpoint tersebut:

Di halaman referensi agen layanan, telusuri setiap endpoint API untuk menemukan semua agen layanan untuk endpoint tersebut.

Beberapa endpoint mungkin tidak memiliki agen layanan terkait—Anda dapat melewati pemicuan pembuatan agen layanan untuk endpoint ini.

Untuk setiap agen layanan endpoint, gunakan alamat email agen layanan untuk menentukan tempat Anda perlu membuat agen layanan.

Placeholder di alamat email agen layanan menunjukkan tempat Anda perlu membuat agen layanan:

Placeholder	Tempat membuat agen layanan
`PROJECT_NUMBER`	Setiap project tempat Anda akan menggunakan layanan
`FOLDER_NUMBER`	Setiap folder tempat Anda akan menggunakan layanan
`ORGANIZATION_NUMBER`	Setiap organisasi tempat Anda akan menggunakan layanan

Untuk setiap endpoint, catat setiap resource unik tempat Anda perlu membuat agen layanan untuk endpoint tersebut.

Memicu pembuatan agen layanan

Setelah mengetahui agen layanan yang perlu dibuat, Anda dapat meminta Google Cloud untuk membuatnya.

Saat meminta Google Cloud untuk membuat agen layanan, Anda perlu menyediakan layanan dan resource. Kemudian, Google Cloud membuat semua agen layanan untuk layanan dan resource tersebut.

Selama langkah ini, jika Anda menggunakan gcloud CLI atau REST API, Anda juga dapat membuat daftar peran yang perlu diberikan kepada setiap agen layanan. Anda akan menggunakan informasi ini untuk memberikan peran kepada agen layanan. Jika Anda menggunakan Terraform, Anda tidak perlu melacak peran yang diperlukan secara manual karena Anda dapat mereferensikan peran secara terprogram.

gcloud

Gunakan perintah gcloud workload-identity service-agents generate untuk membuat agen layanan untuk setiap endpoint dan resource yang Anda identifikasi di Mengidentifikasi agen layanan yang akan dibuat.

Setiap kali Anda menjalankan perintah, tinjau responsnya. Untuk setiap peran dalam respons, catat alamat email agen layanan yang harus diberi peran tersebut. Anda akan menggunakan informasi ini untuk memberikan peran kepada agen layanan.

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

ENDPOINT: Endpoint API yang diinginkan untuk membuat agen layanan, misalnya, aiplatform.googleapis.com.
RESOURCE_TYPE: Jenis resource yang ingin Anda buatkan agen layanannya. Gunakan project, folder, atau organization.
RESOURCE_ID: ID numerik project, folder, atau organisasi yang ingin Anda buat agen layanannya. Google CloudMisalnya, 123456789012.

Anda dapat membuat agen layanan untuk satu resource pada satu waktu. Jika Anda perlu membuat agen layanan untuk beberapa resource, jalankan perintah satu kali untuk setiap resource.

Jalankan perintah berikut:

Linux, macOS, atau Cloud Shell

gcloud workload-identity service-agents generate --service="ENDPOINT" \
    --location="global" --RESOURCE_TYPE="RESOURCE_ID"

Windows (PowerShell)

gcloud workload-identity service-agents generate --service="ENDPOINT" `
    --location="global" --RESOURCE_TYPE="RESOURCE_ID"

Windows (cmd.exe)

gcloud workload-identity service-agents generate --service="ENDPOINT" ^
    --location="global" --RESOURCE_TYPE="RESOURCE_ID"

Respons berisi daftar semua agen layanan yang dibuat. Untuk setiap agen layanan, respons mencantumkan resource yang dibuat untuknya, alamat email agen layanan, layanan yang terkait dengan agen layanan, dan status agen layanan. Jika agen layanan biasanya diberi peran tertentu, respons juga mencantumkan peran tersebut.

Peran yang tercantum tidak otomatis diberikan kepada agen layanan. Untuk setiap peran dalam respons, catat alamat email agen layanan yang harus diberi peran tersebut. Anda akan menggunakan informasi ini untuk memberikan peran kepada agen layanan.

Berikut adalah contoh respons yang dipangkas untuk pembuatan agen layanan untuk aiplatform.googleapis.com.

Provisioned service agents for aiplatform.googleapis.com under projects/123456789012:

container: projects/123456789012
principal: serviceAccount:service-123456789012@gcp-sa-aiplatform.iam.gserviceaccount.com
role: roles/aiplatform.serviceAgent
serviceProducer: aiplatform.googleapis.com
state: ACTIVE
----
container: projects/123456789012
principal: serviceAccount:service-123456789012@gcp-ri-aiplatform.iam.gserviceaccount.com
serviceProducer: aiplatform.googleapis.com
state: ACTIVE
----
...
----
container: projects/123456789012
principal: serviceAccount:service-123456789012@gcp-sa-vertex-vtc.iam.gserviceaccount.com
role: roles/aiplatform.trainingClusterServiceAgent
serviceProducer: aiplatform.googleapis.com
state: ACTIVE
----

Terraform

Untuk mempelajari cara menerapkan atau menghapus konfigurasi Terraform, lihat Perintah dasar Terraform. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi penyedia Terraform.

Gunakan resource google_workload_identity_service_agent untuk memicu pembuatan agen layanan bagi setiap endpoint dan resource yang Anda identifikasi di Mengidentifikasi agen layanan yang akan dibuat.

Misalnya, jika ingin membuat semua agen layanan level project untuk BigQuery di project default, Anda dapat menambahkan kode berikut ke konfigurasi Terraform:

data "google_project" "default" {
}

# Create all project-level bigquery.googleapis.com service agents
resource "google_workload_identity_service_agent" "primary" {
  parent = "projects/${data.google_project.default.number}/locations/global/serviceProducers/bigquery.googleapis.com"
}

REST

Untuk setiap endpoint yang perlu Anda buatkan agen layanannya, lakukan hal berikut:

Buat agen layanan untuk setiap resource yang Anda identifikasi di Mengidentifikasi agen layanan yang akan dibuat:

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- RESOURCE_TYPE: Jenis resource yang ingin Anda buatkan agen layanannya. Gunakan projects, folders, atau organizations.
- RESOURCE_NUMERIC_ID: ID numerik Google Cloud project, folder, atau organisasi yang ingin Anda buat agen layanannya. Misalnya, 123456789012.
  
  Anda dapat membuat agen layanan untuk satu resource pada satu waktu. Jika Anda perlu membuat agen layanan untuk beberapa resource, kirim satu permintaan untuk setiap resource.
- ENDPOINT: Endpoint API yang diinginkan untuk membuat agen layanan, misalnya, aiplatform.googleapis.com.
Metode HTTP dan URL:
```
POST https://workloadidentity.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_NUMERIC_ID/locations/global/serviceProducers/ENDPOINT:generateServiceAgents
```
Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:
curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Jalankan perintah berikut:
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://workloadidentity.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_NUMERIC_ID/locations/global/serviceProducers/ENDPOINT:generateServiceAgents"
```
PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Jalankan perintah berikut:
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://workloadidentity.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_NUMERIC_ID/locations/global/serviceProducers/ENDPOINT:generateServiceAgents" | Select-Object -Expand Content
```
Responsnya berisi Operation yang menunjukkan status permintaan Anda. Contoh:
```
{
  "name": "projects/123456789012/locations/global/operations/operation-1775250941060-64e94d1baa76d-1aa958f3-07b2ea9c",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.OperationMetadata",
    "createTime": "2026-04-03T21:15:41.367155118Z",
    "target": "projects/123456789012/locations/global/serviceProducers/bigquery.googleapis.com",
    "verb": "passthroughLro",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}
```

Mendapatkan respons dari operasi yang telah selesai. Untuk setiap peran dalam respons, catat alamat email agen layanan yang harus diberi peran tersebut. Anda akan menggunakan informasi ini untuk memberikan peran kepada agen layanan.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

OPERATION_NAME: Nama operasi generateServiceAgents. Salin nilai ini dari kolom name respons serviceProducers.generateServiceAgents. Contoh: projects/123456789012/locations/global/operations/operation-1775250941060-64e94d1baa76d-1aa958f3-07b2ea9c
PROJECT_ID: Project ID Google Cloud Anda. Project ID adalah string alfanumerik, seperti my-project.

Metode HTTP dan URL:

GET https://workloadidentity.googleapis.com/v1/OPERATION_NAME

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://workloadidentity.googleapis.com/v1/OPERATION_NAME"

PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://workloadidentity.googleapis.com/v1/OPERATION_NAME" | Select-Object -Expand Content

APIs Explorer (browser)

Buka halaman referensi metode. Panel APIs Explorer terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Lengkapi kolom yang wajib diisi, lalu klik Jalankan.

Operasi yang sedang berlangsung akan menampilkan respons seperti berikut:

{
  "name": "projects/123456789012/locations/global/operations/operation-1775258415970-64e968f44b91a-28fcf2f5-38367cfe",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.OperationMetadata",
    "createTime": "2026-04-03T23:20:15.982631253Z",
    "target": "projects/123456789012/locations/global/serviceProducers/aiplatform.googleapis.com",
    "verb": "passthroughLro",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Operasi yang selesai akan menampilkan respons yang berisi daftar agen layanan yang dibuat. Untuk setiap agen layanan, respons mencantumkan resource yang dibuat untuknya, alamat email agen layanan, layanan yang terkait dengan agen layanan, dan status agen layanan. Jika agen layanan biasanya diberi peran tertentu, respons juga mencantumkan peran tersebut.

Berikut adalah contoh respons yang dipangkas untuk pembuatan agen layanan untuk aiplatform.googleapis.com.

{
  "name": "projects/123456789012/locations/global/operations/operation-1775258415970-64e968f44b91a-28fcf2f5-38367cfe",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.OperationMetadata",
    "createTime": "2026-04-03T23:20:15.982631253Z",
    "endTime": "2026-04-03T23:20:17.315225515Z",
    "target": "projects/123456789012/locations/global/serviceProducers/aiplatform.googleapis.com",
    "verb": "passthroughLro",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.GenerateServiceAgentsResponse",
    "serviceAgents": [
      {
        "container": "projects/123456789012",
        "serviceProducer": "aiplatform.googleapis.com",
        "principal": "serviceAccount:service-123456789012@gcp-sa-aiplatform.iam.gserviceaccount.com",
        "role": "roles/aiplatform.serviceAgent",
        "state": "ACTIVE"
      },
      {
        "container": "projects/123456789012",
        "serviceProducer": "aiplatform.googleapis.com",
        "principal": "serviceAccount:service-123456789012@gcp-ri-aiplatform.iam.gserviceaccount.com",
        "state": "ACTIVE"
      },
      ...
      {
        "container": "projects/123456789012",
        "serviceProducer": "aiplatform.googleapis.com",
        "principal": "serviceAccount:service-123456789012@gcp-sa-vertex-vtc.iam.gserviceaccount.com",
        "role": "roles/aiplatform.trainingClusterServiceAgent",
        "state": "ACTIVE"
      }
    ]
  }
}

Memberikan peran ke agen layanan

Setelah Google Cloud membuat agen layanan yang diperlukan untuk project, folder, dan organisasi Anda, gunakan alamat email agen layanan untuk memberikannya peran.

Jika Anda meminta Google Cloud untuk membuat agen layanan, Anda harus memberikan peran yang biasanya diberikan secara otomatis kepada agen layanan tersebut. Jika tidak, beberapa layanan mungkin tidak berfungsi dengan benar. Hal ini karena agen layanan yang dibuat atas permintaan pengguna tidak diberi peran secara otomatis.

Konsol

Gunakan daftar peran dan agen layanan yang Anda buat di Memicu pembuatan agen layanan untuk mengidentifikasi agen layanan mana yang perlu diberi peran. Untuk setiap agen layanan yang memerlukan peran, lakukan hal berikut:

Di konsol Google Cloud , buka halaman IAM.

Buka IAM
Pilih project, folder, atau organisasi tempat Anda membuat agen layanan.
Klik Grant Access, lalu masukkan alamat email agen layanan.
Klik Pilih peran, lalu masukkan nama peran atau izin untuk memfilter peran yang akan diberikan. Untuk mengikuti prinsip hak istimewa terendah, pilih peran yang hanya menyertakan izin yang diperlukan oleh akun utama Anda.
Klik Simpan. Agen layanan diberi peran pada resource.

gcloud

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

RESOURCE_TYPE: Jenis resource yang aksesnya ingin Anda kelola. Gunakan projects, resource-manager folders, atau organizations.
RESOURCE_ID: Project, folder, atau ID organisasi Anda. Google Cloud Project ID berupa alfanumerik, seperti my-project. Folder dan ID organisasi berupa numerik, seperti 123456789012.
PRINCIPAL: Alamat email agen layanan yang ingin Anda beri akses, diawali dengan serviceAccount:. Misalnya, serviceAccount:service-0123456789012@gcp-sa-aiplatform-cc.iam.gserviceaccount.com.
ROLE_NAME: Nama peran yang ingin Anda berikan kepada agen layanan.

Jalankan perintah berikut:

Linux, macOS, atau Cloud Shell

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
    --member=PRINCIPAL --role=ROLE_NAME \
    --condition=CONDITION

Windows (PowerShell)

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID `
    --member=PRINCIPAL --role=ROLE_NAME `
    --condition=CONDITION

Windows (cmd.exe)

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID ^
    --member=PRINCIPAL --role=ROLE_NAME ^
    --condition=CONDITION

Respons berisi kebijakan izin IAM yang telah diperbarui.

Terraform

Untuk mempelajari cara menerapkan atau menghapus konfigurasi Terraform, lihat Perintah dasar Terraform. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi penyedia Terraform.

Untuk memberikan peran kepada agen layanan, lakukan hal berikut:

Untuk setiap resource google_workload_identity_service_agent, berikan peran apa pun yang terkait dengan agen layanan.

Misalnya, jika Anda ingin memberikan peran kepada semua agen layanan untuk resource google_workload_identity_service_agent.primary, Anda dapat menambahkan kode berikut ke konfigurasi Terraform:

# Grant roles to BigQuery service agents for project
resource "google_project_iam_member" "service_agents" {
  for_each = {
    for i, agent in google_workload_identity_service_agent.primary.service_agents :
    i => agent if try(agent.role, "") != ""
  }
  project = data.google_project.default.project_id
  role    = each.value.role
  member  = each.value.principal
}

Jalankan perintah terraform apply yang ditargetkan untuk resource google_workload_identity_service_agent yang Anda tambahkan di bagian Memicu pembuatan agen layanan di halaman ini.
Misalnya, jika Anda menambahkan resource bernama google_workload_identity_service_agent.primary, Anda akan menjalankan perintah berikut:
```
terraform apply target="google_workload_identity_service_agent.primary"
```
Menjalankan perintah ini memastikan bahwa resource google_project_iam_member dapat mereferensikan resource agen layanan tanpa mengalami error Known After Apply.
Jalankan perintah terraform plan untuk konfigurasi Terraform Anda. Perintah ini menunjukkan rencana eksekusi untuk memberikan peran kepada agen layanan. Jika rencana eksekusi sudah sesuai, jalankan terraform apply untuk menerapkan rencana.

REST

Gunakan daftar peran dan agen layanan yang Anda buat di Memicu pembuatan agen layanan untuk mengidentifikasi agen layanan mana yang perlu diberi peran. Untuk memberikan peran kepada agen layanan, gunakan pola baca-ubah-tulis guna memperbarui kebijakan izin resource:

Baca kebijakan izin saat ini dengan memanggil getIamPolicy.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- API_VERSION: Versi API yang akan digunakan. Untuk project dan organisasi, gunakan v1. Untuk folder, gunakan v2.
- RESOURCE_TYPE: Jenis resource yang ingin Anda kelola kebijakannya. Gunakan nilai projects, folders, atau organizations.
- RESOURCE_ID: Project, organisasi, atau folder ID Google CloudAnda. Project ID adalah string alfanumerik, seperti my-project. Folder dan ID organisasi bersifat numerik, seperti 123456789012.
- POLICY_VERSION: Versi kebijakan yang akan ditampilkan. Permintaan harus menentukan versi kebijakan terbaru, yaitu kebijakan versi 3. Lihat Menentukan versi kebijakan saat mendapatkan kebijakan untuk detailnya.
Metode HTTP dan URL:
```
POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy
```
Meminta isi JSON:
```
{
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}
```
Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:
curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy"
```
PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy" | Select-Object -Expand Content
```
APIs Explorer (browser)

Salin isi permintaan dan buka halaman referensi metode. Panel APIs Explorer terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Tempel isi permintaan di alat ini, lengkapi kolom wajib lainnya, lalu klik Jalankan.

Responsnya berisi kebijakan izin resource. Contoh:
```
{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/owner",
      "members": [
        "user:my-user@example.com"
      ]
    }
  ]
}
```
Untuk setiap agen layanan yang ingin Anda beri peran, buat binding peran yang memberikan peran yang diperlukan kepada agen layanan. Misalnya, binding peran berikut memberikan peran Vertex AI Custom Code Service Agent (roles/aiplatform.customCodeServiceAgent) kepada AI Platform Custom Code Service Agent:
```
  {
    "role": "roles/aiplatform.customCodeServiceAgent",
    "members": [
      "serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform-cc.iam.gserviceaccount.com",
    ]
  }
```
Jika kebijakan izin sudah memiliki binding peran untuk peran yang diperlukan, maka tambahkan agen layanan ke daftar members untuk binding peran tersebut.
Tulis kebijakan izin yang diperbarui dengan memanggil setIamPolicy.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- API_VERSION: Versi API yang akan digunakan. Untuk project dan organisasi, gunakan v1. Untuk folder, gunakan v2.
- RESOURCE_TYPE: Jenis resource yang ingin Anda kelola kebijakannya. Gunakan nilai projects, folders, atau organizations.
- RESOURCE_ID: Project, organisasi, atau folder ID Google CloudAnda. Project ID adalah string alfanumerik, seperti my-project. Folder dan ID organisasi bersifat numerik, seperti 123456789012.
- POLICY: Representasi JSON dari kebijakan yang ingin Anda tetapkan. Untuk informasi selengkapnya tentang format kebijakan, lihat referensi Kebijakan.
Metode HTTP dan URL:
```
POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy
```
Meminta isi JSON:
```
{
  "policy": POLICY
}
```
Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:
curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy"
```
PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy" | Select-Object -Expand Content
```
APIs Explorer (browser)

Salin isi permintaan dan buka halaman referensi metode. Panel APIs Explorer terbuka di sisi kanan halaman. Anda bisa berinteraksi dengan alat ini untuk mengirim permintaan. Tempelkan isi permintaan di alat ini, lengkapi kolom lainnya yang wajib diisi, lalu klik Jalankan.

Respons berisi kebijakan izin yang telah diperbarui.

Catatan: Jika Anda memperlakukan kebijakan sebagai kode dan menyimpannya di sistem kontrol versi, Anda harus menyimpan kebijakan yang ditampilkan, bukan kebijakan yang dikirim dalam permintaan.

Langkah selanjutnya

Lihat daftar semua agen layanan.
Pelajari cara lain untuk memberikan peran kepada akun utama.
Pelajari cara membuat akun layanan yang dikelola pengguna , yang dapat berfungsi sebagai identitas untuk workload Anda.
Pelajari lebih lanjut praktik terbaik untuk menggunakan Terraform di Google Cloud.
Pelajari semua Google Cloud contoh Terraform.

Membuat dan memberikan peran ke agen layanan Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Peran yang diperlukan

Izin yang diperlukan

Mengidentifikasi agen layanan yang akan dibuat

Konsol

gcloud

Linux, macOS, atau Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS, atau Cloud Shell)

PowerShell (Windows)

Memicu pembuatan agen layanan

gcloud

Linux, macOS, atau Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

curl (Linux, macOS, atau Cloud Shell)

PowerShell (Windows)

curl (Linux, macOS, atau Cloud Shell)

PowerShell (Windows)

APIs Explorer (browser)

Memberikan peran ke agen layanan

Konsol

gcloud

Linux, macOS, atau Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

curl (Linux, macOS, atau Cloud Shell)

PowerShell (Windows)

APIs Explorer (browser)

curl (Linux, macOS, atau Cloud Shell)

PowerShell (Windows)

APIs Explorer (browser)

Langkah selanjutnya

Membuat dan memberikan peran ke agen layanan