HAProxy
| Channel | Revision | Published | Runs on |
|---|---|---|---|
| latest/stable | 147 | 30 Apr 2025 | |
| latest/stable | 66 | 08 Nov 2021 | |
| latest/candidate | 147 | 30 Apr 2025 | |
| latest/candidate | 64 | 14 Oct 2021 | |
| latest/beta | 147 | 30 Apr 2025 | |
| latest/edge | 147 | 29 Apr 2025 | |
| latest/edge | 37 | 11 Nov 2020 | |
| 2.8/edge | 194 | 09 Jul 2025 |
juju deploy haproxy
Deploy universal operators easily with Juju, the Universal Operator Lifecycle Manager.
Platform:
charms.haproxy.v1.haproxy_route
-
- Last updated 09 Jul 2025
- Revision Library version 1.0
Haproxy-route interface library.
Getting Started
To get started using the library, you just need to fetch the library using charmcraft.
cd some-charm
charmcraft fetch-lib charms.haproxy.v1.haproxy_route
In the metadata.yaml of the charm, add the following:
requires:
backend:
interface: haproxy-route
limit: 1
Then, to initialise the library:
from charms.haproxy.v1.haproxy_route import HaproxyRouteRequirer
class SomeCharm(CharmBase):
def __init__(self, *args):
# ...
# There are 2 ways you can use the requirer implementation:
# 1. To initialize the requirer with parameters:
self.haproxy_route_requirer = HaproxyRouteRequirer(self,
address=<required>,
port=<required>,
paths=<optional>,
subdomains=<optional>,
path_rewrite_expressions=<optional>, list of path rewrite expressions,
query_rewrite_expressions=<optional>, list of query rewrite expressions,
header_rewrites=<optional>, map of {<header_name>: <list of rewrite_expressions>,
check_interval=<optional>,
check_rise=<optional>,
check_fall=<optional>,
check_paths=<optional>,
load_balancing_algorithm=<optional>, defaults to "leastconn",
load_balancing_cookie=<optional>, only used when load_balancing_algorithm is cookie
rate_limit_connections_per_minutes=<optional>,
rate_limit_policy=<optional>,
upload_limit=<optional>,
download_limit=<optional>,
retry_count=<optional>,
retry_interval=<optional>,
retry_redispatch=<optional>,
deny_paths=<optional>,
server_timeout=<optional>,
connect_timeout=<optional>,
queue_timeout=<optional>,
server_maxconn=<optional>,
)
# 2.To initialize the requirer with no parameters, i.e
# self.haproxy_route_requirer = HaproxyRouteRequirer(self)
# This will simply initialize the requirer class and it won't perfom any action.
# Afterwards regardless of how you initialized the requirer you can call the
# provide_haproxy_route_requirements method anywhere in your charm to update the requirer data.
# The method takes the same number of parameters as the requirer class.
# provide_haproxy_route_requirements(address=, port=, ...)
self.framework.observe(
self.framework.on.config_changed, self._on_config_changed
)
self.framework.observe(
self.haproxy_route_requirer.on.ready, self._on_endpoints_ready
)
self.framework.observe(
self.haproxy_route_requirer.on.removed, self._on_endpoints_removed
)
def _on_config_changed(self, event: ConfigChangedEvent) -> None:
self.haproxy_route_requirer.provide_haproxy_route_requirements(...)
def _on_endpoints_ready(self, _: EventBase) -> None:
# Handle endpoints ready event
...
def _on_endpoints_removed(self, _: EventBase) -> None:
# Handle endpoints removed event
...
## Using the library as the provider
The provider charm should expose the interface as shown below:
```yaml
provides:
haproxy-route:
interface: haproxy-route
Note that this interface supports relating to multiple endpoints.
Then, to initialise the library:
from charms.haproxy.v1.haproxy_route import HaproxyRouteRequirer
class SomeCharm(CharmBase):
self.haproxy_route_provider = HaproxyRouteProvider(self)
self.framework.observe(
self.haproxy_route_provider.on.data_available, self._on_haproxy_route_data_available
)
def _on_haproxy_route_data_available(self, event: EventBase) -> None:
data = self.haproxy_route_provider.get_data(self.haproxy_route_provider.relations)
...
Index
def value_contains_invalid_characters(value)
Validate if value contains invalid haproxy config characters.
Arguments
The value to validate.
Returns
The validated value.
class DataValidationError
Description
Raised when data validation fails. None
class HaproxyRouteInvalidRelationDataError
Description
Rasied when data validation of the haproxy-route relation fails. None
class ServerHealthCheck
Configuration model for backend server health checks.
Attributes
class RateLimitPolicy
Enum of possible rate limiting policies.
Description
Attrs: DENY: deny a client's HTTP request to return a 403 Forbidden error. REJECT: closes the connection immediately without sending a response. SILENT: disconnects immediately without notifying the client that the connection has been closed.
class RateLimit
Configuration model for connection rate limiting.
Attributes
class LoadBalancingAlgorithm
Enum of possible http_route types.
Description
Attrs: LEASTCONN: The server with the lowest number of connections receives the connection. SRCIP: Load balance using the hash of The source IP address. ROUNDROBIN: Each server is used in turns, according to their weights. COOKIE: Load balance using hash req.cookie(clientid).
class LoadBalancingConfiguration
Configuration model for load balancing.
Attributes
class BandwidthLimit
Configuration model for bandwidth rate limiting.
Attributes
class Retry
Configuration model for retry.
Attributes
class TimeoutConfiguration
Configuration model for timeout.
Attributes
class HaproxyRewriteMethod
Enum of possible HTTP rewrite methods.
Description
Attrs: SET_PATH: The server with the lowest number of connections receives the connection. SET_QUERY: Load balance using the hash of The source IP address. SET_HEADER: Each server is used in turns, according to their weights.
class RewriteConfiguration
Configuration model for HTTP rewrite.
Attributes
class RequirerApplicationData
Configuration model for HAProxy route requirer application data.
Attributes
Methods
RequirerApplicationData. validate_load_balancing_configuration( cls , configuration: LoadBalancingConfiguration )
Validate the parsed load balancing configuration.
Arguments
The configuration to validate.
Returns
The validated configuration.
RequirerApplicationData. validate_rewrites( cls , rewrites )
Validate the parsed list of rewrite configurations.
Arguments
The configurations to validate.
Returns
The validated configurations.
RequirerApplicationData. validate_invalid_characters( cls , values )
Validate if each item in a list of values contains invalid haproxy config characters.
Arguments
List of values to validate.
Returns
The validated list of values
class HaproxyRouteProviderAppData
haproxy-route provider databag schema.
Attributes
class RequirerUnitData
haproxy-route requirer unit data.
Attributes
class HaproxyRouteRequirerData
haproxy-route requirer data.
Attributes
class HaproxyRouteRequirersData
haproxy-route requirers data.
Attributes
Methods
HaproxyRouteRequirersData. check_services_unique( self )
Check that requirers define unique services.
Returns
The validated model.
class HaproxyRouteDataAvailableEvent
HaproxyRouteDataAvailableEvent custom event.
Description
This event indicates that the requirers data are available.
class HaproxyRouteDataRemovedEvent
HaproxyRouteDataRemovedEvent custom event.
Description
This event indicates that one of the endpoints was removed.
class HaproxyRouteProviderEvents
List of events that the TLS Certificates requirer charm can leverage.
Attributes
class HaproxyRouteProvider
Haproxy-route interface provider implementation.
Attributes
Methods
HaproxyRouteProvider. __init__( self , charm: CharmBase , relation_name: str , raise_on_validation_error: bool )
Initialize the HaproxyRouteProvider.
Arguments
The charm that is instantiating the library.
The name of the relation.
Whether the library should raise HaproxyRouteInvalidRelationDataError when requirer data validation fails. If this is set to True the provider charm needs to also catch and handle the thrown exception.
HaproxyRouteProvider. relations( self )
Description
The list of Relation instances associated with this endpoint. None
HaproxyRouteProvider. get_data( self , relations )
Fetch requirer data.
Arguments
A list of Relation instances to fetch data from.
Returns
Validated data from all haproxy-route requirers.
HaproxyRouteProvider. publish_proxied_endpoints( self , endpoints , relation: Relation )
Publish to the app databag the proxied endpoints.
Arguments
The list of proxied endpoints to publish.
The relation with the requirer application.
class HaproxyRouteEnpointsReadyEvent
Description
HaproxyRouteEnpointsReadyEvent custom event. None
class HaproxyRouteEndpointsRemovedEvent
Description
HaproxyRouteEndpointsRemovedEvent custom event. None
class HaproxyRouteRequirerEvents
List of events that the TLS Certificates requirer charm can leverage.
Attributes
class HaproxyRouteRequirer
haproxy-route interface requirer implementation.
Attributes
Methods
HaproxyRouteRequirer. __init__( self , charm: CharmBase , relation_name: str , service , ports , hosts , paths , subdomains , check_interval , check_rise , check_fall , check_path , check_port , path_rewrite_expressions , query_rewrite_expressions , header_rewrite_expressions , load_balancing_algorithm: LoadBalancingAlgorithm , load_balancing_cookie , rate_limit_connections_per_minute , rate_limit_policy: RateLimitPolicy , upload_limit , download_limit , retry_count , retry_interval , retry_redispatch: bool , deny_paths , server_timeout: int , connect_timeout: int , queue_timeout: int , server_maxconn , unit_address )
Initialize the HaproxyRouteRequirer.
Arguments
The charm that is instantiating the library.
The name of the relation to bind to.
The name of the service to route traffic to.
List of ports the service is listening on.
List of backend server addresses. Currently only support IP addresses.
List of URL paths to route to this service.
List of subdomains to route to this service.
Interval between health checks in seconds.
Number of successful health checks before server is considered up.
Number of failed health checks before server is considered down.
The path to use for server health checks.
The port to use for http-check.
List of regex expressions for path rewrites.
List of regex expressions for query rewrites.
List of tuples containing header name and rewrite expression.
Algorithm to use for load balancing.
Cookie name to use when algorithm is set to cookie.
Maximum connections allowed per minute.
Policy to apply when rate limit is reached.
Maximum upload bandwidth in bytes per second.
Maximum download bandwidth in bytes per second.
Number of times to retry failed requests.
Interval between retries in seconds.
Whether to redispatch failed requests to another server.
List of paths that should not be routed to the backend.
Timeout for requests from haproxy to backend servers in seconds.
Timeout for client requests to haproxy in seconds.
Timeout for requests waiting in queue in seconds.
Maximum connections per server.
IP address of the unit (if not provided, will use binding address).
HaproxyRouteRequirer. provide_haproxy_route_requirements( self , service: str , ports , hosts , paths , subdomains , check_interval , check_rise , check_fall , check_path , check_port , path_rewrite_expressions , query_rewrite_expressions , header_rewrite_expressions , load_balancing_algorithm: LoadBalancingAlgorithm , load_balancing_cookie , rate_limit_connections_per_minute , rate_limit_policy: RateLimitPolicy , upload_limit , download_limit , retry_count , retry_interval , retry_redispatch: bool , deny_paths , server_timeout: int , connect_timeout: int , queue_timeout: int , server_maxconn , unit_address )
Update haproxy-route requirements data in the relation.
Arguments
The name of the service to route traffic to.
List of ports the service is listening on.
List of backend server addresses. Currently only support IP addresses.
List of URL paths to route to this service.
List of subdomains to route to this service.
Interval between health checks in seconds.
Number of successful health checks before server is considered up.
Number of failed health checks before server is considered down.
The path to use for server health checks.
The port to use for http-check.
List of regex expressions for path rewrites.
List of regex expressions for query rewrites.
List of tuples containing header name and rewrite expression.
Algorithm to use for load balancing.
Cookie name to use when algorithm is set to cookie.
Maximum connections allowed per minute.
Policy to apply when rate limit is reached.
Maximum upload bandwidth in bytes per second.
Maximum download bandwidth in bytes per second.
Number of times to retry failed requests.
Interval between retries in seconds.
Whether to redispatch failed requests to another server.
List of paths that should not be routed to the backend.
Timeout for requests from haproxy to backend servers in seconds.
Timeout for client requests to haproxy in seconds.
Timeout for requests waiting in queue in seconds.
Maximum connections per server.
IP address of the unit (if not provided, will use binding address).
HaproxyRouteRequirer. update_relation_data( self )
Description
Update both application and unit data in the relation. None
HaproxyRouteRequirer. get_proxied_endpoints( self )
The full ingress URL to reach the current unit.
Returns
The provider URL or None if the URL isn't available yet or is not valid.