Mengonfigurasi workload identity federation dengan Kubernetes

Panduan ini menjelaskan cara menggunakan workload identity federation agar workload yang berjalan di Azure Kubernetes Service (AKS), Amazon Elastic Kubernetes Service, atau pada cluster Kubernetes yang dihosting sendiri dapat diautentikasi ke Google Cloud.

Dengan Kubernetes, Anda dapat mengonfigurasi cluster sehingga workload dapat memperoleh token akun layanan Kubernetes dari volume yang diproyeksikan. Dengan menyiapkan workload identity federation, Anda dapat mengizinkan workload menggunakan token akun layanan Kubernetes ini untuk melakukan autentikasi ke Google Cloud.

Jika Anda menggunakan GKE, gunakan Workload Identity, bukan mengonfigurasi workload identity federation.

Sebelum memulai

Sebelum mengonfigurasi workload identity federation, pastikan cluster Kubernetes Anda memenuhi kriteria berikut:

AKS

Pastikan cluster Anda memenuhi kriteria berikut:

Anda telah mengaktifkan fitur Penerbit OIDC.

Anda harus mengaktifkan fitur ini agar workload identity federation dapat mengakses metadata OpenID Connect dan JSON Web Key Set (JWKS) untuk cluster.

EKS

Anda tidak perlu melakukan perubahan apa pun dalam konfigurasi EKS.

Kubernetes

Pastikan cluster Anda memenuhi kriteria berikut:

Anda menjalankan Kubernetes 1.20 atau yang lebih baru.

Kubernetes versi sebelumnya menggunakan format token akun layanan berbeda yang tidak kompatibel dengan petunjuk dalam dokumen ini.
Anda telah mengonfigurasi kube-apiserver agar mendukung proyeksi volume token ServiceAccount.

Cluster tidak perlu dapat diakses melalui internet.

Mengonfigurasi workload identity federation

Anda hanya perlu melakukan langkah-langkah ini satu kali untuk setiap cluster Kubernetes. Anda kemudian dapat menggunakan workload identity pool dan penyedia workload identity yang sama untuk beberapa pod Kubernetes dan di beberapa project Google Cloud.

Untuk mulai mengonfigurasi workload identity federation lakukan hal berikut:

Di konsol Google Cloud, pada halaman pemilih project, pilih atau buat project Google Cloud.

Buka pemilih project

menggunakan project khusus untuk mengelola workload identity pool dan penyedia workload

Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.

Aktifkan API IAM, Resource Manager, Service Account Credentials, and Security Token Service.

Mengaktifkan API

Menentukan pemetaan dan kondisi atribut

Token akun layanan Kubernetes berisi beberapa klaim, termasuk yang berikut ini:

sub: Berisi namespace dan nama akun layanan-misalnya, system:serviceaccount:NAMESPACE:KSA_NAME, dengan NAMESPACE adalah namespace akun layanan dan KSA_NAME adalah nama akun layanan.
"kubernetes.io".namespace: Berisi namespace akun layanan
"kubernetes.io".serviceaccount.name: Berisi nama akun layanan
"kubernetes.io".pod.name: Berisi nama pod

Untuk menggunakan sub sebagai ID subjek (google.subject) di Google Cloud, gunakan pemetaan berikut:

google.subject=assertion.sub

Anda dapat memetakan atribut tambahan (opsional). Selanjutnya, Anda dapat merujuk ke atribut ini saat memberikan akses ke resource. Contoh:

google.subject=assertion.sub,
attribute.namespace=assertion['kubernetes.io']['namespace'],
attribute.service_account_name=assertion['kubernetes.io']['serviceaccount']['name'],
attribute.pod=assertion['kubernetes.io']['pod']['name']

Tentukan kondisi atribut (opsional). Kondisi atribut adalah ekspresi CEL yang dapat memeriksa atribut pernyataan dan atribut target. Jika kondisi atribut bernilai true untuk kredensial tertentu, kredensial tersebut akan diterima. Jika tidak, kredensial akan ditolak.

Anda dapat menggunakan kondisi atribut untuk membatasi akun layanan Kubernetes mana yang dapat menggunakan workload identity federation untuk mendapatkan token Google Cloud dengan masa berlaku pendek. Misalnya, kondisi berikut membatasi akses ke akun layanan Kubernetes dari namespace backend dan monitoring:

