Skip to main content
Version: 1.25

Configure access to your GCP account using Workload ID

This guide walks you through configuring Google Cloud Platform (GCP) credentials for your Okteto instance to enable the commands in your Okteto Manifests to interact with your GCP account.

We will focus on requesting access to Cloud Storage. However, you can extend this approach to grant access to other GCP resources by specifying a role with the necessary permissions.

GCP credentials are configured using Workload Identity Federation. This provides secure and temporary access to your GCP resources.

Step 1: Create the Workload Identity Pool​

info

We recommend installing the Google Cloud CLI before following this tutorial

A Workload Identity Pool is a group of identities that can be used to access GCP resources.

First, choose a name for your Workload Identity Pool and export it as an environment variable:

export POOL_ID=okteto-pool

Next, create the Workload Identity Pool by running the following command:

gcloud iam workload-identity-pools create ${POOL_ID} --location=global --display-name="Okteto pool"

Step 2: Register the OIDC Identity Provider​

Within the newly created Workload Identity Pool, register your Kubernetes cluster as an OIDC Identity Provider in GCP. To do this, Okteto provides the OIDC endpoint of your cluster, which can be found in the General section of your Okteto Admin Dashboard.

OIDC configuration in admin general view

Store these values as environment variables, you will use them in the next steps:

export OIDC_ENDPOINT=https://container.googleapis.com/v1/projects/myProject/locations/us-central1/clusters/myCluster
export OKTETO_SERVICE_ACCOUNT=system:serviceaccount:okteto:okteto

The AUDIENCE is traditionally the client ID of the requester, and tokens will only be exchanged for these audiences. It corresponds to the aud field in the JWT payload. We recommend creating a unique audience for each Okteto instance and GCP region: For example:

export AUDIENCE=okteto.example.com/us-central1

Run the following command to create the identity provider:

gcloud iam workload-identity-pools providers create-oidc myCluster \
  --location=global \
  --workload-identity-pool=${POOL_ID} \
  --display-name="Okteto Identity Provider" \
  --attribute-mapping="google.subject=assertion.sub" \
  --issuer-uri="${OIDC_ENDPOINT}" \
  --allowed-audiences=${AUDIENCE}

Step 3: Create the IAM Policy Binding​

Now, grant the Okteto Kubernetes service account the permissions required to access the specified GCP resources.

First, retrieve the PROJECT_ID and PROJECT_NUMBER values from your Google Cloud project. You can get them by going to your Project's settings in the Google Cloud Console.

Next, set the following variables:

export PROJECT_ID=myProject-123
export PROJECT_NUMBER=118593354781
export PRINCIPAL=iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/subject/${OKTETO_SERVICE_ACCOUNT}

Finally, run the following command to bind the appropriate IAM role to the service account:

gcloud projects add-iam-policy-binding ${PROJECT_ID} --role=roles/storage.admin --member=principal://${PRINCIPAL} --condition=None

This grants the Okteto service account permission to access Cloud Storage resources.

Step 4: Configure GCP Cloud Credentials in Okteto​

Now that you've created the IAM Policy Binding, the final step is to configure the GCP credentials in Okteto.

Go to the Cloud Credentials view view in the Okteto Admin dashboard and enable the GCP Workload ID option:

GCP Workload ID

Provide the following information:

  • Project Number: The GCP project id PROJECT_NUMBER where the resources are located
  • Workload Identity Pool ID: The Pool ID POOL_ID you created in Step 1
  • Provider ID: The OIDC Provider ID created in Step 2
  • Audience JWT Claim: The Audience AUDIENCE you specified during the Identity Provider setup

Example Okteto Manifest​

With the configuration complete, the following Okteto Manifest can interact with the specified storage buckets:

deploy:
  image: gcr.io/google.com/cloudsdktool/google-cloud-cli:stable
  commands:
    - gcloud storage buckets create gs://test-bucket

test:
  gcp:
    image: gcr.io/google.com/cloudsdktool/google-cloud-cli:stable
    commands:
      - gcloud storage ls | grep test-bucket

destroy:
  image: gcr.io/google.com/cloudsdktool/google-cloud-cli:stable
  commands:
    - gcloud storage buckets delete gs://test-bucket