Mengaktifkan Workload Identity Federation di AKS dan EKS

Version 1.14 (latest)

   Versi yang didukung:

• v1.14 (terbaru)                        
• v1.13                         
• v1.12                         
• v1.11                         
• Daftar versi yang didukung

   Versi yang tidak didukung:

• v1.10                                      
• v1.9                                         
• v1.8                                         
• v1.7                                         
• v1.6                                         
• v1.5                                         
• v1.4                                         
• v1.3                                         
• v1.2                                         
• v1.1                                         

Topik ini menjelaskan cara mengaktifkan Workload Identity Federation untuk penginstalan campuran Apigee di platform AKS dan EKS.

Untuk penginstalan di GKE, ikuti petunjuk di Mengaktifkan Workload Identity di GKE.

Ringkasan

Workload identity federation memungkinkan aplikasi yang berjalan di luar Google Cloud meniru akun layanan Google Cloud Platform menggunakan kredensial dari penyedia identitas eksternal.

Menggunakan workload identity federation dapat membantu Anda meningkatkan keamanan dengan memungkinkan aplikasi menggunakan mekanisme autentikasi yang disediakan oleh lingkungan eksternal dan dapat membantu mengganti kunci akun layanan.

Untuk ringkasan, lihat Praktik terbaik untuk menggunakan Workload Identity Federation.

Catatan: Komponen apigee-logger tidak mendukung Workload Identity Federation. Lihat masalah umum.

Menyiapkan Workload Identity Federation

Untuk menggunakan Workload Identity Federation dengan Apigee hybrid, konfigurasikan cluster terlebih dahulu, lalu terapkan fitur ke penginstalan Apigee hybrid.

Sebelum memulai

Petunjuk ini mengasumsikan bahwa Anda telah menyiapkan penginstalan Apigee hybrid. Akun layanan IAM dan akun layanan Kubernetes dibuat selama penginstalan awal. Lihat Gambaran Besar untuk mengetahui ringkasan penginstalan Apigee Hybrid.

Untuk penginstalan di AKS, pastikan Anda telah mengaktifkan penerbit OpenID Connect (OIDC). Anda harus mengaktifkan fitur ini agar Workload Identity Federation dapat mengakses metadata OpenID Connect dan JSON Web Key Set (JWKS) untuk cluster.

Konfigurasikan cluster Anda untuk menggunakan Workload Identity Federation.

1. Pastikan konfigurasi gcloud saat ini ditetapkan ke project ID Google Cloud Anda dengan perintah berikut:

   gcloud config get project

Jika diperlukan, tetapkan konfigurasi gcloud saat ini:

gcloud config set project PROJECT_ID

2. Aktifkan Security Token Service API:

   Pastikan Security Token Service API diaktifkan dengan perintah berikut:

   gcloud services list --enabled --project PROJECT_ID | grep sts.googleapis.com

   Jika API tidak diaktifkan:

   Konsol

   Enable the Security Token Service API.

   Enable the API

   Command line

   Aktifkan API dengan perintah berikut:

   gcloud services enable sts.googleapis.com --project PROJECT_ID

