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
- Go to your gateway
- Click the Listeners tab
- Click Add Listener
- Configure:
| Field | Description | Example |
|---|---|---|
| Name | Unique identifier for the listener | api-listener |
| Protocol | Type of traffic | HTTPS, TLS, or TCP |
| Port | Network port | 443, 8443 |
| Hostname | Your domain name | api.example.com |
- 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
| Parameter | Value |
|---|---|
| Name | web-https |
| Protocol | HTTPS |
| Port | 443 |
| Hostname | app.example.com |
TLS
Generic TLS-encrypted traffic:
- Port: Any port (commonly 443, 8443)
- Certificate: Automatically provisioned
- Use case: Secure non-HTTP protocols
| Parameter | Value |
|---|---|
| Name | secure-grpc |
| Protocol | TLS |
| Port | 8443 |
| Hostname | grpc.example.com |
TCP
Raw TCP traffic without encryption:
- Port: Any port
- No TLS: Traffic is unencrypted
- Use case: Internal services, custom protocols
| Parameter | Value |
|---|---|
| Name | tcp-service |
| Protocol | TCP |
| Port | 9000 |
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:
| Status | Description |
|---|---|
| DNS Configured | Domain correctly points to gateway IP |
| DNS Not Configured | Domain does not point to gateway IP |
| DNS Unknown | Status 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:
| Status | Description |
|---|---|
| TLS Certificate Ready | Certificate is valid and active |
| TLS Certificate Not Ready | Certificate is being provisioned or has an issue |
| TLS Certificate Unknown | Certificate 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:
| Severity | Meaning |
|---|---|
| Info | Informational status |
| Warning | Potential issue requiring attention |
| Error | Problem preventing normal operation |
| Critical | Severe 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
- Find the listener in the list
- Click Edit
- Modify the configuration
- Click Save
Changing the port of a listener will briefly interrupt traffic on that listener.
Deleting a Listener
- Find the listener in the list
- Click Delete
- Confirm deletion
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
| Name | Protocol | Port | Hostname |
|---|---|---|---|
| https | HTTPS | 443 | api.example.com |
| grpc | TLS | 9090 | api.example.com |
Multiple Domains
| Name | Protocol | Port | Hostname |
|---|---|---|---|
| app | HTTPS | 443 | app.example.com |
| api | HTTPS | 443 | api.example.com |
| admin | HTTPS | 443 | admin.example.com |
Mixed Protocols
| Name | Protocol | Port | Hostname |
|---|---|---|---|
| public-https | HTTPS | 443 | app.example.com |
| internal-tcp | TCP | 5432 | - |
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 trafficapi-https- API trafficinternal-tcp- Internal services
Troubleshooting
DNS Not Configured
- Verify DNS record exists
- Check for typos in hostname
- Wait for DNS propagation (up to 10 minutes)
- Use
digto verify:
dig app.example.com
Certificate Not Provisioning
- Ensure DNS is configured correctly
- Check for CAA records blocking Let's Encrypt
- Verify hostname matches DNS exactly
- Wait 5-10 minutes after DNS changes
Listener Not Accepting Traffic
- Verify listener status shows "Accepted" and "Programmed"
- Check for condition warnings/errors
- Ensure port is not blocked by firewall
- Verify routes are configured for this listener