> ## 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.
# Load Balancing
> Configure direct load balancers to expose workload ports through cloud load balancers with geo DNS routing in each deployment location.
## Direct Load Balancer
The Direct Load Balancer allows you to expose your [Workload's Ports](/reference/workload/containers#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](/reference/ipset), 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](/reference/ipset) to the direct load balancer via `loadBalancer.direct.ipSet`. See [IP Set — Workload Binding](/reference/ipset#workload) for configuration steps.
## Example Configuration
```yaml theme={null}
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
```
```json theme={null}
{
"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
}
}
]
}
}
}
}
```
## Geo Location Headers
The Geo Location Headers feature allows you to include geographic information in inbound HTTP requests.
When enabled, this feature adds headers containing geographic information to incoming HTTP requests. These headers can provide valuable data about the origin of the request, including the Autonomous System Number (ASN), city, country, and region.
This product includes GeoLite2 data created by MaxMind, available from
[https://www.maxmind.com](https://www.maxmind.com).
### 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
1. **Enabling the Feature**: Set `geoLocation.enabled` to `true` to activate the Geo Location Headers feature.
2. **Header Configuration**: When enabled, you must specify at least one header (ASN, city, country, or region).
3. **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.
4. **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 Number
* `X-GeoIP-City`: Containing the city name
* `X-GeoIP-Country`: Containing the country name
* `X-GeoIP-Region`: Containing the region name
```yaml theme={null}
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](/reference/workload/firewall#geo-filtering)