Skip to main content
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 for internal traffic, and on AWS and GCP an 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.

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.
Changing the load balancer type causes downtime while the load balancer is recreated.
Do not set the default load balancer type to ALB on new clusters. Add an 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 for end-to-end setup instructions.

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.

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.
  • 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.
Do step 2 before step 3. After the NS record propagates, DNS resolvers read the records of the subdomain only from the new zone.
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:
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.
  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.
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.
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.
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.
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.

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.
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:
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:
Certificates are issued automatically when you attach a hostname to a service through its load balancer config. 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.