3. Buat workload identity pool dan penyedianya.

   Peran yang diperlukan

   Untuk mendapatkan izin yang Anda perlukan untuk mengonfigurasi Workload Identity Federation, minta administrator Anda untuk memberi Anda peran IAM berikut pada project:

   • Admin Workload Identity Pool (roles/iam.workloadIdentityPoolAdmin)
   • Service Account Admin (roles/iam.serviceAccountAdmin)

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

   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 Anda dapat memberikannya dalam lingkungan pengembangan atau pengujian.

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

   1. Tentukan URL penerbit cluster AKS Anda:

      AKS

      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 akan memerlukan URL penerbit di salah satu langkah berikut.

      Jika perintah tersebut tidak menampilkan URL penerbit, pastikan Anda telah mengaktifkan fitur penerbit OIDC.

      EKS

      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.

      Kubernetes lainnya

      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. Opsional: Jika penerbit OIDC Anda tidak dapat diakses secara publik, download JSON Web Key Set (JWKS) cluster:
      Catatan: Langkah ini memerlukan akses kubectl ke cluster Anda.
      Tips: Saat menggunakan file JWKS, Anda harus mengupload file JWKS baru setiap kali memutar kunci penandatanganan untuk cluster.

      kubectl get --raw /openid/v1/jwks > cluster-jwks.json
      

      Untuk memeriksa apakah penyedia OIDC tersedia untuk publik, Anda harus dapat mengakses URL penyedia dengan perintah CURL dan menerima respons 200.

   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: (Opsional) Nama kumpulan.
      • DESCRIPTION: (Opsional) Deskripsi kumpulan yang Anda pilih. Deskripsi ini muncul saat Anda memberikan akses ke identitas kumpulan.

      Contoh:

      gcloud iam workload-identity-pools create my-wi-pool --display-name="My workload pool" --description="My workload pool description"

   4. Tambahkan cluster sebagai penyedia workload identity pool. Pilih perintah untuk membuat penyedia, bergantung pada apakah penerbit OIDC Anda dapat diakses secara publik atau tidak dapat diakses secara publik:

      Dapat diakses secara publik

      Jika penerbit OIDC Anda dapat diakses secara publik, buat penyedia dengan perintah berikut:

      gcloud iam workload-identity-pools providers create-oidc WORKLOAD_PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="ISSUER" \
        --attribute-mapping="google.subject=assertion.sub"

      Tidak dapat diakses secara publik

      Jika penerbit OIDC Anda tidak dapat diakses secara publik, buat penyedia dengan perintah berikut:

        gcloud iam workload-identity-pools providers create-oidc WORKLOAD_PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="ISSUER" \
        --jwks-file="cluster-jwks.json" \
        --attribute-mapping="google.subject=assertion.sub"

      Catatan: Jika memutar kunci, Anda harus mengupload JWKS baru dengan setiap rotasi kunci.

      Perintah ini tidak memvalidasi JWKS cluster. Jika format JWKS salah atau sudah tidak berlaku, upaya autentikasi berikutnya mungkin akan gagal dengan pesan error Error connecting to the given credential's issuer.

      Ganti kode berikut:

      • WORKLOAD_PROVIDER_ID: ID penyedia workload identity pool unik yang Anda pilih.
      • POOL_ID: ID workload identity pool yang telah Anda buat sebelumnya.
      • ISSUER: Gunakan URL penerbit yang telah Anda tentukan sebelumnya untuk URI penerbit .

      attribute-mapping="google.subject=assertion.sub" memetakan subjek Kubernetes ke subjek IAM.

Membuat file konfigurasi kredensial

Untuk men-deploy workload Kubernetes yang dapat mengakses resource Google Cloud , Anda harus membuat file konfigurasi kredensial untuk setiap akun layanan IAM terlebih dahulu:

1. Cantumkan akun layanan IAM (juga disebut "akun layanan Google") dengan perintah berikut:

   gcloud iam service-accounts list --project PROJECT_ID

   Catatan: Anda kemungkinan besar telah membuat akun layanan IAM (juga disebut "akun layanan Google") selama penginstalan awal Apigee hybrid dengan alat create-service-account. Lihat Tentang akun layanan untuk mengetahui daftar akun layanan IAM yang diperlukan oleh Apigee hybrid. Lihat Langkah 4: Buat akun layanan untuk mengetahui prosedur panduan penginstalan guna membuat akun layanan IAM.

   Anda harus membuat file konfigurasi kredensial untuk akun layanan IAM berikut:

   Prod

   Untuk lingkungan produksi:

   DISPLAY NAME         EMAIL                                                      DISABLED
   apigee-cassandra     apigee-cassandra@my_project_id.iam.gserviceaccount.com     False
   apigee-mart          apigee-mart@my_project_id.iam.gserviceaccount.com          False
   apigee-metrics       apigee-metrics@my_project_id.iam.gserviceaccount.com       False
   apigee-runtime       apigee-runtime@my_project_id.iam.gserviceaccount.com       False
   apigee-synchronizer  apigee-synchronizer@my_project_id.iam.gserviceaccount.com  False
   apigee-udca          apigee-udca@my_project_id.iam.gserviceaccount.com          False
   apigee-watcher       apigee-watcher@my_project_id.iam.gserviceaccount.com       False
   

   Non-prod

   Untuk lingkungan non-produksi:

   DISPLAY NAME         EMAIL                                                      DISABLED
   apigee-non-prod      apigee-non-prod@my_project_id.iam.gserviceaccount.com      False
   

   Tips: Jika Anda memiliki nama kustom untuk akun layanan yang tidak sesuai dengan nama komponen Apigee, Anda dapat menentukan peran setiap akun layanan dengan memeriksa peran yang ditetapkan dan membandingkan peran tersebut dengan peran yang direkomendasikan di Tentang akun layanan.

   Gunakan perintah berikut untuk memeriksa peran yang ditetapkan ke akun layanan:

   gcloud projects get-iam-policy PROJECT_ID  \
     --flatten="bindings[].members" \
     --format='table(bindings.role)' \
     --filter="SERVICE_ACCOUNT_NAME"

   Perhatikan akun layanan kustom yang sesuai dengan setiap SA IAM yang tercantum dalam daftar sebelumnya.

