Connecting a cloud account

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
GCP
Azure

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

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.

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:

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

This removes the IAM role and prevents Porter from accessing your account.

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.

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.

Create the Service Account

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

Option 1: Automated setup (recommended)

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 2: Manual setup

Enable required APIs

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

Navigate to APIs & Services
Click Enable APIs and Services
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

Navigate to Service Accounts

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

Create the account

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

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.

Create a key

Find your new service account in the list
Under Actions, select Manage keys
Click Add Key → Create new key
Select JSON as the key type
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.

Migrating to Workload Identity Federation

If your project has Workload Identity Federation (WIF) enabled, you can migrate an existing service-account JSON connection to WIF without redeploying your clusters. WIF replaces long-lived service-account keys with short-lived federated tokens.

Workload Identity Federation for GCP is currently rolled out per project. If you don’t see the Migrate to Workload Identity Federation button described below, reach out through the support widget to have it enabled.

To migrate:

Open the cloud account

In Porter, navigate to Integrations → GCP and open the cloud account you want to migrate.

Start the migration

Click Migrate to Workload Identity Federation. Porter generates a one-time setup command and a Cloud Shell deeplink.

Run the bootstrap in Cloud Shell

Click the Cloud Shell link, paste the setup command, and run it. The command provisions the Workload Identity Pool, provider, and service account binding in your GCP project via Terraform.Your existing service-account JSON credential keeps authenticating your clusters throughout this step — there is no downtime during migration.

Wait for verification

Porter waits for the bootstrap callback and then cuts the cloud account over to the federated identity. The dialog closes automatically once verification succeeds.

After migration, you can safely delete the original service-account key from your GCP project.

Revoking Access

To revoke Porter’s access:

First, delete any clusters through the Porter dashboard
Navigate to IAM & Admin → Service Accounts in GCP Console
Find the Porter service account and delete it

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

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:

In the Azure portal, search for Subscriptions
Select your subscription and click Resource providers
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

In the Azure portal, search for App registrations
Under All applications, select your new service principal
Navigate to API Permissions
Click Add a permission → Microsoft Graph → Application permissions
Select these permissions:
- Application.ReadWrite.All
- Directory.ReadWrite.All
- Domain.Read.All
- Group.Create
- Group.ReadWrite.All
- RoleManagement.ReadWrite.Directory
- User.ReadWrite.All
Click Add permissions
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:

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

Revoking Access

To revoke Porter’s access:

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

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

Documentation

Documentation Index

​Create the IAM Role

​Permissions Granted

​Revoking Access

​Prerequisites

​Create the Service Account

​Enable required APIs

​Create the Service Account

​Upload to Porter

​Migrating to Workload Identity Federation

​Revoking Access

​Create the Service Principal

​Enable Resource Providers

​Create the Custom Role

​Create the Service Principal

​Grant API Permissions

​Enter Credentials in Porter

​Rotating Credentials

​Revoking Access

Create the IAM Role

Permissions Granted

Revoking Access

Prerequisites

Create the Service Account

Enable required APIs

Create the Service Account

Upload to Porter

Migrating to Workload Identity Federation

Revoking Access

Create the Service Principal

Enable Resource Providers

Create the Custom Role

Create the Service Principal

Grant API Permissions

Enter Credentials in Porter

Rotating Credentials

Revoking Access