From f264699f897d2bc53ef805ad2b81ebf6cfb1eb28 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 13 May 2026 15:10:51 +0000 Subject: [PATCH] Add GCP Workload Identity Federation onboarding option Generated-By: mintlify-agent --- cloud-accounts/connecting-a-cloud-account.mdx | 96 +++++++++++++++---- 1 file changed, 80 insertions(+), 16 deletions(-) diff --git a/cloud-accounts/connecting-a-cloud-account.mdx b/cloud-accounts/connecting-a-cloud-account.mdx index f791a47..f770833 100644 --- a/cloud-accounts/connecting-a-cloud-account.mdx +++ b/cloud-accounts/connecting-a-cloud-account.mdx @@ -61,18 +61,82 @@ Before Porter can create a cluster, you need to grant it access to your cloud ac - Porter connects to GCP using a service account with the **Project IAM Admin** role. You only need to grant this one role and enable two APIs — Porter automatically provisions all other required permissions and APIs. + Porter supports two methods for connecting your GCP project: + + - **Workload Identity Federation (recommended)** — keyless, short-lived credentials issued via federation from Porter's AWS account to your GCP project. No JSON key file to store, rotate, or leak. + - **Service account JSON key** — long-lived JSON key uploaded directly to Porter. Use this if your organization restricts Workload Identity Federation or you need a fully manual setup. ## Prerequisites Before connecting your GCP project to Porter, ensure that a [billing account](https://console.cloud.google.com/billing) is attached to the project. Porter cannot provision infrastructure in a project without an active billing account. - ## Create the Service Account + + + Porter runs a guided Cloud Shell flow that provisions a Workload Identity Pool, Provider, and service account in your GCP project using Terraform, then calls back to Porter to finalize the integration. Porter impersonates the service account using short-lived federated credentials — no JSON key is ever created or transmitted. - You can create the service account using our automated script (recommended) or manually. + + + After selecting GCP as your cloud provider and choosing **Workload Identity Federation**, enter your GCP project ID (for example, `my-prod-project` — not the numeric project number). - - + Click **Continue**. Porter returns a Cloud Shell deeplink and a one-line setup command. + + + Click **Open Cloud Shell**. Google Cloud Shell launches in a new tab with the public [porter-dev/gcp-onboarding](https://github.com/porter-dev/gcp-onboarding) repo cloned into the session. + + + The setup command is single-use and embeds a verification token tied to your Porter project. The token expires after a short window — if it expires before you finish, return to Porter and restart the flow to issue a new one. + + + + Copy the setup command from Porter and paste it into the Cloud Shell terminal. The command looks like: + + ```bash + PORTER_API_URL="https://api.porter.run" \ + PORTER_CLOUD_ACCOUNT_ID="4741dca9-ae17-417b-949e-1a18f91b77d9" \ + PORTER_VERIFICATION_TOKEN="eyJhbGciOi..." \ + ./bootstrap.sh + ``` + + `bootstrap.sh` runs `terraform apply` to: + + - Enable the required GCP APIs + - Create a Workload Identity Pool and AWS-backed Provider scoped to Porter's AWS account + - Create a `porter-manager` service account with the **Project IAM Admin** role + - Configure the Provider's attribute condition so only Porter's tenant-scoped sessions can impersonate the service account + + When Terraform finishes, the script calls Porter back with the project number, service account email, and provider resource name. Porter verifies it can federate into the project and marks the integration as connected. + + + Return to the Porter tab. The cloud account status updates to **Connected** once the callback completes. You can now provision clusters in the project. + + + + ### How federation works + + Porter's Cluster Control Plane runs in an AWS account. The Terraform module configures your Workload Identity Provider to trust assumed-role sessions originating from that account, with an attribute condition pinned to your tenant's external ID. When Porter needs to act on your GCP project, it: + + 1. Self-assumes its IAM role with a session name containing your tenant external ID. + 2. Exchanges the resulting AWS STS token at Google's STS endpoint via the Workload Identity Provider. + 3. Impersonates the `porter-manager` service account using the federated token. + + The federated credentials are short-lived and scoped to a single tenant. No static keys exist on either side. + + ### Re-running onboarding + + If the Cloud Shell session times out or Terraform fails partway through, return to Porter and start the flow again for the same project. Porter rotates the verification token but keeps the tenant external ID stable, so the Terraform state path is unchanged and `terraform apply` resumes cleanly. + + ### Revoking access + + To revoke Porter's access: + + 1. First, delete any clusters through the Porter dashboard. + 2. In the GCP Console, go to **IAM & Admin** → **Workload Identity Federation** and delete the `porter-pool-*` pool. + 3. Delete the `porter-manager` service account from **IAM & Admin** → **Service Accounts**. + + Alternatively, run `terraform destroy` against the module from the same Cloud Shell session. + + + If you have the [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed and authenticated (`gcloud auth login`), run our setup script: ```bash @@ -95,7 +159,7 @@ Before Porter can create a cluster, you need to grant it access to your cloud ac After running the script, upload the generated key file to Porter. - + ### Enable required APIs Before creating the service account, enable the following APIs in your [GCP Console](https://console.cloud.google.com): @@ -138,22 +202,22 @@ Before Porter can create a cluster, you need to grant it access to your cloud ac 5. The JSON key file downloads automatically — keep it safe - - - ## Upload to Porter + ### Upload to Porter - In Porter, click **Drop a GCP Service Account JSON here, or click to browse** and upload the JSON key file. + In Porter, click **Drop a GCP Service Account JSON here, or click to browse** and upload the JSON key file. - Porter verifies the credentials and automatically provisions all required permissions and APIs. This takes about a minute. + Porter verifies the credentials and automatically provisions all required permissions and APIs. This takes about a minute. + + - ## Revoking Access + ## Revoking JSON key access - To revoke Porter's access: + If you onboarded with a service account JSON key, revoke access by: - 1. First, delete any clusters through the Porter dashboard - 2. Navigate to **IAM & Admin** → **Service Accounts** in GCP Console - 3. Find the Porter service account and delete it + 1. First, deleting any clusters through the Porter dashboard. + 2. Navigating to **IAM & Admin** → **Service Accounts** in GCP Console. + 3. Finding the Porter service account and deleting it. This removes the service account and prevents Porter from accessing your account.