haproxy

HAProxy

Channel Revision Published Runs on
latest/stable 84 25 Jul 2024
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04 Ubuntu 14.04
latest/stable 82 24 Jul 2024
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04 Ubuntu 14.04
latest/stable 66 08 Nov 2021
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04 Ubuntu 14.04
latest/candidate 131 13 Feb 2025
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04 Ubuntu 14.04
latest/candidate 82 24 Jul 2024
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04 Ubuntu 14.04
latest/candidate 64 14 Oct 2021
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04 Ubuntu 14.04
latest/beta 84 25 Jul 2024
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
latest/beta 82 24 Jul 2024
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04
latest/edge 131 12 Feb 2025
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04 Ubuntu 14.04
latest/edge 82 24 Jul 2024
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04 Ubuntu 14.04
latest/edge 80 24 Jul 2024
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04 Ubuntu 14.04
latest/edge 37 11 Nov 2020
Ubuntu 24.04 Ubuntu 22.04 Ubuntu 20.04 Ubuntu 18.04 Ubuntu 16.04 Ubuntu 14.04
2.8/edge 141 18 Mar 2025
Ubuntu 24.04
juju deploy haproxy
Show information

Learn to deploy on juju >

Platform:

Ubuntu
24.04 22.04 20.04 18.04 16.04 14.04

