---
updatedAt: 2025-08-27T17:23:22.000Z
agentTools:
  projectIndex: https://documentation.bunnyshell.com/llms.txt
---

# Custom Load Balancer Configuration

# Overview

By default, Bunnyshell automatically provisions ingress and routing for your components. If you wish to use a **custom load balancer** based on your provider, you can do so by adding configuration under the component’s **`hosts`** property.

This property allows you to override the default behavior and integrate directly with provider-specific ingress classes, annotations, or self-managed DNS.

# How It Works

The `hosts` property defines how a component is exposed externally. You can:

* Set a custom hostname and path
* Expose services on specific ports
* Mark a service as public or restrict it to allowed IPs
* Map a Bunnyshell hostname to an external address (CNAME)
* Use self-managed DNS for external domains
* Configure Kubernetes ingress with provider-specific options

# Using Provider Load Balancers

When using your own ingress controller or load balancer, add your configuration under `hosts[*].k8s.ingress`.\
This supports:

* `className` — sets the `ingressClassName` (defaults to `bns-nginx`; use an empty string for no value)
* `annotations` — extra annotations for the ingress resource (e.g., cloud provider–specific ingress settings)
* `tlsSecretName` — TLS secret name for ingress when using `selfManagedDns=true`

# Examples

## Basic Public Service

```yaml
hosts:
  - hostname: backend-${env.unique}.bunnyenv.com
    path: /
    servicePort: 8080
    public: true
```

### External Address (CNAME)

```yaml
hosts:
  - hostname: backend-${env.unique}.bunnyenv.com
    externalAddress: foo.bar.example.com
    path: /
```

### Self-Managed DNS with Custom Ingress Class

```yaml
hosts:
  - hostname: stage-1.my-company.tld
    servicePort: 8080
    selfManagedDns: true
    k8s:
      ingress:
        className: my-own-ingress
        annotations:
          alb.ingress.kubernetes.io/scheme: internal
          alb.ingress.kubernetes.io/group.name: kube-system-internal
```

### Override Displayed URLs

```yaml
hosts:
  - hostname: backend-${env.unique}.bunnyenv.com
    path: /
    servicePort: 8080
    displayPaths:
      - /admin
      - https://mycompany.tld/docs
```

## Notes

* `externalAddress` is incompatible with `servicePort`, `public`, or `selfManagedDns`.
* When `selfManagedDns` is set to `true`, DNS records must be managed by the user.
* `public` is only effective when combined with `security.allowedIps`.
* `displayPaths` can be used to override or hide the default generated component URLs.
* Hostnames can also be injected into environment variables for other components. See the [Variable Interpolation](https://documentation.bunnyshell.com/docs/variable-interpolation) page.