Skip to content

docs: document per-node-group GKE Workload Identity toggle #300

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document per-node-group GKE Workload Identity toggle #300

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 22 additions & 2 deletions applications/configure/secure-cloud-access.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,9 +113,29 @@ See [Connections in porter.yaml](/applications/configuration-as-code/services/co

## GCP

Workload identity support for GCP is **in development**. The equivalent flow on GKE — binding a Porter service to a Google service account via [Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation) — is not yet generally available.
Porter uses [GKE Workload Identity](https://cloud.google.com/kubernetes-engine/docs/concepts/workload-identity) to let a service's Kubernetes service account impersonate a GCP IAM service account. Your application code can then use Google's default credential chain (e.g. `google.auth.default()` in Python, `google.NewDefaultCredentials` in Go) and tokens for the GCP service account are resolved automatically — no JSON key files mounted into the pod.

If you'd like this enabled for your project, reach out to Porter support and we'll work with you to get early access.
### Step 1 — Enable Workload Identity on the node group

GKE only runs the metadata server on node pools that have Workload Identity enabled. Before attaching a GCP service account to a Porter service, opt the service's node group in:

1. Navigate to **Infrastructure** → your GKE cluster.
2. Expand the node group your service runs on.
3. Toggle **Enable Workload Identity** on and click **Update**.

See [Node groups → GKE Workload Identity](/cloud-accounts/node-groups#gke-workload-identity-gcp) for details. If your service runs on a node group without Workload Identity enabled, GCP API calls from the pod fail to resolve credentials.

### Step 2 — Create a GCP service account

In the same GCP project as your GKE cluster, create a service account and grant it the IAM roles needed to access the specific resources your service will call.

We strongly recommend following the principle of least privilege: scope roles to individual resources rather than the whole project, prefer narrow predefined roles over `Owner` or `Editor`, and create a dedicated service account per Porter service.

### Step 3 — Attach the service account to your service

Reach out to Porter support to bind your Porter service to the GCP service account. Wider self-serve UI for Workload Identity Federation is still rolling out.

On the next deploy, your pods can call GCP APIs as the service account immediately — no application restart logic required.

---

Expand Down
24 changes: 24 additions & 0 deletions cloud-accounts/node-groups.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,30 @@ Create custom node groups for specialized workloads like GPU processing, high-me

---

## GKE Workload Identity (GCP)

For node groups on GKE clusters, you can opt individual node pools into [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/concepts/workload-identity). When enabled, the GKE metadata server runs on the node pool so pods scheduled there can impersonate a GCP IAM service account at runtime — without mounting service account keys.

Enable this on any node group whose workloads need to call GCP APIs (for example, BigQuery, Cloud Storage, or Pub/Sub) using a GCP service account connection.

<Steps>
<Step title="Edit the node group">
From your Porter dashboard, navigate to **Infrastructure** → your GKE cluster, and expand the node group you want to enable Workload Identity on.
</Step>
<Step title="Toggle Enable Workload Identity">
Switch on **Enable Workload Identity**. The toggle appears only for GCP clusters.
</Step>
<Step title="Update">
Scroll to the bottom and click **Update**. GKE applies the change to the node pool. Existing pods on the pool restart as nodes are rolled.
</Step>
</Steps>

<Info>
Leave Workload Identity disabled on node groups whose workloads don't need GCP API access. The metadata server adds a small amount of overhead per node and exposes additional metadata endpoints to pods on the pool.
</Info>

---

## Assigning Workloads to Node Groups

Once your custom node group is created, assign applications to run on it:
Expand Down