# Use Workload Identity in GCP What is Workload Identity? Applications running on Google Kubernetes Engine might need access to Google Cloud APIs such as Compute Engine API, BigQuery API, or Storage APIs. Workload Identity allows a Kubernetes service account in your GKE cluster to act as an IAM service account. Pods that use the configured Kubernetes service account automatically authenticate as the IAM service account when accessing Google Cloud APIs. **Using Workload Identity allows you to assign distinct, fine-grained identities and authorization for each application in your cluster**. {% hint style="info" %} Enabling Workload Identity in your Self-Hosted installation is **just available for the orchestrated container deployment** of CARTO. {% endhint %} ## How does Workload Identity work? When you enable Workload Identity on a cluster, GKE automatically creates a fixed workload identity pool for the cluster's Google Cloud project. A workload identity pool allows IAM to understand and trust Kubernetes service account credentials. GKE uses this pool for all clusters in the project that use Workload Identity. The workload identity pool has the following format: `PROJECT_ID.svc.id.goog` When you configure a Kubernetes service account in a namespace to use Workload Identity, IAM authenticates the credentials using the following member name: `serviceAccount:PROJECT_ID.svc.id.goog[KUBERNETES_NAMESPACE/KUBERNETES_SERVICE_ACCOUNT]` In this member name: * `PROJECT_ID`: your Google Cloud project ID. * `KUBERNETES_NAMESPACE`: the namespace of the Kubernetes service account. * `KUBERNETES_SERVICE_ACCOUNT`: the name of the Kubernetes service account making the request. The process of configuring Workload Identity includes using an IAM policy binding to bind the Kubernetes service account member name to an IAM service account that has the permissions your workloads need. Any Google Cloud API calls from workloads that use this Kubernetes service account are authenticated as the bound IAM service account. ## Configure CARTO deployment to use Workload Identity In order to enable Workload Identity in your CARTO Self-Hosted installation, you'll have to follow these steps: 1. **Create an IAM service account for your application**, or use an existing IAM service account instead. {% tabs %} {% tab title="gcloud" %} ```bash gcloud iam service-accounts create {IAM_SERVICE_ACCOUNT_NAME} \ --project={PROJECT_ID} ``` * `IAM_SERVICE_ACCOUNT_NAME`: name of the new service account. * `PROJECT_ID`: ID of the project where the GKE cluster is deployed. Service Account needs `roles/iam.serviceAccountTokenCreator` role to sign URLs, you can grant it with this command: ```bash gcloud iam service-accounts add-iam-policy-binding \ {IAM_SERVICE_ACCOUNT_EMAIL} \ --member=serviceAccount:{IAM_SERVICE_ACCOUNT_EMAIL} \ --role=roles/iam.serviceAccountTokenCreator ``` * `IAM_SERVICE_ACCOUNT_NAME`: name of the new service account used in previous step * `IAM_SERVICE_ACCOUNT_EMAIL`: email of the service account generated with the previous command. {% endtab %} {% endtabs %} 2. **Send email to CARTO Support Team** with the **Service Account email** Reach out to our CARTO support team and provide them with the email associated with the Service Account you’ve created. This step ensures seamless integration of your Service Account with your CARTO Self-Hosted deployment. Email CARTO Support Team with the service account email. {% hint style="danger" %} **IMPORTANT**: The provided Service Account will not work unless the CARTO support team has been notified and they proceed with the grants mentioned above. {% endhint %} 3. Create the Kubernetes service account used for Workload Identity: {% tabs %} {% tab title="kubectl" %} Use the following command to generate the service account in your cluster: ``` kubectl create serviceaccount {SERVICE_ACCOUNT_NAME} \ --namespace={NAMESPACE} ``` * `SERVICE_ACCOUNT_NAME`: name of the service account that will be generated in your namespace. You'll have to provide that name when configuring CARTO platform. * `NAMESPACE`: namespace where you're deploying CARTO Self-Hosted platform. Once your service account is created in your kubernetes cluster, you'll have to annotate it with the email of the service account that you genereated in your GCP project: ``` kubectl annotate serviceaccount {SERVICE_ACCOUNT_NAME} \ --namespace {NAMESPACE} \ iam.gke.io/gcp-service-account={GCP_SERVICE_ACCOUNT_EMAIL} ``` * `SERVICE_ACCOUNT_NAME`: name of the service account that will be generated in your namespace. * `NAMESPACE`: namespace where you're deploying CARTO Self-Hosted platform. * `GCP_SERVICE_ACCOUNT_EMAIL`: email of the service account that you created in your GCP project. {% endtab %} {% endtabs %} 4. Allow the Kubernetes service account that is going to be created in your GKE cluster to impersonate the IAM service account by adding an IAM policy binding between the two service accounts.\ This binding allows the Kubernetes service account to act as the IAM service account. {% tabs %} {% tab title="gcloud" %} ```bash gcloud iam service-accounts add-iam-policy-binding {IAM_SERVICE_ACCOUNT_EMAIL} \ --role roles/iam.workloadIdentityUser \ --member "serviceAccount:{PROJECT_ID}.svc.id.goog[{KUBERNETES_NAMESPACE}/{KUBERNETES_SERVICE_ACCOUNT}]" ``` * `IAM_SERVICE_ACCOUNT_EMAIL`: email of the service account generated in the first step. * `PROJECT_ID`: ID of the project where the GKE cluster is deployed. * `KUBERNETES_NAMESPACE`: namespace where CARTO application is deployed. * `KUBERNETES_SERVICE_ACCOUNT`: name of the kubernetes service account used by CARTO application. Default value is `carto-common-backend`. {% hint style="info" %} You can find the `gcloud` command with the `KUBERNETES_NAMESPACE` and `KUBERNETES_SERVICE_ACCOUNT` values in the helm output notes once you execute the installation process. {% endhint %} {% endtab %} {% endtabs %} 5. Add the workload identity service account name in your Admin Console:
## Create a BigQuery connection managed using Workload Identity CARTO Self-Hosted running on a GKE cluster can take advantage of GKE Workload Identity feature to create a connection between the CARTO Self-Hosted platform and BigQuery without any user action. ### Configuration 1. Setup GKE Workload Identity for CARTO Self-Hosted following the [documentation](#how-to-allow-carto-to-use-workload-identity). 2. Grant your Workload Identity service account with BigQuery [required permissions](https://docs.carto.com/carto-user-manual/connections/required-permissions) to your data warehouse project. 3. Enable the BigQuery workload identity connection in your Admin Console:
In the CARTO connection owner ID field you'll have to use the ID of the CARTO user who will be the owner of the connection (i.e. `"auth0|3idsj230990sj4wsddd10"`). This can be obtained by running the following `curl` command: ``` curl -s 'https://accounts.app.carto.com/users/me' \ -H 'Authorization: Bearer ' \ | jq '.user_id' ``` Once you've applied the changes performed in your customizations.yaml file, your CARTO deployment will automatically create a new BigQuery connection using Workload Identity owned by the CARTO user specified in the deployment configuration! --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.carto.com/carto-self-hosted/guides/guides/use-workload-identity-in-gcp.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.