Configure your custom service account

Use your own GCP service account instead of the CARTO-provisioned one

By default, each CARTO Self-Hosted installation includes a dedicated GCP service account key, provisioned by CARTO, that the platform uses to access certain CARTO-managed services. If you prefer to use your own Google Cloud Platform (GCP) service account instead, follow the steps below before installing.

On Kubernetes you can avoid long-lived service account keys entirely by using keyless identity federation. See Cloud Identities: Workload Identity in GCP and EKS Pod Identity in AWS.

1. Create and register the service account

1. Create a dedicated GCP service account for your CARTO Self-Hosted deployment in the GCP console.

2. (Recommended for Single VM deployments) Attach this service account to the Compute Engine instance running CARTO, so the platform authenticates via the instance's identity instead of a long-lived JSON key.

3. Share the service account email with CARTO Support ([e-mail]) so it can be granted the required permissions on CARTO infrastructure.

Wait for confirmation from CARTO Support before proceeding to step 2.

2. Configure the service account in your deployment

☸️ Kots (Admin Console)

Kots

1. Open the Admin Console:

   • Single VM: http://<your-vm-ip>:30000

   • Standard Orchestrated: kubectl kots admin-console -n <namespace>, then open http://localhost:8800

2. Go to Config.

3. Locate the CARTO Platform credentials field. This textarea contains the service account JSON key used by CARTO to access CARTO platform services. By default it holds the CARTO-provisioned service account.

Do not modify the CARTO Platform credentials field without guidance from CARTO Support. Contact [e-mail] before proceeding. They will confirm the service account has the correct permissions and walk you through the change.

1. Replace the existing JSON value with the JSON key of your custom service account.

2. Click Save config, then Deploy to apply the change.

The CARTO Platform credentials field is only visible when Workload Identity is disabled. If you are using Workload Identity, the service account is configured in that section instead.

🛞 Helm (customizations.yaml)

Helm

Add the service account to your customizations.yaml using one of these two options:

Option 1 — Inline value (create secret automatically):

cartoSecrets:
  defaultGoogleServiceAccount:
    value: |
      {
        "type": "service_account",
        "project_id": "<your_project_id>",
        "private_key_id": "<your_private_key_id>",
        "private_key": "-----BEGIN PRIVATE KEY-----\n<your_private_key>\n-----END PRIVATE KEY-----\n",
        "client_email": "<your_sa_email>@<your_project>.iam.gserviceaccount.com",
        "client_id": "<your_client_id>",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token",
        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
        "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/<your_sa_email>"
      }

Option 2 — Existing Kubernetes secret:

First, create the secret from your service account JSON key file:

kubectl create secret generic \
  mycarto-google-custom-service-account \
  --from-file=key=<PATH_TO_YOUR_SECRET.json> \
  -n <namespace>

Then reference it in your customizations.yaml:

cartoSecrets:
  defaultGoogleServiceAccount:
    existingSecret:
      name: mycarto-google-custom-service-account
      key: key

Once your customizations.yaml is updated, apply with:

helm upgrade carto carto/carto \
  --namespace <namespace> \
  -f carto-values.yaml \
  -f carto-secrets.yaml \
  -f customizations.yaml