charms.haproxy.v0.haproxy_route

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.v0.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.v0.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,
        host=<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>,
        client_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(host=, 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.v0.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

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

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.
paths
List of URL paths to use for HTTP health checks.

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

connections_per_minute
Number of connections allowed per minute for a client.
policy
Action to take when the rate limit is exceeded.

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

algorithm
Algorithm to use for load balancing.
cookie
Cookie name to use when algorithm is set to cookie.

class BandwidthLimit

Configuration model for bandwidth rate limiting.

Attributes

upload
Limit upload speed (bytes per second).
download
Limit download speed (bytes per second).

class Retry

Configuration model for retry.

Attributes

count
How many times should a request retry.
interval
Interval (in seconds) between retries.
redispatch
Whether to redispatch failed requests to another server.

class TimeoutConfiguration

Configuration model for timeout.

Attributes

server
Timeout for requests from haproxy to backend servers.
client
Timeout for client requests to haproxy.
queue
Timeout for requests waiting in the queue after server-maxconn is reached.

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

method
Which rewrite method to apply.One of set-path, set-query, set-header.
expression
Regular expression to use with the rewrite method.
header
The name of the header to rewrited.

class RequirerApplicationData

Configuration model for HAProxy route requirer application data.

Attributes

service
Name of the service requesting HAProxy routing.
ports
List of port numbers on which the service is listening.
paths
List of URL paths to route to this service. Defaults to an empty list.
subdomains
List of subdomains to route to this service. Defaults to an empty list.
rewrites
List of RewriteConfiguration objects defining path, query, or header rewrite rules.
check
ServerHealthCheck configuration for monitoring backend health.
load_balancing
Configuration for the load balancing strategy.
rate_limit
Optional configuration for limiting connection rates.
bandwidth_limit
Optional configuration for limiting upload and download bandwidth.
retry
Optional configuration for request retry behavior.
deny_paths
List of URL paths that should not be routed to the backend.
timeout
Configuration for server, client, and queue timeouts.
server_maxconn
Optional maximum number of connections per server.

class HaproxyRouteProviderAppData

haproxy-route provider databag schema.

Attributes

endpoints
The list of proxied endpoints that maps to the backend.

class RequirerUnitData

haproxy-route requirer unit data.

Attributes

host
hostname or IP address of the unit.

class HaproxyRouteRequirerData

haproxy-route requirer data.

Attributes

application_data
Application data.
units_data
Units data

class HaproxyRouteRequirersData

haproxy-route requirers data.

Attributes

requirers_data
List of requirer data.

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

data_available
This event indicates that the haproxy-route endpoints are available.
data_removed
This event indicates that one of the endpoints was removed.

class HaproxyRouteProvider

Haproxy-route interface provider implementation.

Attributes

on
Custom events of the provider.
relations
Related appliations.

Methods

HaproxyRouteProvider. __init__( self , charm: CharmBase , relation_name: str , raise_on_validation_error: bool )

Initialize the HaproxyRouteProvider.

Arguments

charm

The charm that is instantiating the library.

relation_name

The name of the relation.

raise_on_validation_error

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

relations

A list of Relation instances to fetch data from.

Returns

HaproxyRouteRequirersData

Validated data from all haproxy-route requirers.

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

ready
when the provider proxied endpoints are ready.
removed
when the provider

class HaproxyRouteRequirer

haproxy-route interface requirer implementation.

Attributes

on
Custom events of the requirer.

Methods

HaproxyRouteRequirer. __init__( self , charm: CharmBase , relation_name: str , service , ports , paths , subdomains , check_interval , check_rise , check_fall , check_paths , 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 , client_timeout: int , queue_timeout: int , server_maxconn , host )

Initialize the HaproxyRouteRequirer.

Arguments

charm

The charm that is instantiating the library.

relation_name

The name of the relation to bind to.

service

The name of the service to route traffic to.

ports

List of ports the service is listening on.

paths

List of URL paths to route to this service.

subdomains

List of subdomains to route to this service.

check_interval

Interval between health checks in seconds.

check_rise

Number of successful health checks before server is considered up.

check_fall

Number of failed health checks before server is considered down.

check_paths

List of paths to use for health checks.

path_rewrite_expressions

List of regex expressions for path rewrites.

query_rewrite_expressions

List of regex expressions for query rewrites.

header_rewrite_expressions

List of tuples containing header name and rewrite expression.

load_balancing_algorithm

Algorithm to use for load balancing.

load_balancing_cookie

Cookie name to use when algorithm is set to cookie.

rate_limit_connections_per_minute

Maximum connections allowed per minute.

rate_limit_policy

Policy to apply when rate limit is reached.

upload_limit

Maximum upload bandwidth in bytes per second.

download_limit

Maximum download bandwidth in bytes per second.

retry_count

Number of times to retry failed requests.

retry_interval

Interval between retries in seconds.

retry_redispatch

Whether to redispatch failed requests to another server.

deny_paths

List of paths that should not be routed to the backend.

server_timeout

Timeout for requests from haproxy to backend servers in seconds.

client_timeout

Timeout for client requests to haproxy in seconds.

queue_timeout

Timeout for requests waiting in queue in seconds.

server_maxconn

Maximum connections per server.

host

Hostname or IP address of the unit (if not provided, will use binding address).

HaproxyRouteRequirer. provide_haproxy_route_requirements( self , service: str , ports , paths , subdomains , check_interval , check_rise , check_fall , check_paths , 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 , client_timeout: int , queue_timeout: int , server_maxconn )

Update haproxy-route requirements data in the relation.

Arguments

service

The name of the service to route traffic to.

ports

List of ports the service is listening on.

paths

List of URL paths to route to this service.

subdomains

List of subdomains to route to this service.

check_interval

Interval between health checks in seconds.

check_rise

Number of successful health checks before server is considered up.

check_fall

Number of failed health checks before server is considered down.

check_paths

List of paths to use for health checks.

path_rewrite_expressions

List of regex expressions for path rewrites.

query_rewrite_expressions

List of regex expressions for query rewrites.

header_rewrite_expressions

List of tuples containing header name and rewrite expression.

load_balancing_algorithm

Algorithm to use for load balancing.

load_balancing_cookie

Cookie name to use when algorithm is set to cookie.

rate_limit_connections_per_minute

Maximum connections allowed per minute.

rate_limit_policy

Policy to apply when rate limit is reached.

upload_limit

Maximum upload bandwidth in bytes per second.

download_limit

Maximum download bandwidth in bytes per second.

retry_count

Number of times to retry failed requests.

retry_interval

Interval between retries in seconds.

retry_redispatch

Whether to redispatch failed requests to another server.

deny_paths

List of paths that should not be routed to the backend.

server_timeout

Timeout for requests from haproxy to backend servers in seconds.

client_timeout

Timeout for client requests to haproxy in seconds.

queue_timeout

Timeout for requests waiting in queue in seconds.

server_maxconn

Maximum connections per server.

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.