Skip to main content

Listeners

Define entry points for traffic on your gateway with protocol, port, and hostname configuration.

Overview​

Listeners determine how your gateway accepts incoming traffic. Each listener specifies:

  • Protocol - The type of traffic to accept (HTTPS, TLS, TCP)
  • Port - The network port to listen on
  • Hostname - The domain name for the listener

Adding a Listener​

Step-by-Step​

  1. Go to your gateway
  2. Click the Listeners tab
  3. Click Add Listener
  4. Configure:
FieldDescriptionExample
NameUnique identifier for the listenerapi-listener
ProtocolType of trafficHTTPS, TLS, or TCP
PortNetwork port443, 8443
HostnameYour domain nameapi.example.com
  1. Click Save

Protocols​

HTTPS​

Secure HTTP traffic with automatic TLS certificates:

  • Port: Typically 443 or 8443
  • Certificate: Automatically provisioned via Let's Encrypt
  • Use case: Web applications, REST APIs
ParameterValue
Nameweb-https
ProtocolHTTPS
Port443
Hostnameapp.example.com

TLS​

Generic TLS-encrypted traffic:

  • Port: Any port (commonly 443, 8443)
  • Certificate: Automatically provisioned
  • Use case: Secure non-HTTP protocols
ParameterValue
Namesecure-grpc
ProtocolTLS
Port8443
Hostnamegrpc.example.com

TCP​

Raw TCP traffic without encryption:

  • Port: Any port
  • No TLS: Traffic is unencrypted
  • Use case: Internal services, custom protocols
ParameterValue
Nametcp-service
ProtocolTCP
Port9000
TCP Protocol

TCP listeners do not provide encryption. Use only for internal services or when encryption is handled at the application level.

Listener Status​

DNS Status​

Each listener with a hostname shows its DNS configuration status:

StatusDescription
DNS ConfiguredDomain correctly points to gateway IP
DNS Not ConfiguredDomain does not point to gateway IP
DNS UnknownStatus check has not completed yet

Configure DNS by adding an A record pointing your domain to the gateway IP address.

TLS Certificate Status​

For HTTPS and TLS listeners, certificate status is displayed:

StatusDescription
TLS Certificate ReadyCertificate is valid and active
TLS Certificate Not ReadyCertificate is being provisioned or has an issue
TLS Certificate UnknownCertificate status check has not completed yet

Certificates are automatically:

  • Provisioned when DNS is configured correctly
  • Renewed before expiration
  • Managed via Let's Encrypt

Conditions​

Listeners display detailed status conditions:

SeverityMeaning
InfoInformational status
WarningPotential issue requiring attention
ErrorProblem preventing normal operation
CriticalSevere issue requiring immediate action

Common conditions:

  • Accepted - Listener configuration is valid
  • Programmed - Listener is active and routing traffic
  • ResolvedRefs - All referenced resources exist

Managing Listeners​

Editing a Listener​

  1. Find the listener in the list
  2. Click Edit
  3. Modify the configuration
  4. Click Save
Port Changes

Changing the port of a listener will briefly interrupt traffic on that listener.

Deleting a Listener​

  1. Find the listener in the list
  2. Click Delete
  3. Confirm deletion
warning

Deleting a listener removes all routes associated with it and immediately stops traffic on that port/hostname combination.

Multiple Listeners​

A gateway can have multiple listeners for different use cases:

Same Domain, Different Ports​

NameProtocolPortHostname
httpsHTTPS443api.example.com
grpcTLS9090api.example.com

Multiple Domains​

NameProtocolPortHostname
appHTTPS443app.example.com
apiHTTPS443api.example.com
adminHTTPS443admin.example.com

Mixed Protocols​

NameProtocolPortHostname
public-httpsHTTPS443app.example.com
internal-tcpTCP5432-

Best Practices​

Use HTTPS for Public Traffic​

Always use HTTPS for internet-facing services:

  • Automatic certificate management
  • Required by modern browsers
  • SEO benefits
  • User trust

Name Listeners Descriptively​

Use clear, descriptive names:

Good: api-https, admin-portal, grpc-service
Bad: listener1, test, l1

Separate Concerns​

Create separate listeners for different purposes:

  • public-https - Customer-facing traffic
  • api-https - API traffic
  • internal-tcp - Internal services

Troubleshooting​

DNS Not Configured​

  1. Verify DNS record exists
  2. Check for typos in hostname
  3. Wait for DNS propagation (up to 10 minutes)
  4. Use dig to verify:
dig app.example.com

Certificate Not Provisioning​

  1. Ensure DNS is configured correctly
  2. Check for CAA records blocking Let's Encrypt
  3. Verify hostname matches DNS exactly
  4. Wait 5-10 minutes after DNS changes

Listener Not Accepting Traffic​

  1. Verify listener status shows "Accepted" and "Programmed"
  2. Check for condition warnings/errors
  3. Ensure port is not blocked by firewall
  4. Verify routes are configured for this listener