Connections in porter.yaml

Connect your services to external cloud resources like AWS IAM roles, Azure managed identities, Google Cloud SQL instances, and persistent disks.

Connection Types

Type	Description	Cloud Provider
`awsRole`	Attach an IAM role for AWS API access	AWS
`azureManagedIdentity`	Bind a User Assigned Managed Identity for Azure API access	Azure
`gcpServiceAccount`	Bind a GCP IAM service account for GCP API access	GCP
`cloudSql`	Connect to Google Cloud SQL instances	GCP
`disk`	Attach persistent storage	All

AWS Role Connection

Attach an IAM role to your service for secure AWS API access without managing credentials.

Field Reference

Field	Type	Required	Description
`type`	string	Yes	Must be `awsRole`
`role`	string	Yes	IAM role name

Example

services:
  - name: api
    # ...
    connections:
      - type: awsRole
        role: my-app-s3-access

Azure Managed Identity Connection

Bind a User Assigned Managed Identity (UAMI) to your service for secure Azure API access without managing credentials. Porter uses Azure Workload Identity to federate the service’s Kubernetes service account with the UAMI, so your application can authenticate to Azure resources using DefaultAzureCredential (or any credential type that supports workload identity).

This feature is only available on AKS clusters created through Porter and must be enabled at the project level. Reach out to Porter support if you don’t see it available on your project.

Prerequisites

Before adding this connection to your service, you must:

Have a User Assigned Managed Identity provisioned in your Azure subscription. Porter does not create the UAMI for you — provision it via the Azure Portal, Terraform, or the Azure CLI.
Grant the UAMI the Azure RBAC role assignments it needs to access the resources your service will call (e.g. Storage Blob Data Reader on a storage account).

When your service deploys, Porter creates a federated identity credential on the UAMI that maps your service’s Kubernetes service account to the identity. At runtime, the pod receives a projected OIDC token that Azure exchanges for an access token scoped to the UAMI.

Field Reference

Field	Type	Required	Description
`type`	string	Yes	Must be `azureManagedIdentity`
`identityName`	string	Yes	Name of the User Assigned Managed Identity
`resourceGroup`	string	Yes	Azure resource group containing the managed identity

Example

services:
  - name: api
    # ...
    connections:
      - type: azureManagedIdentity
        identityName: my-app-identity
        resourceGroup: my-resource-group

This connection grants your service every permission assigned to the UAMI in Azure. Scope role assignments narrowly — a UAMI with subscription-level Owner is rarely what you want.

Only one azureManagedIdentity connection is permitted per service. If you need to access resources across multiple identities, consolidate role assignments onto a single UAMI.

GCP Service Account Connection

Bind a GCP IAM service account to your service for secure GCP API access without managing service account key files. Your application can authenticate to GCP resources using Application Default Credentials, and Porter handles the identity binding for your service.

Prerequisites

Before adding this connection to your service, you must:

Have a GCP IAM service account provisioned in the same GCP project as your Porter infrastructure. Porter does not create the IAM service account for you — provision it via the Google Cloud Console, Terraform, or the gcloud CLI.
Grant the IAM service account the GCP IAM roles it needs to access the resources your service will call (e.g. roles/storage.objectViewer on a storage bucket).

When your service deploys, Porter configures the required IAM binding so the service can receive short-lived credentials scoped to the IAM service account.

Field Reference

Field	Type	Required	Description
`type`	string	Yes	Must be `gcpServiceAccount`
`serviceAccountEmail`	string	Yes	Fully-qualified email of the GCP IAM service account to impersonate

Example

services:
  - name: api
    # ...
    connections:
      - type: gcpServiceAccount
        serviceAccountEmail: my-app@my-project.iam.gserviceaccount.com

This connection grants your service every permission assigned to the IAM service account in GCP. Scope IAM role bindings narrowly — a service account with project-level roles/owner is rarely what you want.

Only one gcpServiceAccount connection is permitted per service. If you need to access resources across multiple service accounts, consolidate IAM role bindings onto a single service account.

Cloud SQL Connection (GCP)

Connect to Google Cloud SQL instances using the Cloud SQL Auth Proxy for secure database access.

Your GCP Service account must be configured in the Connections tab of your cluster settings before it can be used in porter.yaml.

Field Reference

Field	Type	Required	Description
`type`	string	Yes	Must be `cloudSql`
`config.cloudSqlConnectionName`	string	Yes	Cloud SQL instance connection name
`config.cloudSqlDatabasePort`	integer	Yes	Database port (e.g., 5432 for PostgreSQL)
`config.cloudSqlServiceAccount`	string	Yes	GCP service account name

Example

services:
  - name: api
    # ...
    connections:
      - type: cloudSql
        config:
          cloudSqlConnectionName: my-project-123456:us-east1:my-instance
          cloudSqlDatabasePort: 5432
          cloudSqlServiceAccount: my-service-account

The connection name follows the format project-id:region:instance-name. You can find this in the Google Cloud Console under your Cloud SQL instance details.

Persistent Disk Connection

Attach persistent storage to your service for data that needs to survive pod restarts.

Your persistent disk must be created in the Add-Ons tab of Porter before it can be used in porter.yaml.

Field Reference

Field	Type	Required	Description
`type`	string	Yes	Must be `disk`
`config.diskName`	string	Yes	Name of the persistent disk

Example

services:
  - name: api
    # ...
    connections:
      - type: disk
        config:
          diskName: my-persistent-data

Persistent disks are tied to specific availability zones. Services using persistent disks cannot be scheduled across multiple zones.

Multiple Connections

You can attach multiple connections to a single service (but only one of each type of connection):

services:
  - name: api
    # ...
    connections:
      - type: awsRole
        role: api-s3-access
      - type: disk
        config:
          diskName: cache-storage

Web Services - Web service configuration
Worker Services - Worker service configuration
Job Services - Job service configuration
porter.yaml Reference - Complete configuration reference

​Connection Types

​AWS Role Connection

​Field Reference

​Example

​Azure Managed Identity Connection

​Prerequisites

​Field Reference

​Example

​GCP Service Account Connection

​Prerequisites

​Field Reference

​Example

​Cloud SQL Connection (GCP)

​Field Reference

​Example

​Persistent Disk Connection

​Field Reference

​Example

​Multiple Connections

​Related Documentation

Connection Types

AWS Role Connection

Field Reference

Example

Azure Managed Identity Connection

Prerequisites

Field Reference

Example

GCP Service Account Connection

Prerequisites

Field Reference

Example

Cloud SQL Connection (GCP)

Field Reference

Example

Persistent Disk Connection

Field Reference

Example

Multiple Connections

Related Documentation