assertion['kubernetes.io']['namespace'] in ['backend', 'monitoring']

Membuat workload identity pool dan penyedia workload

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk mengonfigurasi workload identity federation, minta administrator Anda untuk memberikan peran IAM berikut pada project:

Admin Workload Identity Pool (roles/iam.workloadIdentityPoolAdmin)
Admin Akun Layanan (roles/iam.serviceAccountAdmin)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Atau, peran dasar Pemilik IAM (roles/owner) juga mencakup izin untuk mengonfigurasi penggabungan identitas. Anda tidak boleh memberikan peran dasar dalam lingkungan produksi, tetapi dapat memberikannya dalam lingkungan pengembangan atau pengujian.

Untuk membuat workload identity pool dan penyedia workload, lakukan hal berikut:

AKS

Tentukan URL penerbit cluster AKS Anda:
```
az aks show -n NAME -g RESOURCE_GROUP --query "oidcIssuerProfile.issuerUrl" -otsv
```
Ganti kode berikut:
- NAME: Nama cluster
- RESOURCE_GROUP: Grup resource cluster
Perintah ini menampilkan URL penerbit. Anda memerlukan URL penerbit di salah satu langkah berikut.

Jika perintah tersebut tidak menampilkan URL penerbit, pastikan Anda telah mengaktifkan fitur penerbit OIDC.
Buat workload identity pool baru:
```
gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"
```
Ganti kode berikut:
- POOL_ID: ID unik untuk pool
- DISPLAY_NAME: Nama pool
- DESCRIPTION: Deskripsi pool yang Anda pilih Deskripsi ini muncul saat Anda memberikan akses ke identitas pool.
Tambahkan cluster AKS sebagai penyedia workload identity pool:
```
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"
```
Ganti kode berikut:
- PROVIDER_ID: ID penyedia unik untuk workload identity pool yang Anda pilih.
- POOL_ID: ID workload identity pool yang telah Anda buat sebelumnya.
- ISSUER: URI penerbit yang telah Anda tentukan sebelumnya.
- MAPPINGS: Daftar yang dipisahkan koma untuk pemetaan atribut yang telah Anda buat sebelumnya dalam panduan ini.
- CONDITIONS: Kondisi atribut opsional yang telah Anda buat sebelumnya dalam panduan ini. Hapus parameter jika Anda tidak memiliki kondisi atribut.

EKS

Tentukan URL penerbit cluster EKS Anda:
```
aws eks describe-cluster --name NAME --query "cluster.identity.oidc.issuer" --output text
```
Ganti NAME dengan nama cluster.

Perintah ini menampilkan URL penerbit. Anda memerlukan URL penerbit di salah satu langkah berikut.
Buat workload identity pool baru:
```
gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"
```
Ganti kode berikut:
- POOL_ID: ID unik untuk pool
- DISPLAY_NAME: Nama pool
- DESCRIPTION: Deskripsi pool yang Anda pilih Deskripsi ini muncul saat Anda memberikan akses ke identitas pool.
Tambahkan cluster EKS sebagai penyedia workload identity pool:
```
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"
```
Ganti kode berikut:
- PROVIDER_ID: ID penyedia unik untuk workload identity pool yang Anda pilih.
- POOL_ID: ID workload identity pool yang telah Anda buat sebelumnya.
- ISSUER: URI penerbit yang telah Anda tentukan sebelumnya.
- MAPPINGS: Daftar yang dipisahkan koma untuk pemetaan atribut yang telah Anda buat sebelumnya dalam panduan ini.
- CONDITIONS: Kondisi atribut opsional yang telah Anda buat sebelumnya dalam panduan ini. Hapus parameter jika Anda tidak memiliki kondisi atribut.

Kubernetes

