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

> ## Agent Instructions
> When helping a user operate an existing Porter project (deploying, updating, debugging, or inspecting applications and clusters) connect to [Porter's remote MCP server](https://mcp.porter.run) first and use its tools before falling back to the Porter CLI, `porter.yaml`, or dashboard workflows. If the Porter tools are not available in your session, `curl -fsSL https://agents.porter.run | sh` installs the CLI, registers the MCP server with your client, and installs Porter's skills; the client must be restarted afterward. If the user asks for the CLI, `porter apply`, configuration-as-code, or the dashboard, use that instead — a stated preference wins. Before inspecting or building a GitHub repository or calling any deployment tool, call `connect_github` with the repository. Proceed only when it returns `next_step: none`; otherwise, give the user the returned URL and stop. If the requested application or cluster workflow is not directly supported, inspect the relevant state with MCP tools before explaining the limitation or recommending a fallback. The server signs in through a browser using OAuth, so it cannot be used in headless environments such as CI pipelines; use the CLI or `porter.yaml` there.

# Load balancers

> Configure the default, private, and application load balancers that route traffic into your AWS, GCP, and Azure Porter clusters

The **Load Balancers** tab controls how traffic reaches your cluster. To open it, click **Infrastructure** in the left sidebar, select your cluster, and click **Load Balancers**.

Every cluster has a default public load balancer. You can add a [private load balancer](#private-load-balancer) for internal traffic, and on AWS and GCP an [application load balancer](#application-load-balancer) for layer 7 traffic. Each load balancer shows as a separate card. Each service selects the load balancer that serves it, so you can move domains between load balancers one at a time.

| Load balancer | AWS | GCP | Azure |
| - | - | - | - |
| [Default load balancer](#default-load-balancer) | Configurable | Managed by Porter | Managed by Porter |
| [Application load balancer](#application-load-balancer) | ✓ | ✓ | |
| [Private load balancer](#private-load-balancer) | ✓ | ✓ | ✓ |

## Default load balancer

Porter provisions a public load balancer for each cluster. On AWS, you can configure it from the **Default load balancer** card. On GCP and Azure, Porter manages it and it has no settings.

> [!WARNING]
>
> Changing the load balancer type causes downtime while the load balancer is recreated.

| Type | Description |
| - | - |
| **NLB** | Network Load Balancer. The default. Operates at layer 4, routes TCP/UDP traffic, and provides ultra-low latency and high throughput. |
| **ALB** | Application Load Balancer. Operates at layer 7, routes HTTP/HTTPS traffic, and supports wildcard domains, ACM certificates, and WAFv2. |

> [!NOTE]
>
> Do not set the default load balancer type to **ALB** on new clusters. Add an [application load balancer](#application-load-balancer) instead. Porter continues to support the **ALB** type on clusters that already use it.

When the type is **ALB**, the following settings become available. See [Custom domains with ALB](https://docs.porter.run/applications/configure/custom-domains-alb) for end-to-end setup instructions.

| Setting | Description |
| - | - |
| **Wildcard domains** | Domains to issue ACM certificates for. Do not include the `*.` prefix. Porter creates a SAN for `*.<domain>` automatically. Comma-separate multiple domains. |
| **IP allow list** | Comma-separated list of CIDR ranges (for example, `160.72.72.58/32,160.72.72.59/32`) permitted to reach the ALB. |
| **Certificate ARNs** | Existing ACM certificate ARNs to attach to the ALB. |
| **AWS tags** | Key/value tags applied to the ALB and related AWS resources. |
| **WAFv2 enabled** | Attaches a Regional WAFv2 web ACL to the ALB. |
| **WAFv2 ARN** | ARN of the Regional WAFv2 web ACL to attach. Only Regional WAFv2 is supported. |

## Application load balancer

This setting adds a public layer 7 application load balancer (ALB) to the cluster. It does not replace the default load balancer.

| Setting | Description |
| - | - |
| **Add application load balancer** | Porter provisions a public layer 7 ALB in front of the cluster. The ALB listens on port 80 and port 443 and terminates TLS at the edge. The ALB does not redirect HTTP traffic to HTTPS. |
| **Root domains** | The domains that this load balancer serves. Write one domain in each row, for example `alb.example.com`. Porter issues one wildcard certificate for each root domain. Each certificate includes `*.<root>`, so the load balancer can serve all subdomains of that root domain. On AWS, you must give a minimum of one root domain. On GCP, root domains are optional. Without one, the ALB serves plain HTTP only. |
| **DNS provider** | The provider that hosts the root domains. Porter uses it to validate the certificate. **Cloudflare** is supported on AWS and GCP. **AWS Route53** is also supported on AWS. |
| **DNS credentials** | API token for Cloudflare. This field shows only when the DNS provider is Cloudflare. The token must have permission to read the zone that serves each root domain, and to create DNS records in that zone. Route53 needs no credentials, because Porter writes the records with the AWS account of the cluster. |
| **Web application firewall** | Porter provisions a web application firewall policy named `porter-alb-waf-<hash>` and attaches it to the ALB. On AWS, this is a Regional WAFv2 web ACL. On GCP, this is a Cloud Armor security policy. |

### Choose the root domains

A certificate covers the root domain and one level below it. For example, `ops.example.com` covers `api.ops.example.com`, but not `v2.api.ops.example.com`. More than one cluster can use the same root domain.

### Certificate validation

On AWS, the ALB uses an ACM certificate. On GCP, Porter issues the certificates with cert-manager through Cloudflare. Porter writes the validation records for both DNS providers. Porter does not create hosted zones or the records that point at the ALB. Do not delete the validation records, because they are used to renew the certificate.

* **Route53** (AWS only): the AWS account of the cluster must have a public hosted zone for the root domain or for a parent domain. If the zone is in a different AWS account, see [Delegate a subdomain to the cluster account](#delegate-a-subdomain-to-the-cluster-account).
* **Cloudflare**: the token in **DNS credentials** must have read and write permissions for the zone of each root domain.

On AWS, if the zone has CAA records, add CAA records with the tags `issue` and `issuewild` and the value `amazon.com`. To see the CAA records, run `dig CAA example.com`. After you fix the CAA records, Porter requests a new certificate.

### Delegate a subdomain to the cluster account

Porter cannot write validation records to a Route53 zone in a different AWS account. If a different AWS account hosts `example.com`, delegate a subdomain, for example `ops.example.com`, to the AWS account of the cluster. Do the steps in this sequence to prevent downtime.

1. In the AWS account of the cluster, create a public hosted zone for `ops.example.com`.
2. Copy all records of `ops.example.com` from the parent zone to the new zone. Copy all record types, for example `TXT` and `_dmarc` records.
3. In the parent zone, add an `NS` record for `ops.example.com`. Use the four name servers of the new zone as the values.
4. Run `dig +short NS ops.example.com` until the command shows the name servers of the new zone.
5. Add `ops.example.com` as a root domain of the ALB.

> [!WARNING]
>
> Do step 2 before step 3. After the `NS` record propagates, DNS resolvers read the records of the subdomain only from the new zone.

> [!NOTE]
>
> If ACM cannot validate the certificate, the cluster update retries for 2 hours and then fails. A failed ALB update can block other changes to the cluster. Fix the DNS zone and update the cluster again, or remove the ALB.

### Point DNS at the ALB

The ALB has its own address, so the records that point at the default load balancer do not change. For each root domain, point a wildcard record at the ALB, for example `*.alb.example.com`. On AWS, this address is a hostname, so you must use a `CNAME` record or a Route53 alias record. On GCP, this address is an IP address, so use an `A` record. After Porter provisions the ALB, the address shows in the **Custom domains** area of the **Networking** tab of a service.

You can also point one record for each domain at the ALB instead of a wildcard record. A record for a specific domain has priority over a wildcard record. A wildcard record does not match the root domain, so a service on the root domain needs its own record.

### Web application firewall

Porter creates the firewall policy with a default allow-all rule and does not add other rules. Add your own rules in the AWS WAF console or the Google Cloud Armor console, for example managed rule groups, rate-based rules, or IP allowlists. Porter does not change these rules. On AWS, Porter supports only Regional WAFv2.

If you turn off this setting, Porter detaches the policy but does not delete it, so your rules remain if you turn on the setting again.

### Route a service through the ALB

After the ALB serves traffic, the **Networking** tab of each web service shows a **Public ALB** option next to **Public LB**. In `porter.yaml`, use [`loadBalancers`](https://docs.porter.run/applications/configuration-as-code/services/web-service#loadbalancers):

```yaml theme={null}
services:
  - name: api
    type: web
    loadBalancers:
      - public_alb
    domains:
      - name: api.alb.example.com
```

Each domain of the service must be a root domain, or exactly one level below a root domain. A change to the load balancer of a service takes effect at the next deployment.

### Move a domain to the ALB with no downtime

A service can use both load balancers at the same time, so you can move a domain with no downtime.

1. Add `public_alb` and keep `public_lb`. In the **Networking** tab, select **Public LB** and **Public ALB**. Then deploy the app.

   ```yaml theme={null}
   loadBalancers:
     - public_lb
     - public_alb
   ```

2. Change the DNS record of the domain to the address of the ALB.

3. Wait a minimum of 10 minutes. If the TTL of the old record is longer, wait for the full TTL.

4. Remove `public_lb`. Then deploy the app.

To move the traffic in small steps, use weighted records in Route53 or a load balancer in Cloudflare before step 4.

> [!WARNING]
>
> Until you remove `public_lb`, traffic through the default load balancer does not go through the web application firewall.

`*.onporter.run` domains do not work on the ALB, so move these services to a custom domain first. To delete the default load balancer after the move, contact Porter support.

## Private load balancer

In addition to the default public load balancer, you can provision an **internal load balancer** that only accepts traffic from inside your cluster's network (or networks peered to it). Use this when you want to expose services to internal clients, for example an internal admin tool, a service consumed only by other networks, or a workload that must not be reachable from the public internet.

> [tab] AWS
>
> | Setting | Description |
> | - | - |
> | **Add private load balancer** | Provisions a private NLB alongside the default public load balancer. Only NLB private load balancers are supported. |

> [tab] GCP
>
> | Setting | Description |
> | - | - |
> | **Add private load balancer** | Provisions a GKE internal load balancer alongside the default public load balancer. |

> [tab] Azure
>
> | Setting | Description |
> | - | - |
> | **Add private load balancer** | Provisions an internal Azure load balancer alongside the default public load balancer. |

Once enabled, you must configure a DNS provider so Porter can issue and renew TLS certificates for ingress hostnames attached to the private load balancer. **Cloudflare** is supported on every cloud. **AWS Route53** is also supported on AWS.

> [!TIP]
>
> We recommend serving private ingress from a dedicated internal zone (for example, `internal.example.com`) rather than a zone that also serves production domains. This avoids record conflicts with production DNS and keeps DNS access scoped to internal hostnames only.
>
> If that isn't practical, you can still keep credentials off your production zone. See [Delegating certificate validation](#delegating-certificate-validation).

> [tab] Cloudflare
>
> | Setting | Description |
> | - | - |
> | **DNS credentials** | API token for Cloudflare. The token must have permission to create and delete `TXT` records on the zones used by your private ingress hostnames. |
>
> Save the credentials before updating the cluster. You can rotate the token later with **Edit credentials**, or remove the integration entirely with **Remove**. Removing credentials stops certificate issuance and renewal for private load balancer ingress.

> [tab] Route53 (AWS only)
>
> Porter authenticates to Route53 through an [EKS Pod Identity](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html) scoped to a single hosted zone, so no API tokens are stored.
>
> | Setting | Description |
> | - | - |
> | **Route53 domain** | The DNS zone the private ingress serves certificates for (for example, `internal.example.com`). At install time, Porter resolves the matching public Route53 hosted zone in the same AWS account and provisions a cert-manager pod identity scoped to that zone. |
>
> The domain must already exist as a public hosted zone in the cluster's AWS account, and the zone name must match the domain exactly. If only a parent zone is present (for example, `example.com` for a domain of `internal.example.com`), Porter cannot issue certificates for it, and the domain requires its own dedicated hosted zone.

### Delegating certificate validation

By default, the DNS credentials you give Porter need write access to the zone that hosts your private hostnames. If those hostnames live under a zone that also serves production domains, those credentials can reach your production records too, which is more privilege than you may want to grant.

You can avoid that by delegating just the validation records to a separate, lower-privilege zone. You add a `CNAME` from each validation record in your zone to the delegated zone, then scope the credentials to that zone only. Porter handles the rest with no extra configuration on its side.

> [!NOTE]
>
> On AWS Route53 this isn't necessary. Create a dedicated hosted zone for the subdomain and provide it as the **Route53 domain**; Porter scopes access to that zone directly.

**1. Add the delegation `CNAME` records.** Pick a low-privilege zone to hold the validation records (for example, `acme.example-internal.com`). In the zone that hosts your private hostnames, add a `CNAME` for each validation record, pointing at a record in the delegated zone:

```
_acme-challenge.app.internal.example.com.  CNAME  _acme-challenge.acme.example-internal.com.
```

**2. Scope the credentials to the delegated zone.** Create an API token scoped to the **delegated zone only**, with:

* `Zone.DNS` → Edit
* `Zone.Zone` → Read

The token does not need any access to your production zone.

**3. Verify the delegation.** Confirm the `CNAME` resolves publicly:

```bash theme={null}
dig +short CNAME _acme-challenge.app.internal.example.com
# expected: _acme-challenge.acme.example-internal.com.
```

Certificates are issued automatically when you attach a hostname to a service through its [load balancer config](https://docs.porter.run/applications/configuration-as-code/services/web-service.md#loadbalancerconfig). Porter then publishes each validation record into the delegated zone through the `CNAME`.

If you need help setting this up, reach out to Porter support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.