Connecting a cloud account

Grant Porter access to your AWS, GCP, or Azure account using IAM roles, service accounts, or service principals 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.

AWS

Porter uses AWS IAM role assumption via the AssumeRole operation 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

1. Enter your AWS Account ID

   After selecting AWS as your cloud provider, log into your AWS Console and find your 12-digit Account ID in the top-right corner.

   Enter this ID in Porter and click Grant Permissions.

2. 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.

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

   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).

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

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

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

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.

GCP

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 is attached to the project. Porter cannot provision infrastructure in a project without an active billing account.

Option 1: Workload Identity Federation (recommended)

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.

1. Enter your GCP project ID

   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.

2. Open Cloud Shell

   Click Open Cloud Shell. Google Cloud Shell launches in a new tab with the public 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.

3. Run the bootstrap script

   Copy the setup command from Porter and paste it into the Cloud Shell terminal. The command looks like:

   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.

4. Confirm in Porter

   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.

Option 2: Service account JSON key (automated script)

If you have the gcloud CLI installed and authenticated (gcloud auth login), run our setup script:

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

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

# Run the script (optionally provide your GCP project ID)
./setup-gcp-porter.sh [your-gcp-project-id]

The script:

• Enables the Cloud Resource Manager API and Service Usage API
• Creates a porter-manager service account
• Grants the Project IAM Admin role
• Downloads a JSON key file

After running the script, upload the generated key file to Porter.

Option 3: Service account JSON key (manual setup)

Enable required APIs

Before creating the service account, enable the following APIs in your GCP Console:

1. Navigate to APIs & Services
2. Click Enable APIs and Services
3. Search for and enable each of these APIs:
   • Cloud Resource Manager API — required for Porter to manage IAM bindings
   • Service Usage API — required for Porter to enable all other APIs automatically

Each API may take a few minutes to enable.

The Service Usage API cannot be enabled programmatically if it is not already active — it must be enabled manually through the console or gcloud CLI before Porter can manage other APIs.

Create the Service Account

1. Navigate to Service Accounts

   In the GCP Console, go to IAM & Admin → Service Accounts.

2. Create the account

   Click Create Service Account and enter a name (e.g., porter-manager).

3. Grant permissions

   Grant the service account the following role:

   • Resource Manager > Project IAM Admin

   This is the only role you need to grant manually. Porter uses this role to automatically provision all other required IAM bindings (Storage Admin, Compute Admin, Kubernetes Engine Admin, etc.).

   Click Done to create the account.

4. Create a key

   1. Find your new service account in the list
   2. Under Actions, select Manage keys
   3. Click Add Key → Create new key
   4. Select JSON as the key type
   5. The JSON key file downloads automatically — keep it safe

Upload to Porter

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.

Revoking JSON key access

If you onboarded with a service account JSON key, revoke access by:

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.

Azure

Porter connects to Azure using a service principal with permissions to manage your infrastructure.

Create the Service Principal

You can create the service principal using our automated script (recommended) or manually.

Option 1: Automated setup (recommended)

If you have the Azure CLI installed and authenticated (az login), run our setup script:

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

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

# Run the script (optionally provide subscription ID)
./setup-azure-porter.sh [your-subscription-id]

The script:

• Enables all required Azure resource providers
• Creates the custom porter-aks-restricted role
• Creates the service principal with proper permissions
• Adds Microsoft Graph API permissions
• Grants admin consent (if you have permissions)
• Displays the credentials needed for Porter

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

Option 2: Manual setup

Enable Resource Providers

Before creating the service principal, enable the required resource providers:

1. In the Azure portal, search for Subscriptions
2. Select your subscription and click Resource providers
3. Enable the following providers by selecting them and clicking Register:
   • Microsoft.Capacity
   • Microsoft.Compute
   • Microsoft.ContainerRegistry
   • Microsoft.ContainerService
   • Microsoft.KeyVault
   • Microsoft.ManagedIdentity
   • Microsoft.Network
   • Microsoft.OperationalInsights
   • Microsoft.OperationsManagement
   • Microsoft.ResourceGraph
   • Microsoft.Resources
   • Microsoft.Storage

Registration may take a few minutes per provider. Confirm all providers are enabled before proceeding.

Create the Custom Role

Run the following commands in the Azure Cloud Shell (Bash) or your local terminal with the Azure CLI:

# Set your subscription ID
PORTER_AZURE_SUBSCRIPTION_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# Create the role
envsubst << EOF | az role definition create --role-definition @-
{
    "assignableScopes": ["/subscriptions/${PORTER_AZURE_SUBSCRIPTION_ID}"],
    "description": "Grants Porter access to manage resources for an AKS cluster.",
    "id": "/subscriptions/${PORTER_AZURE_SUBSCRIPTION_ID}/providers/Microsoft.Authorization/roleDefinitions/porter-aks-restricted",
    "isCustom": true,
    "name": "porter-aks-restricted",
    "permissions": [
        {
            "actions": ["*"],
            "dataActions": [],
            "notActions": [
                "Microsoft.Authorization/elevateAccess/Action",
                "Microsoft.Blueprint/blueprintAssignments/write",
                "Microsoft.Blueprint/blueprintAssignments/delete",
                "Microsoft.Compute/galleries/share/action"
            ],
            "notDataActions": []
        }
    ],
    "roleName": "Contributor",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions"
}
EOF

Create the Service Principal

az ad sp create-for-rbac \
  --name="azure-porter-restricted-sp" \
  --role="porter-aks-restricted" \
  --scopes="/subscriptions/${PORTER_AZURE_SUBSCRIPTION_ID}"

Save the output—you’ll need these values:

{
  "appId": "00000000-0000-0000-0000-000000000000",
  "displayName": "azure-porter-restricted-sp",
  "password": "0000-0000-0000-0000-000000000000",
  "tenant": "00000000-0000-0000-0000-000000000000"
}

Grant API Permissions

1. In the Azure portal, search for App registrations
2. Under All applications, select your new service principal
3. Navigate to API Permissions
4. Click Add a permission → Microsoft Graph → Application permissions
5. Select these permissions:
   • Application.ReadWrite.All
   • Directory.ReadWrite.All
   • Domain.Read.All
   • Group.Create
   • Group.ReadWrite.All
   • RoleManagement.ReadWrite.Directory
   • User.ReadWrite.All
6. Click Add permissions
7. Click Grant admin consent for Default Directory

Enter Credentials in Porter

In Porter, enter the following values from your service principal:

Field	Value
Subscription ID	Your Azure subscription ID
Application (Client) ID	The appId from your service principal
Client Secret	The password from your service principal
Tenant ID	The tenant from your service principal

Rotating Credentials

Azure requires client secrets to expire every 365 days. When a secret expires, Porter can’t manage infrastructure or deploy updates (existing workloads continue running).

To refresh your client secret:

1. Visit https://aka.ms/NewClientSecret
2. Select the app ID for your Porter service principal
3. Generate a new client secret and copy the value
4. In Porter, navigate to Integrations → Azure
5. Update the Password field with the new value

Revoking Access

To revoke Porter’s access:

1. First, delete any clusters through the Porter dashboard
2. In the Azure portal, search for App registrations
3. Find and delete the Porter service principal
4. Optionally, delete the custom role definition

This removes the service principal and prevents Porter from accessing your account.