Hubungkan ke cluster Kubernetes Anda dan gunakan kubectl untuk menentukan URL penerbit cluster Anda:
```
kubectl get --raw /.well-known/openid-configuration | jq -r .issuer
```
Anda memerlukan URL penerbit di salah satu langkah berikut.
Download JSON Web Key Set (JWKS) cluster:
```
kubectl get --raw /openid/v1/jwks > cluster-jwks.json
```
Dalam salah satu langkah berikut, Anda perlu meng-upload JWKS sehingga workload identity federation dapat memverifikasi keaslian token akun layanan Kubernetes yang dikeluarkan oleh cluster Anda.
Buat workload identity pool baru:
```
gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"
```
Ganti kode berikut:
- POOL_ID: ID unik untuk pool
- DISPLAY_NAME: Nama pool
- DESCRIPTION: Deskripsi pool yang Anda pilih Deskripsi ini muncul saat Anda memberikan akses ke identitas pool.
Tambahkan cluster Kubernetes sebagai penyedia workload identity pool dan upload JWKS cluster:
```
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS" \
    --jwk-json-path="cluster-jwks.json"
```
Ganti kode berikut:
- PROVIDER_ID: ID penyedia unik untuk workload identity pool yang Anda pilih.
- POOL_ID: ID workload identity pool yang telah Anda buat sebelumnya.
- ISSUER: URI penerbit yang telah Anda tentukan sebelumnya.
- MAPPINGS: Daftar yang dipisahkan koma untuk pemetaan atribut yang telah Anda buat sebelumnya dalam panduan ini.
- CONDITIONS: Kondisi atribut opsional yang telah Anda buat sebelumnya dalam panduan ini. Hapus parameter jika Anda tidak memiliki kondisi atribut.
Catatan: Perintah ini tidak memvalidasi JWKS cluster. Jika format JWKS salah atau sudah tidak berlaku, upaya autentikasi berikutnya mungkin akan gagal disertai dengan pesan eror Error connecting to the given credential's issuer.

Mengautentikasi workload Kubernetes

Bagian ini menjelaskan cara mengonfigurasi workload Kubernetes untuk menggunakan workload identity federation.

Anda harus melakukan langkah-langkah ini satu kali untuk setiap workload Kubernetes yang memerlukan akses ke Google Cloud.

Buat sepasang akun layanan

Agar workload Kubernetes dapat diautentikasi ke Google Cloud, Anda memerlukan sepasang akun layanan:

Akun layanan Kubernetes yang Anda lampirkan ke pod Kubernetes
Akun layanan IAM yang dapat ditiru oleh workload Kubernetes menggunakan akun layanan Kubernetes yang terpasang.

Untuk membuat akun layanan, lakukan langkah berikut:

Buat akun layanan IAM yang merepresentasikan workload.

Akun layanan tidak perlu berada dalam project yang sama dengan workload identity pool.
```
gcloud iam service-accounts create SA_NAME
```
Ganti kode berikut:
- SA_NAME: Nama akun layanan
Buat akun layanan Kubernetes.
```
kubectl create serviceaccount KSA_NAME --namespace NAMESPACE
```
Ganti kode berikut:
- KSA_NAME: Nama akun layanan
- NAMESPACE: Namespace tempat membuat akun layanan
Beri akses akun layanan IAM ke resource yang Anda inginkan untuk diakses oleh workload Kubernetes.
Berikan peran Workload Identity User (roles/iam.workloadIdentityUser) ke identitas eksternal akun layanan Kubernetes:
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"
```
Ganti kode berikut:
- SERVICE_ACCOUNT_EMAIL: Alamat email akun layanan
- PROJECT_NUMBER: Nomor project dari project yang berisi workload identity pool
- POOL_ID: ID pool dari workload identity pool
- SUBJECT: Nilai yang diharapkan untuk atribut yang telah Anda petakan ke google.subject, misalnya system:serviceaccount:NAMESPACE:KSA_NAME.
Catatan: Anda harus menggunakan nomor project di ID anggota. Penggunaan ID project tidak didukung.

Men-deploy workload Kubernetes

Pada tahap ini, Anda akan men-deploy workload Kubernetes dan mengizinkannya menggunakan pasangan akun layanan:

Buat file konfigurasi kredensial:
```
gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --credential-source-file=/var/run/service-account/token \
    --credential-source-type=text \
    --output-file=credential-configuration.json
