Documentation Index
Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
Use this file to discover all available pages before exploring further.
Direct Load Balancer
The Direct Load Balancer allows you to expose your Workload’s Ports directly through a cloud load balancer in each location where the workload is running.
Overview
- A direct load balancer is created in each location where the workload is running
- Each location obtains a public address configured as a Geo DNS target, using standard latency-based routing for traffic distribution across locations
- Domains do not need to be registered — traffic is routed directly to the workload through the load balancer
- The workload’s DNS record can be configured as a CNAME target for any source domains you wish to accept traffic for
- Users are responsible for configuring TLS certificates on the workload if required
Configuration
The Direct Load Balancer is enabled on a workload using loadBalancer.direct.enabled, with the following properties:
direct
The direct object contains the configuration for the Direct Load Balancer.
| Property | Type | Description |
|---|
enabled | boolean | When set to false, this load balancer will be stopped and no charges will accrue |
ports | array | A list of ports that will be exposed by this load balancer |
ipSet | string (optional) | A link to an IP Set, used to reserve a static public IP per location |
ports
Each port in the ports array is added to the cloud load balancer to control the routing behavior:
| Property | Type | Description |
|---|
externalPort | number | The port that is available publicly. Must be between 22 and 32768 |
protocol | string | The protocol that is exposed publicly. Can be either ‘TCP’ or ‘UDP’ |
scheme | string (optional) | Overrides the default https URL scheme that will be used for links in the UI and status. Valid values are ‘http’, ‘tcp’, ‘https’, ‘ws’, ‘wss’ |
containerPort | object | The port on the container that will receive this traffic |
Static IP Addresses
By default, the public IP assigned to each location is not reserved and may change. To assign a static public IP per location, link an IP Set to the direct load balancer via loadBalancer.direct.ipSet. See IP Set — Workload Binding for configuration steps.
Example Configuration
kind: workload
name: example-workload
spec:
loadBalancer:
direct:
enabled: true
ports:
- externalPort: 80
protocol: TCP
scheme: http
containerPort:
port: 8080
- externalPort: 443
protocol: TCP
scheme: https
containerPort:
port: 8443
- externalPort: 9000
protocol: UDP
containerPort:
port: 9000
{
"kind": "workload",
"name": "example-workload",
"spec": {
"loadBalancer": {
"direct": {
"enabled": true,
"ports": [
{
"externalPort": 80,
"protocol": "TCP",
"scheme": "http",
"containerPort": {
"port": 8080
}
},
{
"externalPort": 443,
"protocol": "TCP",
"scheme": "https",
"containerPort": {
"port": 8443
}
},
{
"externalPort": 9000,
"protocol": "UDP",
"containerPort": {
"port": 9000
}
}
]
}
}
}
}
Configuration
| Parameter | Type | Description |
|---|
enabled | boolean | When set to true, geo location headers will be included on inbound HTTP requests. Existing headers will be replaced. Default is false. |
headers.asn | string | The header name for the Autonomous System Number information. |
headers.city | string | The header name for the city information. |
headers.country | string | The header name for the country information. |
headers.region | string | The header name for the region information. |
Usage Guidelines
-
Enabling the Feature: Set
geoLocation.enabled to true to activate the Geo Location Headers feature.
-
Header Configuration: When enabled, you must specify at least one header (ASN, city, country, or region).
-
Unique Headers: The values for ASN, city, country, and region headers must be unique. You cannot use the same header name for different types of information.
-
Existing Headers: If enabled, this feature will replace any existing headers with the same names in incoming requests.
Notes
- Enabling this feature may have performance implications, as it requires additional processing for each incoming request.
- Enabling this feature has no effect if the workload does not expose an http port.
- Ensure that you comply with all relevant data protection and privacy regulations when using geographic information.
- The accuracy of geographic information may vary and should not be relied upon for critical decision-making without verification.
- Workloads receive the latest ip to geo database on startup.
Example Configuration
This configuration will add the following headers to incoming HTTP requests:
X-GeoIP-ASN: Containing the Autonomous System NumberX-GeoIP-City: Containing the city nameX-GeoIP-Country: Containing the country nameX-GeoIP-Region: Containing the region name
loadBalancer:
geoLocation:
enabled: true
headers:
asn: X-GeoIP-ASN
city: X-GeoIP-City
country: X-GeoIP-Country
region: X-GeoIP-Region
Geo Location Filtering
Geo location headers can be use in conjunction with header filters, to allow/deny http requests from specified places.
Checkout Geo Filtering
