> ## Documentation Index
> Fetch the complete documentation index at: https://docs.porter.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Connections in porter.yaml

> Connect Porter services to 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          |
| `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

```yaml theme={null}
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](https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview) 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).

<Info>
  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.
</Info>

### 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](https://learn.microsoft.com/en-us/azure/active-directory/develop/workload-identity-federation) 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

```yaml theme={null}
services:
  - name: api
    # ...
    connections:
      - type: azureManagedIdentity
        identityName: my-app-identity
        resourceGroup: my-resource-group
```

<Warning>
  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.
</Warning>

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

***

## 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](https://cloud.google.com/docs/authentication/application-default-credentials), and Porter handles the identity binding for your service.

### Prerequisites

Before adding this connection to your service, you must:

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

```yaml theme={null}
services:
  - name: api
    # ...
    connections:
      - type: gcpServiceAccount
        serviceAccountEmail: my-app@my-project.iam.gserviceaccount.com
```

<Warning>
  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.
</Warning>

<Info>
  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.
</Info>

***

## Cloud SQL Connection (GCP)

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

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

### 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

```yaml theme={null}
services:
  - name: api
    # ...
    connections:
      - type: cloudSql
        config:
          cloudSqlConnectionName: my-project-123456:us-east1:my-instance
          cloudSqlDatabasePort: 5432
          cloudSqlServiceAccount: my-service-account
```

<Info>
  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.
</Info>

***

## Persistent Disk Connection

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

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

### Field Reference

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

### Example

```yaml theme={null}
services:
  - name: api
    # ...
    connections:
      - type: disk
        config:
          diskName: my-persistent-data
```

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

***

## Multiple Connections

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

```yaml theme={null}
services:
  - name: api
    # ...
    connections:
      - type: awsRole
        role: api-s3-access
      - type: disk
        config:
          diskName: cache-storage
```

***

## Related Documentation

* [Web Services](/applications/configuration-as-code/services/web-service) - Web service configuration
* [Worker Services](/applications/configuration-as-code/services/worker-service) - Worker service configuration
* [Job Services](/applications/configuration-as-code/services/job-service) - Job service configuration
* [porter.yaml Reference](/applications/configuration-as-code/reference) - Complete configuration reference