```
Ganti kode berikut:
- PROJECT_NUMBER: Nomor project dari project yang berisi workload identity pool
- POOL_ID: ID workload identity pool
- PROVIDER_ID: ID penyedia workload identity pool
- SERVICE_ACCOUNT_EMAIL: Alamat email akun layanan
File konfigurasi kredensial memungkinkan Library Klien Cloud, gcloud CLI, dan Terraform untuk menentukan hal berikut:
- Tempat Anda bisa memperoleh kredensial eksternal
- Workload identity pool dan penyedia workload identity yang akan digunakan
- Akun layanan yang akan ditiru identitasnya
Catatan: Tidak seperti kunci akun layanan, file konfigurasi kredensial tidak berisi kunci pribadi dan tidak perlu dirahasiakan. Detail mengenai file konfigurasi kredensial tersedia di https://google.aip.dev/auth/4117.
Impor file konfigurasi kredensial sebagai ConfigMap:
```
kubectl create configmap CONFIGMAP_NAME \
  --from-file credential-configuration.json \
  --namespace NAMESPACE
```
Ganti kode berikut:
- CONFIGMAP_NAME: Nama ConfigMap
- NAMESPACE: Namespace tempat membuat ConfigMap
Men-deploy workload dan mengizinkannya menggunakan akun layanan Kubernetes dan ConfigMap.

Buat manifes dan konfigurasikan sebagai berikut:
- Pasang volume project yang diproyeksikan sehingga workload dapat memperoleh token akun layanan Kubernetes dari file lokal. Konfigurasikan volume agar token akun layanan Kubernetes menggunakan audiens yang diharapkan oleh penyedia pool workload identity federation Anda.
- Pasang ConfigMap yang berisi file konfigurasi kredensial sehingga workload dapat mengakses konfigurasi yang diperlukan untuk menggunakan workload identity federation.
- Tambahkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS yang berisi jalur file konfigurasi kredensial sehingga workload dapat menemukan file tersebut.
Berikut adalah contoh manifes yang menggunakan akun layanan Kubernetes dan ConfigMap untuk mengizinkan Google Cloud CLI melakukan autentikasi ke Google Cloud:
```
apiVersion: v1
kind: Pod
metadata:
  name: example
  namespace: NAMESPACE
spec:
  containers:
  - name: example
    image: google/cloud-sdk:alpine
    command: ["/bin/sh", "-c", "gcloud auth login --cred-file $GOOGLE_APPLICATION_CREDENTIALS && gcloud auth list && sleep 600"]
    volumeMounts:
    - name: token
      mountPath: "/var/run/service-account"
      readOnly: true
    - name: workload-identity-credential-configuration
      mountPath: "/etc/workload-identity"
      readOnly: true
    env:
    - name: GOOGLE_APPLICATION_CREDENTIALS
      value: "/etc/workload-identity/credential-configuration.json"

  serviceAccountName: KSA_NAME
  volumes:
  - name: token
    projected:
      sources:
      - serviceAccountToken:
          audience: https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
          expirationSeconds: 3600
          path: token
  - name: workload-identity-credential-configuration
    configMap:
      name: CONFIGMAP_NAME
