Connections in porter.yaml

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

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
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 connection is available on any project with an AKS cluster created through Porter.

Prerequisites

Before adding this connection to your service, you must:

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

---

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

---

Related Documentation

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