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/stable | 216 | 20 Aug 2025 | |
| 2.8/edge | 228 | 11 Sep 2025 |
juju deploy haproxy
Deploy universal operators easily with Juju, the Universal Operator Lifecycle Manager.
Platform:
charms.haproxy.v0.haproxy_route_tcp
-
- Last updated 22 Aug 2025
- Revision Library version 0.1
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_tcp
In the metadata.yaml of the charm, add the following:
requires:
backend-tcp:
interface: haproxy-route-tcp
limit: 1
Then, to initialise the library:
from charms.haproxy.v0.haproxy_route_tcp import HaproxyRouteTcpRequirer
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_tcp_requirer = HaproxyRouteTcpRequirer(
self,
relation_name="haproxy-route-tcp"
port=<optional> # The port exposed on the provider.
backend_port=<optional> # The port where the backend service is listening.
hosts=<optional> # List of backend server addresses. Currently only support IP addresses.
sni=<optional> # Server name identification. Used to route traffic to the service.
check_interval=<optional> # Interval between health checks in seconds.
check_rise=<optional> # Number of successful health checks
before server is considered up.
check_fall=<optional> # Number of failed health checks before server is considered down.
check_type=<optional> # Can be 'generic', 'mysql', 'postgres', 'redis' or 'smtp'ßß.
check_send=<optional> # Only used in generic health checks,
specify a string to send in the health check request.
check_expect=<optional> # Only used in generic health checks,
specify the expected response from a health check request.
check_db_user=<optional> # Only used if type is postgres or mysql,
specify the user name to enable HAproxy to send a Client Authentication packet.
load_balancing_algorithm=<optional> # Algorithm to use for load balancing.
load_balancing_consistent_hashing=<optional> # Whether to use consistent hashing.
rate_limit_connections_per_minute=<optional> # Maximum connections allowed per minute.
rate_limit_policy=<optional> # Policy to apply when rate limit is reached.
upload_limit=<optional> # Maximum upload bandwidth in bytes per second.
download_limit=<optional> # Maximum download bandwidth in bytes per second.
retry_count=<optional> # Number of times to retry failed requests.
retry_redispatch=<optional> # Whether to redispatch failed requests to another server.
server_timeout=<optional> # Timeout for requests from haproxy
to backend servers in seconds.
connect_timeout=<optional> # Timeout for client requests to haproxy in seconds.
queue_timeout=<optional> # Timeout for requests waiting in queue in seconds.
server_maxconn=<optional> # Maximum connections per server.
ip_deny_list=<optional> # List of source IP addresses to block.
enforce_tls=<optional> # Whether to enforce TLS for all traffic coming to the backend.
tls_terminate=<optional> # Whether to enable tls termination on the dedicated frontend.
unit_address=<optional> # IP address of the unit
(if not provided, will use binding address).
)
# 2.To initialize the requirer with no parameters, i.e
# self.haproxy_route_tcp_requirer = HaproxyRouteTcpRequirer(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_tcp_requirements(port=, ...)
self.framework.observe(
self.framework.on.config_changed, self._on_config_changed
)
self.framework.observe(
self.haproxy_route_tcp_requirer.on.ready, self._on_endpoints_ready
)
self.framework.observe(
self.haproxy_route_tcp_requirer.on.removed, self._on_endpoints_removed
)
def _on_config_changed(self, event: ConfigChangedEvent) -> None:
self.haproxy_route_tcp_requirer.provide_haproxy_route_tcp_requirements(...)
def _on_endpoints_ready(self, _: EventBase) -> None:
# Handle endpoints ready event
if endpoints := self.haproxy_route_tcp_requirer.get_proxied_endpoints():
# Do something with the endpoints information
...
def _on_endpoints_removed(self, _: EventBase) -> None:
# Handle endpoints removed event
...
# 3.To initialize the requirer together with helper methods.
# This will use chaining of the helper methods to populate the requirer
# data attributes.
self.haproxy_tcp_route_requirer = HaproxyRouteTcpRequirer(self, relation_name="") .configure_port(4000) .configure_backend_port(5000) .configure_health_check(60, 5, 5) .configure_rate_limit(10, TCPRateLimitPolicy.SILENT) .update_relation_data()
## Using the library as the provider
The provider charm should expose the interface as shown below:
```yaml
provides:
haproxy-route-tcp:
interface: haproxy-route-tcp
Note that this interface supports relating to multiple endpoints.
Then, to initialise the library:
from charms.haproxy.v0.haproxy_route import HaproxyRouteTcpProvider
class SomeCharm(CharmBase):
self.haproxy_route_tcp_provider = HaproxyRouteTcpProvider(self)
self.framework.observe(
self.haproxy_route_tcp_provider.on.data_available, self._on_haproxy_route_data_available
)
def _on_haproxy_route_data_available(self, event: EventBase) -> None:
data = self.haproxy_route_tcp_provider.get_data(self.haproxy_route_tcp_provider.relations)
# data is an object of the `HaproxyRouteTcpRequirersData` class, see below for the
# available attributes
...
# Publish the endpoints to the requirers
for requirer_data in data.requirers_data:
self.haproxy_route_tcp.publish_proxied_endpoints(
["..."], requirer_data.relation_id
)
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 HaproxyRouteTcpInvalidRelationDataError
Description
Raised when data validation of the haproxy-route relation fails. None
class TCPHealthCheckType
Enum of possible rate limiting policies.
Description
Attrs: GENERIC: deny a client's HTTP request to return a 403 Forbidden error. MYSQL: closes the connection immediately without sending a response. POSTGRES: disconnects immediately without notifying the client that the connection has been closed. REDIS: closes the connection immediately without sending a response. SMTP: closes the connection immediately without sending a response.
class TCPServerHealthCheck
Configuration model for backend server health checks.
Attributes
Methods
TCPServerHealthCheck. check_all_required_fields_set( self )
Check that all required fields for health check are set.
Returns
The validated model.
class TCPRateLimitPolicy
Enum of possible rate limiting policies.
Description
Attrs: REJECT: Send a TCP reset packet to close the connection. SILENT: disconnects immediately without notifying the client that the connection has been closed (no packet sent).
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.
class TCPLoadBalancingConfiguration
Configuration model for load balancing.
Attributes
Methods
TCPLoadBalancingConfiguration. validate_attributes( self )
Check that algorithm-specific configs are only set with their respective algorithm.
Returns
The validated model.
class BandwidthLimit
Configuration model for bandwidth rate limiting.
Attributes
class Retry
Configuration model for retry.
Attributes
class TimeoutConfiguration
Configuration model for timeout.
Attributes
class TcpRequirerApplicationData
Configuration model for HAProxy route requirer application data.
Attributes
Methods
TcpRequirerApplicationData. assign_default_backend_port( self )
Assign a default value to backend_port if not set.
Returns
The model with backend_port default value applied.
Description
The value is equal to the provider port.
TcpRequirerApplicationData. sni_set_when_not_enforcing_tls( self )
Check if sni is configured but TLS is disabled.
Returns
The validated model.
class HaproxyRouteTcpProviderAppData
haproxy-route provider databag schema.
Attributes
class TcpRequirerUnitData
haproxy-route requirer unit data.
Attributes
class HaproxyRouteTcpRequirerData
haproxy-route requirer data.
Attributes
class HaproxyRouteTcpRequirersData
haproxy-route requirers data.
Attributes
Methods
HaproxyRouteTcpRequirersData. check_ports_unique( self )
Check that requirers define unique ports.
Returns
The validated model, with invalid relation IDs updated in
self.relation_ids_with_invalid_data
class HaproxyRouteTcpDataAvailableEvent
HaproxyRouteDataAvailableEvent custom event.
Description
This event indicates that the requirers data are available.
class HaproxyRouteTcpDataRemovedEvent
HaproxyRouteDataRemovedEvent custom event.
Description
This event indicates that one of the endpoints was removed.
class HaproxyRouteTcpProviderEvents
List of events that the TLS Certificates requirer charm can leverage.
Attributes
class HaproxyRouteTcpProvider
Haproxy-route interface provider implementation.
Attributes
Methods
HaproxyRouteTcpProvider. __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 HaproxyRouteTcpInvalidRelationDataError when requirer data validation fails. If this is set to True the provider charm needs to also catch and handle the thrown exception.
HaproxyRouteTcpProvider. relations( self )
Description
The list of Relation instances associated with this endpoint. None
HaproxyRouteTcpProvider. 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.
HaproxyRouteTcpProvider. 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 HaproxyRouteTcpEnpointsReadyEvent
Description
HaproxyRouteTcpEnpointsReadyEvent custom event. None
class HaproxyRouteTcpEndpointsRemovedEvent
Description
HaproxyRouteTcpEndpointsRemovedEvent custom event. None
class HaproxyRouteTcpRequirerEvents
List of events that the TLS Certificates requirer charm can leverage.
Attributes
class HaproxyRouteTcpRequirer
haproxy-route interface requirer implementation.
Attributes
Methods
HaproxyRouteTcpRequirer. __init__( self , charm: CharmBase , relation_name: str )
Initialize the HaproxyRouteRequirer.
Arguments
The charm that is instantiating the library.
The name of the relation to bind to.
The provider port.
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.
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.
Health check type, Can be “generic”, “mysql”, “postgres”, “redis” or “smtp”.
Only used in generic health checks, specify a string to send in the health check request.
Only used in generic health checks, specify the expected response from a health check request.
Only used if type is postgres or mysql, specify the user name to enable HAproxy to send a Client Authentication packet.
Algorithm to use for load balancing.
Whether to use consistent hashing.
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.
Whether to redispatch failed requests to another server.
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.
List of source IP addresses to block.
Whether to enforce TLS for all traffic coming to the backend.
Whether to enable tls termination on the dedicated frontend.
IP address of the unit (if not provided, will use binding address).
HaproxyRouteTcpRequirer. provide_haproxy_route_tcp_requirements( self )
Update haproxy-route requirements data in the relation.
Arguments
The provider port.
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.
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.
Health check type, Can be “generic”, “mysql”, “postgres”, “redis” or “smtp”.
Only used in generic health checks, specify a string to send in the health check request.
Only used in generic health checks, specify the expected response from a health check request.
Only used if type is postgres or mysql, specify the user name to enable HAproxy to send a Client Authentication packet.
Algorithm to use for load balancing.
Whether to use consistent hashing.
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.
Whether to redispatch failed requests to another server.
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.
List of source IP addresses to block.
Whether to enforce TLS for all traffic coming to the backend.
Whether to enable tls termination on the dedicated frontend.
IP address of the unit (if not provided, will use binding address).
HaproxyRouteTcpRequirer. update_relation_data( self )
Description
Update both application and unit data in the relation. None
HaproxyRouteTcpRequirer. 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.
HaproxyRouteTcpRequirer. configure_port( self , port: int )
Set the provider port.
Arguments
The provider port to set
Returns
The HaproxyRouteTcpRequirer class
HaproxyRouteTcpRequirer. configure_backend_port( self , backend_port: int )
Set the backend port.
Arguments
The backend port to set
Returns
The HaproxyRouteTcpRequirer class
HaproxyRouteTcpRequirer. configure_hosts( self , hosts )
Set backend hosts.
Arguments
The hosts list to set
Returns
The HaproxyRouteTcpRequirer class
HaproxyRouteTcpRequirer. configure_sni( self , sni: str )
Set the SNI.
Arguments
The SNI to set
Returns
The HaproxyRouteTcpRequirer class
HaproxyRouteTcpRequirer. configure_health_check( self , interval: int , rise: int , fall: int , check_type: TCPHealthCheckType , send , expect , db_user )
Configure server health check.
Description
Args: interval: Number of seconds between consecutive health check attempts. rise: Number of consecutive successful health checks required for up. fall: Number of consecutive failed health checks required for DOWN. check_type: Health check type, Can be "generic", "mysql", "postgres", "redis" or "smtp". send: Only used in generic health checks, specify a string to send in the health check request. expect: Only used in generic health checks, specify the expected response from a health check request. db_user: Only used if type is postgres or mysql, specify the user name to enable HAproxy to send a Client Authentication packet.
Returns: Self: The HaproxyRouteTcpRequirer class
HaproxyRouteTcpRequirer. configure_rate_limit( self , connections_per_minute: int , policy: TCPRateLimitPolicy )
Configure rate limit.
Arguments
The number of connections per minute allowed
The rate limit policy to apply
Returns
The HaproxyRouteTcpRequirer class
HaproxyRouteTcpRequirer. configure_bandwidth_limit( self , upload_bytes_per_second , download_bytes_per_second )
Configure bandwidth limit.
Arguments
Upload bandwidth limit in bytes per second
Download bandwidth limit in bytes per second
Returns
The HaproxyRouteTcpRequirer class
HaproxyRouteTcpRequirer. configure_retry( self , retry_count: int , retry_redispatch: bool )
Configure retry.
Arguments
The number of retries to attempt
Whether to enable retry redispatch
Returns
The HaproxyRouteTcpRequirer class
HaproxyRouteTcpRequirer. configure_timeout( self , server_timeout_in_seconds , connect_timeout_in_seconds , queue_timeout_in_seconds )
Configure timeout.
Arguments
Server timeout.
Connect timeout.
Queue timeout
Returns
The HaproxyRouteTcpRequirer class
HaproxyRouteTcpRequirer. configure_server_max_connections( self , max_connections: int )
Set the server max connections.
Arguments
The number of max connections to set
Returns
The HaproxyRouteTcpRequirer class
HaproxyRouteTcpRequirer. disable_tls_termination( self )
Disable TLS termination.
Returns
The HaproxyRouteTcpRequirer class
HaproxyRouteTcpRequirer. allow_http( self )
Do not enforce TLS.
Returns
The HaproxyRouteTcpRequirer class
HaproxyRouteTcpRequirer. configure_deny_list( self , ip_deny_list )
Configure IP deny list.
Arguments
List of IP addresses to deny
Returns
The HaproxyRouteTcpRequirer class