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:

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

    Buka pemilih project

  2. Sebaiknya Anda menggunakan project khusus untuk mengelola workload identity pool dan penyedia workload.
  3. Pastikan penagihan telah diaktifkan untuk project Google Cloud Anda.

  4. 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:

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

  1. 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.

  2. 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.
  3. 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

  1. 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.

  2. 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.
  3. 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

  1. 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.

  2. 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.

  3. 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.
  4. 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.

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:

  1. 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
  2. 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
  3. Beri akses akun layanan IAM ke resource yang Anda inginkan untuk diakses oleh workload Kubernetes.

  4. 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.

Men-deploy workload Kubernetes

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

  1. 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
  2. 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
  3. 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.

  4. (Opsional) Verifikasi bahwa autentikasi berfungsi dengan benar dengan menjalankan perintah berikut:

    kubectl exec example --namespace NAMESPACE -- gcloud auth print-access-token

Langkah selanjutnya