Integrate Developer Hub with a Google Cloud Storage bucket using Workload Identity Federation

Integrating Developer Hub with Google Cloud Storage (GCS) involves enabling the TechDocs plug-in to use a GCS bucket for storing and serving documentation. Next, we will explain the process for achieving this integration using Workload Identity Federation and address common pitfalls.

In this lesson, you will:

• Enable the TechDocs plug-in to use a GCS bucket.
• Integrate Developer Hub with Google Cloud Storage.

Service account impersonation

Before we get to the implementation, it is important to understand the function of service account impersonation. Service account impersonation on Google Cloud with Google Kubernetes Engine (GKE) allows workloads running in GKE clusters to act as specific service accounts to securely interact with Google Cloud resources. This is a critical part of managing identity and access in GKE clusters, ensuring workloads have the least privilege required while avoiding long-lived credentials. 

Service account impersonation works by using Workload Identity Federation in GKE. Workload Identity Federation is a feature in GKE that links a Kubernetes service account (KSA) to a Google service account (GSA), enabling workloads to use the GSA’s permissions without storing long-lived service account keys.

Instead of distributing keys, GKE uses identity tokens from Kubernetes to request temporary tokens from Google Cloud.

This is the token flow:

• A workload running in a pod within the cluster uses the KSA.
• GKE ensures that when the workload requests access to Google Cloud APIs, it uses the impersonated GSA credentials.
• Google Cloud authenticates the request using the GSA’s Identity and Access Management (IAM) permissions.

Before proceeding, ensure you have the following in place:

• Enable Workload Identity Federation for the GKE cluster (not required for autopilot clusters):

  gcloud container clusters update [CLUSTER_NAME] \ --workload-pool=[PROJECT_ID].svc.id.goog

• Create a Google service account (GSA) for the database/GCS. This account will facilitate secure authentication to Cloud SQL/GCS:

  gcloud iam service-accounts create ${GSA} --project=${PROJECT_ID}

• Assign the necessary bindings to enable authentication via Workload Identity Federation to the relevant Kubernetes service account on GKE.

  gcloud iam service-accounts add-iam-policy-binding ${GSA}@${PROJECT_ID}.iam.gserviceaccount.com \
      --role roles/iam.workloadIdentityUser \
      --member "serviceAccount:${PROJECT_ID}.svc.id.goog[${NAMESPACE}/${KSA}]"

• Annotate the Kubernetes service account (KSA) to associate it with the GSA:

  upstream:
    serviceAccount: 
      name: ${KSA}
      create: true
      annotations: 
        iam.gke.io/gcp-service-account: <GSA>@<PROJECT_ID>.iam.gserviceaccount.com

Step-by-step guide to integration

With those prerequisites satisfied, let’s move on to the integration itself. Follow these steps:

1. Create the GCS bucket to store your TechDocs documentation:

   gcloud storage buckets create gs://${BUCKET}

2. To assign permissions to the GSA, grant the GSA the necessary roles on the GCS bucket. 

   Object admin role for managing objects:

   gcloud storage buckets add-iam-policy-binding gs://${BUCKET} \
     --member "serviceAccount:${GSA}@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role "roles/storage.objectAdmin"

   Legacy bucket reader role (or a custom role) for bucket-level permissions storage.get.buckets:

   gcloud storage buckets add-iam-policy-binding gs://${BUCKET} \
     --member "serviceAccount:${GSA}@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role "roles/storage.legacyBucketReader"

3. The TechDocs plug-in is part of the default set of plug-ins in the Developer Hub image. To enable the TechDocs plug-in, add the following configuration under global.dynamic:

   plugins:
       - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-backend-dynamic
         disabled: false    

   Update the configuration to use the GCS bucket:

   upstream:
     techdocs:
       publisher:
         type: 'googleGcs'
         googleGcs:
           bucketName: <BUCKET>

4. Update the deployment:

   helm upgrade rhdh \
       openshift-helm-charts/redhat-developer-hub \
       --namespace ${NAMESPACE}\
       --values values-sample.yaml

Troubleshooting tips

To confirm the GSA is properly impersonated by the workload, you can inspect the metadata server from the pod:

curl -H "Metadata-Flavor: Google" http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/?recursive=true

Example output:

Defaulted container "backstage-backend" out of: backstage-backend, install-dynamic-plugins (init)
sh-5.1$ curl -H "Metadata-Flavor: Google" http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/?recursive=true
{"aliases":["default"],"email":"rhdh-gsa@openenv-vgrmc.iam.gserviceaccount.com","scopes":["https://www.googleapis.com/auth/cloud-platform","https://www.googleapis.com/auth/userinfo.email"]}

This command should display the GSA information, verifying the correct mapping of KSA to GSA.

Summary

Using Workload Identity Federation with a mapped GSA ensures secure, keyless authentication between your Developer Hub instance and the GCS bucket. This method requires careful configuration, and it is a best practice for secure and scalable cloud-native deployments.

By completing these steps, you can enable the TechDocs plug-in to seamlessly integrate with a GCS bucket, empowering your DevHub with robust documentation capabilities. In the next lesson, we will enable Developer Hub with Cloud SQL using Workload Identity Federation.