2. Buat file konfigurasi kredensial untuk setiap akun layanan IAM dalam daftar sebelumnya. Anda memerlukan file konfigurasi kredensial ini untuk mengonfigurasi Apigee hybrid agar dapat menggunakan Workload Identity Federation:

   Kode

   gcloud iam workload-identity-pools create-cred-config \
     projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID \
     --service-account=SERVICE_ACCOUNT_EMAIL \
     --credential-source-file=/var/
     --credential-source-type=text \
     --output-file=SERVICE_ACCOUNT_NAME-credential-configuration.json
     

   Contoh

   gcloud iam workload-identity-pools create-cred-config \
     projects/123123123123/locations/global/workloadIdentityPools/my-wi-pool/providers/my-wi-provider \
     --service-account=[e-mail] \
     --credential-source-file=/var/
     --credential-source-type=text \
     --output-file=apigee-cassandra-credential-configuration.json
     

   Dengan keterangan:

   • PROJECT_NUMBER: Nomor project dari project yang berisi workload identity pool. Ini harus berupa nomor project, bukan project ID.
   • POOL_ID: ID workload identity pool
   • WORKLOAD_PROVIDER_ID: ID penyedia workload identity pool
   • SERVICE_ACCOUNT_EMAIL: Alamat email akun layanan, jika Anda mengonfigurasi ServiceAccount Kubernetes untuk menggunakan peniruan identitas akun layanan IAM.
   Penting: credential-source-type harus ditetapkan ke text.
   Catatan: Jangan membuat file konfigurasi kredensial untuk akun layanan apigee-logger.

   File konfigurasi kredensial memungkinkan [Library Klien Cloud](/apis/docs/cloud-client-libraries), gcloud CLI, dan Terraform menentukan hal berikut:

   • Tempat Anda bisa memperoleh kredensial eksternal
   • Workload identity pool dan penyedia workload identity yang akan digunakan
   • Akun layanan yang akan ditiru
   Catatan: Tidak seperti kunci akun layanan, file konfigurasi kredensial tidak berisi kunci pribadi dan tidak perlu dirahasiakan. Detail tentang file konfigurasi kredensial tersedia di https://google.aip.dev/auth/4117.

   Mengonfigurasi Apigee hybrid untuk menggunakan Workload Identity Federation

   Tips: Anda dapat mengonfigurasi penginstalan campuran untuk menggunakan Workload Identity Federation untuk komponen mana pun atau semua komponen. Misalnya, UDCA dapat menggunakan Workload Identity Federation, sedangkan Synchronizer menggunakan akun layanan Google IAM atau sebaliknya.
   1. Salin atau pindahkan setiap file output (SERVICE_ACCOUNT_NAME-credential-configuration.json) ke direktori diagram berikut (atau subdirektorinya). Ini adalah file yang Anda buat di langkah Membuat file konfigurasi kredensial.

      Prod

      Akun layanan	Direktori diagram Helm Apigee
      apigee-cassandra	apigee-datastore/
      apigee-mart	apigee-org/
      apigee-metrics	apigee-telemetry/
      apigee-runtime	apigee-env/
      apigee-synchronizer	apigee-env/
      apigee-udca	apigee-org/ apigee-env/
      apigee-watcher	apigee-org/

      Non-prod

      Akun layanan	Diagram Helm Apigee
      apigee-non-prod	apigee-datastore/ apigee-telemetry/ apigee-org/ apigee-env/

   2. Lakukan perubahan global berikut pada file penggantian cluster Anda:

      Kode

      gcp:
        workloadIdentity:
          enabled: false # must be set to false to use Workload Identity Federation
        federatedWorkloadIdentity:
          enabled: true
          audience: "AUDIENCE"
          credentialSourceFile: "/var/run/service-account/token"
      

      Contoh

      gcp:
        workloadIdentity:
          enabled: false
        federatedWorkloadIdentity:
          enabled: true
          audience: "//iam.googleapis.com/projects/123123123123/locations/global/workloadIdentityPools/my-wi-pool/providers/my-wi-provider"
          credentialSourceFile: "/var/run/service-account/token"
      

      Catatan: Lihat

      • gcp.workloadIdentity.enabled
      • gcp.federatedWorkloadIdentity.enabled
      • gcp.federatedWorkloadIdentity.audience
      • gcp.federatedworkloadIdentity.credentialSourceFile

      Dengan: AUDIENCE adalah audiens yang diizinkan dari Penyedia Workload Identity. Anda dapat menemukan nilainya dengan menelusuri istilah audience: di salah satu file konfigurasi kredensial. Nilai audiens sama di setiap file konfigurasi kredensial.

      Misalnya, dalam contoh file apigee-udca-credential-configuration.json berikut:

      {
        "universe_domain": "googleapis.com",
        "type": "external_account:,"
        "audience": "//iam.googleapis.com/projects/123123123123/locations/global/workloadIdentityPools/my-wi-pool/providers/my-wi-provider",
        "subject_token_type": "urn:ietf:params:oauth: token-type:jwt",
        "token_url": "https://sts.googleapis.com/v1/token",
        "service
        "impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/[e-mail]:generateAccessToken",
        "credential_source": {
          "file": "/var/run/service-account/token",
          "format": {
            "type": "text"
          }
        }
      }

      Nilai audiens adalah //iam.googleapis.com/projects/123123123123/locations/global/workloadIdentityPools/my-wi-pool/providers/my-wi-provider.

   3. Konfigurasikan penggantian untuk setiap komponen menggunakan Workload Identity Federation. Pilih petunjuk untuk file sertifikat, secret Kubernetes, atau Vault yang sesuai untuk penginstalan Anda.

      File sertifikat

      Ganti nilai serviceAccountPath dengan file sumber kredensial untuk akun layanan IAM yang sesuai. Ini harus berupa jalur yang relatif terhadap direktori diagram. Contoh:

      envs:
      - name: ENVIRONMENT_NAME
        serviceAccountPaths:
          synchronizer: apigee-synchronizer-credential-configuration.json
          runtime: apigee-runtime-credential-configuration.json
          udca: udca-credential-configuration.json
      
      mart:
        serviceAccountPath: mart-credential-configuration.json
      
      connectAgent:
        serviceAccountPath: mart-credential-configuration.json
      
      metrics:
        serviceAccountPath: metrics-credential-configuration.json
      
      udca:
        serviceAccountPath: UDCA_SERVICE_ACCOUNT_FILEPATH
      
      watcher:
        serviceAccountPath: WATCHER_SERVICE_ACCOUNT_FILEPATH
      

      Rahasia K8s

      1. Buat secret Kubernetes baru menggunakan file sumber kredensial untuk setiap file konfigurasi kredensial.

         kubectl create secret -n APIGEE_NAMESPACE generic SECRET_NAME --from-file="client_secret.json=CREDENTIAL_CONFIGURATION_FILE"

         Contoh:

         kubectl create secret -n apigee generic udca-workoad-identity-secret --from-file="client_secret.json=./apigee-udca-credential-configuration.json"

      2. Ganti nilai serviceAccountRef dengan secret baru. Contoh:

         udca:
           serviceAccountRef: udca-workoad-identity-secret
         

      Vault

      Perbarui kunci akun layanan, SAKEY untuk setiap akun layanan di Vault dengan file sumber kredensial yang sesuai. Prosedurnya sama untuk semua komponen. Misalnya, untuk UDCA:

      SAKEY=$(cat .apigee-udca-credential-configuration.json); kubectl -n APIGEE_NAMESPACE exec vault-0 -- vault kv patch secret/apigee/orgsakeys udca="$SAKEY"

      Lihat Storing service account keys in Hashicorp Vault untuk mengetahui informasi selengkapnya.

   4. Terapkan perubahan pada setiap komponen yang terpengaruh dengan perintah helm upgrade:

      Jika Anda memperbarui kunci akun layanan Vault, perbarui diagram apigee-operator.

      helm upgrade operator apigee-operator/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        -f overrides.yaml
      

      Perbarui diagram lainnya yang terpengaruh dalam urutan berikut:

      helm upgrade datastore apigee-datastore/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        -f overrides.yaml
      

      helm upgrade telemetry apigee-telemetry/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        -f overrides.yaml
      

      helm upgrade $ORG_NAME apigee-org/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        -f overrides.yaml
      

      Perbarui diagram apigee-env untuk setiap env, dengan mengganti $ENV_RELEASE_NAME dan ENV_NAME setiap kali:

      helm upgrade $ENV_RELEASE_NAME apigee-env/ \
        --namespace APIGEE_NAMESPACE \
        --atomic \
        --set env=$ENV_NAME \
        -f overrides.yaml
      

      Lihat Referensi Helm Apigee hybrid untuk mengetahui daftar komponen dan diagram yang sesuai.

   Memberikan akses ke akun layanan Kubernetes

   1. Cantumkan akun layanan Kubernetes dengan perintah berikut:

      kubectl get sa -n APIGEE_NAMESPACE

      Catatan: Diagram campuran Apigee membuat akun layanan Kubernetes yang diperlukan untuk setiap komponen saat Anda menjalankan perintah helm upgrade.
      Penting: Anda tidak akan menggunakan setiap akun layanan Kubernetes yang tercantum oleh perintah ini.
   2. Berikan akses ke akun layanan Kubernetes untuk meniru identitas akun layanan IAM terkait seperti yang ditunjukkan dalam tabel berikut. Tabel ini menampilkan nama akun layanan IAM Apigee default. Jika Anda menggunakan nama akun layanan kustom, gunakan akun layanan IAM yang sesuai:

      Akun layanan Kubernetes	Akun layanan IAM
      Akun layanan Kubernetes tingkat organisasi
      apigee-connect-agent-ORG_NAME-ORG_HASH_ID	apigee-mart
      apigee-mart-ORG_NAME-ORG_HASH_ID	apigee-mart
      apigee-metrics-apigee-telemetry	apigee-metrics
      apigee-open-telemetry-collector-apigee-telemetry	apigee-metrics
      apigee-udca-ORG_NAME-ORG_HASH_ID	apigee-udca
      apigee-watcher-ORG_NAME-ORG_HASH_ID	apigee-watcher
      Akun layanan Kubernetes tingkat lingkungan
      apigee-runtime-ORG_NAME-ENV_NAME-ENV_HASH_ID	apigee-runtime
      apigee-synchronizer-ORG_NAME-ENV_NAME-ENV_HASH_ID	apigee-synchronizer
      Pencadangan dan pemulihan Cassandra (jika diaktifkan)
      apigee-cassandra-backup-sa	apigee-cassandra
      apigee-cassandra-restore-sa	apigee-cassandra

      Dengan keterangan:

      • ORG_NAME: 15 karakter pertama nama organisasi Anda.
      • ORG_HASH_ID: ID hash unik dari nama lengkap organisasi Anda.
      • ENV_NAME: 15 karakter pertama dari nama lingkungan Anda.
      • ENV_HASH_ID: ID hash unik dari nama organisasi dan lingkungan Anda.

      Contoh:

      • apigee-connect-agent-myhybridorg-123abcd
      • apigee-runtime-myhybridorg-prodenv-234bcde
      Penting: Anda harus mengulangi langkah ini untuk setiap lingkungan.

      Berikan akses ke setiap akun layanan Kubernetes untuk meniru identitas akun layanan IAM yang sesuai dengan perintah berikut:

      gcloud iam service-accounts add-iam-policy-binding \
        IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
          --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/MAPPED_SUBJECT" \
          --role=roles/iam.workloadIdentityUser

      Dengan keterangan:

      • IAM_SA_NAME: nama akun layanan.
      • PROJECT_ID: ID project yang dikaitkan dengan Org Apigee.
      • PROJECT_NUMBER: nomor project dari project tempat Anda membuat workload identity pool.
      • POOL_ID: ID workload identity pool.
      • MAPPED_SUBJECT: ServiceAccount Kubernetes dari klaim dalam token ID yang Anda petakan ke google.subject. Misalnya, jika Anda memetakan google.subject=assertions.sub dan token ID Anda berisi "sub": "system:serviceaccount:default:my-kubernetes-serviceaccount", MAPPED_SUBJECT adalah system:serviceaccount:default:my-kubernetes-serviceaccount.
      Catatan: Anda harus menggunakan nomor project di ID anggota. Penggunaan project ID tidak didukung.

   Untuk informasi selengkapnya tentang Workload Identity Federation dan praktik terbaik, lihat Praktik terbaik untuk menggunakan workload identity federation.