> ## Documentation Index
> Fetch the complete documentation index at: https://porter-gk-forward-auth.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting a cloud account

> Grant Porter access to your AWS, GCP, or Azure account using IAM role assumption or Workload Identity Federation to provision infrastructure

Before Porter can create a cluster, you need to grant it access to your cloud account. Porter uses secure credential methods that don't require storing static API keys.

<Tabs>
  <Tab title="AWS">
    Porter uses AWS IAM role assumption via the `AssumeRole` [operation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html) to access your account. You create a role in your AWS account and declare that you trust Porter to assume it. This eliminates static credentials and makes access easy to revoke.

    ## Create the IAM Role

    <Steps>
      <Step title="Enter your AWS Account ID">
        After selecting AWS as your cloud provider, log into your [AWS Console](https://console.aws.amazon.com) and find your 12-digit Account ID in the top-right corner.

        Enter this ID in Porter and click **Grant Permissions**.
      </Step>

      <Step title="Create the CloudFormation stack">
        Porter opens the AWS CloudFormation console in a new tab to create a stack that provisions the `porter-manager` IAM role.

        <Warning>
          If the popup is blocked, check your browser settings and allow popups from Porter.
        </Warning>

        Scroll to the bottom of the CloudFormation page, check the **I acknowledge that AWS CloudFormation might create IAM resources** box, and click **Create Stack**.

        Wait for the stack creation to complete (this takes a few minutes).
      </Step>
    </Steps>

    <Info>
      The IAM role must remain in your AWS account for Porter to manage your infrastructure. Deleting it will prevent Porter from making changes.
    </Info>

    ## Permissions Granted

    The CloudFormation stack creates an IAM role with permissions to:

    * Create and manage EKS clusters
    * Create and manage VPCs, subnets, and security groups
    * Create and manage ECR repositories
    * Create and manage IAM roles for cluster operations
    * Request service quota increases

    <Info>
      If you need Porter to operate with more restricted permissions, contact us through the support widget to inquire about Porter Enterprise.
    </Info>

    ## Revoking Access

    To revoke Porter's access:

    1. First, delete any clusters through the Porter dashboard
    2. Navigate to **CloudFormation Stacks** in your AWS console
    3. Select the stack named `PorterRole` and click **Delete**

    This removes the IAM role and prevents Porter from accessing your account.
  </Tab>

  <Tab title="GCP">
    Porter connects to GCP using [Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation). Workload Identity Federation offers a mechanism for Porter to connect with your GCP project without requiring any static keys. Setup runs in [Google Cloud Shell](https://cloud.google.com/shell) with a single command Porter generates for your project.

    ## Prerequisites

    Your GCP project needs an active [billing account](https://console.cloud.google.com/billing) attached. Porter cannot provision infrastructure without one.

    The Google account running the setup must have these project-level roles (or `roles/owner`, which covers all of them):

    * `roles/serviceusage.serviceUsageAdmin`
    * `roles/iam.serviceAccountAdmin`
    * `roles/resourcemanager.projectIamAdmin`
    * `roles/iam.workloadIdentityPoolAdmin`
    * `roles/storage.admin`

    ## Connect Your GCP Project

    <Steps>
      <Step title="Enter your GCP Project ID">
        In Porter, select GCP. Enter your [GCP project ID](https://console.cloud.google.com) (visible at the top of any page in the GCP Console) and click **Connect**. Porter generates a one-time setup command scoped to this integration.
      </Step>

      <Step title="Run the setup in Cloud Shell">
        In the Porter dashboard:

        1. Copy the command shown in the **Run Setup in Cloud Shell** panel.
        2. Click **Open Cloud Shell** to launch a new tab with the [porter-dev/gcp-onboarding](https://github.com/porter-dev/gcp-onboarding) repository pre-loaded.
        3. Cloud Shell will warn that the repository is from an untrusted source. Click **Trust** to continue. The repository is open source so you can review the Terraform before approving.
        4. Paste the command into the shell and press Enter.

        The script runs Terraform in your project and performs the initial setup:

        * Enables five Google APIs: Cloud Resource Manager, IAM, IAM Credentials, STS, and Service Usage
        * Creates a `porter-manager-*` service account that Porter impersonates
        * Creates a `porter-pool-*` Workload Identity Pool with a trust policy scoped to your project
        * Grants three bootstrap IAM roles to the service account so Porter can finish the rest of the configuration itself: `roles/serviceusage.serviceUsageAdmin`, `roles/resourcemanager.projectIamAdmin`, and `roles/iam.serviceAccountAdmin`

        Setup takes about 30 seconds.
      </Step>

      <Step title="Wait for verification">
        Porter's dashboard polls the connection automatically. Once the bootstrap completes, Porter takes over the heavier configuration on your behalf. It enables the remaining APIs needed for cluster provisioning (Compute, Kubernetes Engine, Artifact Registry, Secret Manager, and others) and grants the matching per-service roles to the `porter-manager-*` service account (Compute Admin, Kubernetes Engine Admin, Artifact Registry Admin, Secret Manager Admin, and others). Once everything is provisioned, the cloud account is marked connected and the status banner turns green.

        The full Terraform module is open source if you want to inspect every resource Porter creates: [porter-dev/gcp-onboarding](https://github.com/porter-dev/gcp-onboarding).
      </Step>
    </Steps>

    ## Porter-Managed Infrastructure

    Once your project is connected, Porter provisions and continuously reconciles infrastructure in it: the VPC, Cloud NAT and Cloud Router, the GKE cluster, its node pools, and the cluster load balancer.

    <Warning>
      Do not modify Porter-managed resources directly in the GCP Console or with `gcloud`. Out-of-band changes are detected as drift on the next cluster update: Porter will revert them, which can itself disrupt traffic. Changes to settings that GKE cannot update in place may cause the **cluster to be replaced entirely**, resulting in downtime and the loss of any manually created in-cluster resources.
    </Warning>

    Settings that can trigger reconciliation or cluster replacement when changed outside of Porter include:

    * **Cloud NAT and Cloud Router** — port allocation (min ports per VM, dynamic port allocation), endpoint-independent mapping, TCP timeouts, NAT IP allocation mode and static NAT IPs, source subnetwork ranges
    * **VPC** — the cluster VPC and subnet, primary and secondary CIDR ranges, Private Google Access and its associated routes and DNS
    * **GKE control plane** — cluster version, private cluster settings (private nodes, endpoint access), master authorized networks and CIDR, workload identity pool, logging and system components, cluster autoscaling, KMS settings
    * **GKE node pools** — machine type, disk, image type, autoscaling settings, node locations and versions, spot/preemptible flag, OAuth scopes, labels, taints, network tags, GPU settings, upgrade and management settings
    * **Load balancer** — the external static IP

    Settings like NAT port allocation and node pool configuration can be changed safely from the Porter dashboard. For any requirement not exposed there (for example, public node IPs to reduce egress cost), contact Porter support before changing it in GCP.

    ## Migrating from a Service Account JSON

    If you previously connected GCP using a service account JSON key, you can switch to Workload Identity Federation with no downtime:

    1. In Porter, navigate to **Integrations** → **Cloud accounts** and select your GCP account.
    2. Click **Migrate to Workload Identity Federation** in the banner at the top of the page.
    3. Follow the same Cloud Shell flow above.

    Your existing clusters keep authenticating with the JSON key while the new federation is being verified. Once verified, Porter swaps the credential atomically. There is no service interruption.

    ### After Migration

    Workload Identity Federation is now the active connection between Porter and your GCP project, but your previous service account and its JSON key are still present in your project until you remove them. To finish the migration:

    1. In the [GCP Console](https://console.cloud.google.com), open **IAM & Admin** → **Service Accounts**.
    2. Find your legacy service account (the one whose key you previously uploaded to Porter — typically named `porter-manager`, separate from the new `porter-manager-*` account created during federation).
    3. Delete its JSON key, or delete the entire service account.

    Porter no longer needs the legacy account once federation is active. Leaving it in place means an unrotated long-lived key continues to exist in your project.

    ## Revoking Access

    To disconnect Porter from your GCP project:

    1. First, delete any clusters through the Porter dashboard.
    2. In the [GCP Console](https://console.cloud.google.com), navigate to **IAM & Admin** → **Workload Identity Federation** and delete the `porter-pool-*` Workload Identity Pool. This immediately invalidates all federated tokens.

    Optionally, also delete the `porter-manager-*` service account under **IAM & Admin** → **Service Accounts** for full cleanup.
  </Tab>

  <Tab title="Azure">
    Porter connects to Azure using [workload identity federation](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation). You create a [managed identity](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview) that trusts a Porter-managed OIDC issuer. Porter generates short-lived JWT tokens using this OIDC isser and exchanges them with Azure for short-lived Azure tokens.

    ## Prerequisites

    * You must have permissions to create app registrations, role definitions, and role assignments in your Azure subscription
    * You must have the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) and [`jq`](https://jqlang.github.io/jq/) installed

    ## Connect Your Azure Subscription

    <Steps>
      <Step title="Begin the Azure connection process in Porter">
        In the Porter dashboard, click **Connect a new account** and select **Azure**. Porter generates a one-time setup command with your OIDC subject and issuer already substituted. Keep this open — you'll paste it into your terminal in the next step.
      </Step>

      <Step title="Run the setup commands">
        Copy the commands shown in the dashboard and run it in your terminal. The commands look like:

        ```bash theme={null}
        # Authenticate the Azure CLI
        az login

        # Download the setup script
        curl -O https://raw.githubusercontent.com/porter-dev/docs/main/scripts/setup-azure-porter-wif.sh

        # Make it executable
        chmod +x setup-azure-porter-wif.sh

        # Run the script with the OIDC subject and issuer from Porter
        ./setup-azure-porter-wif.sh \
          --subject <oidc-subject-from-porter> \
          --issuer <oidc-issuer-from-porter>
        ```

        The script performs the initial setup in your Azure account:

        * Enables the required Azure resource providers:
          * Microsoft.Capacity
          * Microsoft.Compute
          * Microsoft.ContainerRegistry
          * Microsoft.ContainerService
          * Microsoft.ManagedIdentity
          * Microsoft.Network
          * Microsoft.OperationalInsights
          * Microsoft.OperationsManagement
          * Microsoft.ResourceGraph
          * Microsoft.Resources
          * Microsoft.Storage
        * Creates the custom `porter-aks-restricted` role and grants all subscription actions except:
          * `Microsoft.Authorization/elevateAccess/Action`
          * `Microsoft.Blueprint/blueprintAssignments/write`
          * `Microsoft.Blueprint/blueprintAssignments/delete`
          * `Microsoft.Compute/galleries/share/action`
        * Creates the `azure-porter-federated-sp` app registration and matching service principal, then assigns the custom role at the subscription scope
        * Adds these Microsoft Graph application permissions:
          * Application.ReadWrite.All
          * Directory.ReadWrite.All
          * Domain.Read.All
          * Group.Create
          * Group.ReadWrite.All
          * RoleManagement.ReadWrite.Directory
          * User.ReadWrite.All
        * Grants admin consent for the Graph permissions
        * Adds a federated identity credential on the app registration trusting Porter's OIDC issuer (audience `api://AzureADTokenExchange`)
        * Waits for Azure's [eventually consistent IAM service](https://devblogs.microsoft.com/identity/designing-for-eventual-consistency-for-microsoft-entra/) to propogate changes.
        * Outputs the app registration's metadata: **Subscription ID**, **Application (Client) ID**, and **Tenant ID**

        Setup can take a few minutes.

        <Info>
          If the script fails to grant admin consent automatically, grant it manually in the Azure Portal: **App registrations** > **azure-porter-federated-sp** > **API permissions** > **Grant admin consent for Default Directory**.
        </Info>
      </Step>

      <Step title="Enter app metadata into Porter">
        Paste the outputted **Subscription ID**, **Application (Client) ID**, and **Tenant ID** back into the Porter dashboard to register the connection.
      </Step>
    </Steps>

    ## Revoking Access

    To revoke Porter's access:

    1. In the Azure portal, search for **App registrations** and delete **azure-porter-federated-sp**
    2. \[Optional] Delete the custom role definition created by Porter

    This ensures that Porter can no longer access your Azure subscription.
  </Tab>
</Tabs>