```
Anda dapat mengikuti pendekatan yang sama untuk mengizinkan alat dan workload yang menggunakan salah satu library klien berikut menemukan kredensial secara otomatis:
C++
Library Klien Google Cloud untuk C++ mendukung penggabungan workload identity sejak versi v2.6.0. Untuk menggunakan workload identity federation, Anda harus membangun library klien dengan gRPC versi 1.36.0 atau yang lebih baru.
Go
Library klien untuk Go mendukung penggabungan identitas jika menggunakan modul golang.org/x/oauth2 versi v0.0.0-20210218202405-ba52d332ba99 atau versi lebih baru.

Untuk memeriksa versi modul yang digunakan library klien Anda, jalankan perintah berikut:
```
cd $GOPATH/src/cloud.google.com/go
go list -m golang.org/x/oauth2
```
Java
Library klien untuk Java mendukung penggabungan identitas jika menggunakan artefak com.google.auth:google-auth-library-oauth2-http versi 0.24.0 atau versi lebih baru.

Untuk memeriksa versi artefak yang digunakan library klien Anda, jalankan perintah Maven berikut di direktori aplikasi Anda:
```
mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
```
Node.js
Library klien untuk Node.js mendukung workload identity federation jika menggunakan paket google-auth-library versi 7.0.2 atau versi lebih baru.

Untuk memeriksa versi paket yang digunakan library klien Anda, jalankan perintah berikut di direktori aplikasi Anda:
```
npm list google-auth-library
```
Saat membuat objek GoogleAuth, Anda dapat menentukan project ID atau mengizinkan GoogleAuth untuk otomatis menemukan project ID. Untuk otomatis menemukan project ID, akun layanan dalam file konfigurasi harus memiliki peran Browser (roles/browser), atau peran dengan izin yang setara, di project Anda. Untuk mengetahui detailnya, lihat README untuk paket google-auth-library.
Python
Library klien untuk Python mendukung penggabungan identitas jika menggunakan paket google-auth versi 1.27.0 atau versi lebih baru.

Untuk memeriksa versi paket yang digunakan library klien Anda, jalankan perintah berikut di lingkungan tempat paket diinstal:
```
pip show google-auth
```
Untuk menentukan project ID bagi klien autentikasi, Anda dapat menetapkan variabel lingkungan GOOGLE_CLOUD_PROJECT atau mengizinkan klien untuk otomatis menemukan project ID. Untuk otomatis menemukan project ID, akun layanan dalam file konfigurasi harus memiliki peran Browser (roles/browser), atau peran dengan izin yang setara, di project Anda. Untuk mengetahui detailnya, lihat panduan pengguna untuk paket google-auth.
gcloud
Untuk melakukan autentikasi menggunakan workload identity federation, gunakan perintah gcloud auth login:
```
gcloud auth login --cred-file=FILEPATH.json
```
Ganti FILEPATH dengan jalur file ke file konfigurasi kredensial.

Dukungan untuk workload identity federation di gcloud CLI tersedia di gcloud CLI versi 363.0.0 dan versi lebih baru.
Terraform
Penyedia Google Cloud mendukung workload identity federation jika Anda menggunakan versi 3.61.0 atau versi lebih baru:
```
terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 3.61.0"
    }
  }
}
```
gsutil
Untuk melakukan autentikasi menggunakan workload identity federation, gunakan salah satu metode berikut:

Saat Anda menggunakan gsutil bersamaan dengan gcloud, login seperti biasa:
```
gcloud auth login --cred-file=FILEPATH.json
```
Saat Anda menggunakan gsutil sebagai aplikasi command line mandiri, edit file .boto untuk menyertakan bagian berikut:
```
[Credentials]
gs_external_account_file = FILEPATH
```
Dalam kedua kasus tersebut, ganti FILEPATH dengan jalur file ke file konfigurasi kredensial.

Dukungan untuk workload identity federation di gsutil tersedia di gcloud CLI versi 379.0.0 dan versi lebih baru.
bq
Untuk melakukan autentikasi menggunakan workload identity federation, gunakan perintah gcloud auth login, sebagai berikut:
```
gcloud auth login --cred-file=FILEPATH.json
```
Ganti FILEPATH dengan jalur file ke file konfigurasi kredensial.

Dukungan untuk workload identity federation di bq tersedia di gcloud CLI versi 390.0.0 dan versi yang lebih baru.
(Opsional) Verifikasi bahwa autentikasi berfungsi dengan benar dengan menjalankan perintah berikut:
```
kubectl exec example --namespace NAMESPACE -- gcloud auth print-access-token
```

Langkah selanjutnya

Baca selengkapnya mengenai workload identity federation.
Pelajari praktik terbaik untuk menggunakan workload identity federation.
Lihat cara mengelola workload identity pool dan penyedia workload identity.

Mengonfigurasi workload identity federation dengan Kubernetes

Sebelum memulai

AKS

EKS

Kubernetes

Mengonfigurasi workload identity federation

Menentukan pemetaan dan kondisi atribut

Membuat workload identity pool dan penyedia workload

Peran yang diperlukan

AKS

EKS

Kubernetes

Mengautentikasi workload Kubernetes

Buat sepasang akun layanan

Men-deploy workload Kubernetes

C++

Go

Java

Node.js

Python

gcloud

Terraform

gsutil

bq

Langkah selanjutnya