Installation

Install the HAProxy Data Plane API on HAProxy

Version 3.0 contains breaking changes

If you’re installing HAProxy Data Plane API 3.x, know that it changes several conventions that were present in version 2.x, and that upgrading to 3.x will require you to call the API endpoints differently. See the release notes for more details.

This section describes how to install the HAProxy Data Plane API alongside HAProxy.

Run the API using systemd Jump to heading

Running the API as a systemd service enables you to issue CLI commands to a running haproxy process.

  1. Download the latest 3.0.x package from the HAProxy Data Plane API GitHub repository. For Debian/Ubuntu, packages have the suffix .deb. For RHEL, packages have the suffix .rpm.

  2. Install the package:

    nix
    sudo dpkg -i --force-depends dataplaneapi_3.0.3_linux_amd64.deb
    nix
    sudo dpkg -i --force-depends dataplaneapi_3.0.3_linux_amd64.deb
    nix
    sudo rpm -Uvh --nodeps dataplaneapi_3.0.3_linux_amd64.rpm
    nix
    sudo rpm -Uvh --nodeps dataplaneapi_3.0.3_linux_amd64.rpm
  3. Ensure that your HAProxy configuration has a stats socket line in the global section.

    This enables the Runtime API, which the Data Plane API uses to make some changes without requiring a reload.

    haproxy.cfg
    haproxy
    global
    stats socket /var/run/haproxy.sock mode 660 level admin
    haproxy.cfg
    haproxy
    global
    stats socket /var/run/haproxy.sock mode 660 level admin
  4. Add a userlist section to the HAProxy configuration. This sets the authentication username to admin and password to adminpwd:

    haproxy.cfg
    haproxy
    userlist dataplaneapi
    user admin insecure-password adminpwd
    haproxy.cfg
    haproxy
    userlist dataplaneapi
    user admin insecure-password adminpwd
  5. Start the Data Plane API:

    nix
    sudo systemctl start dataplaneapi
    nix
    sudo systemctl start dataplaneapi
  6. Verify that the API is running properly by calling the info function:

    nix
    curl -X GET --user admin:adminpwd http://localhost:5555/v3/info
    nix
    curl -X GET --user admin:adminpwd http://localhost:5555/v3/info
    output
    json
    {"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}
    output
    json
    {"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}

Run the API in Docker Jump to heading

Available since

  • HAProxy 2.0

The HAProxy Docker images come with the Data Plane API preinstalled.

  1. Create a folder on your workstation named haproxy. Here, you will keep your configuration files.

  2. To get a sample Data Plane API configuration file:

    • Download the latest 3.0.x archive from the HAProxy Data Plane API GitHub repository.

      nix
      wget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.3/dataplaneapi_3.0.3_linux_x86_64.tar.gz
      nix
      wget https://github.com/haproxytech/dataplaneapi/releases/download/v3.0.3/dataplaneapi_3.0.3_linux_x86_64.tar.gz
    • Extract the archive to get the sample configuration file dataplaneapi.yml.dist.

      nix
      tar -zxvf dataplaneapi_3.0.3_linux_x86_64.tar.gz
      nix
      tar -zxvf dataplaneapi_3.0.3_linux_x86_64.tar.gz
    • Rename the file dataplaneapi.yml.dist to dataplaneapi.yml and move it into your haproxy folder.

    • Change the file paths to the HAProxy program and configuration file:

      dataplaneapi.yml
      yaml
      haproxy:
      config_file: /usr/local/etc/haproxy/haproxy.cfg
      haproxy_bin: /usr/local/sbin/haproxy
      dataplaneapi.yml
      yaml
      haproxy:
      config_file: /usr/local/etc/haproxy/haproxy.cfg
      haproxy_bin: /usr/local/sbin/haproxy
    • To send API logs to standard out, change the log_to line to stdout:

      dataplaneapi.yml
      yaml
      log_targets:
      - log_to: stdout
      dataplaneapi.yml
      yaml
      log_targets:
      - log_to: stdout
  3. Create an HAProxy configuration file that has:

    • a global section. The stats socket line enables the Runtime API, which the Data Plane API uses to make some changes without requiring a reload.
    • a userlist section that sets the API authentication username and password. In the example below, we set the username to admin and password to adminpwd.
    haproxy.cfg
    haproxy
    global
    stats socket /var/run/haproxy.sock mode 660 level admin
    userlist dataplaneapi
    user admin insecure-password adminpwd
    haproxy.cfg
    haproxy
    global
    stats socket /var/run/haproxy.sock mode 660 level admin
    userlist dataplaneapi
    user admin insecure-password adminpwd
  4. Change directory into the haproxy folder. Then run the Docker container, passing the -v flag to map your local haproxy folder to /usr/local/etc/haproxy inside the container:

    nix
    docker run -d --name my-running-haproxy -p 5555:5555/tcp -v ${PWD}:/usr/local/etc/haproxy:rw haproxytech/haproxy-ubuntu
    nix
    docker run -d --name my-running-haproxy -p 5555:5555/tcp -v ${PWD}:/usr/local/etc/haproxy:rw haproxytech/haproxy-ubuntu
  5. Verify that the API is running properly by calling the info function:

    nix
    curl -X GET --user admin:adminpwd http://localhost:5555/v3/info
    nix
    curl -X GET --user admin:adminpwd http://localhost:5555/v3/info
    output
    json
    {"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}
    output
    json
    {"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}

Troubleshooting Jump to heading

  • You get the error The configuration file is not declared in the HAPROXY_CFGFILES environment variable, cannot start.

    The value of config_file in your Data Plane API configuration must match the configuration file that HAProxy actually loaded. Try checking the value of the HAPROXY_CFGFILES environment variable by including it in your logs. Set your config_file field to match. For example, /usr/local/etc/haproxy/haproxy.cfg.

  • You get a permission denied error.

    If you get an error like this:

    json
    {"code":500,"message":"dial unix /var/run/haproxy.sock: connect: permission denied"}
    json
    {"code":500,"message":"dial unix /var/run/haproxy.sock: connect: permission denied"}

    This means that the user who runs the API does not have access to the HAProxy socket. Check that you added them to the HAProxy group and log out and back in again.

  • You receive 400 Bad Request.

    If you receive an error such as 400 Bad Request or Client sent an HTTP request to an HTTPS server, HTTPS may be enabled. Try the curl command again with the -k option and specify https:// in your URL:

    nix
    curl -k -X GET --user admin:adminpwd https://localhost:5555/v3/info
    nix
    curl -k -X GET --user admin:adminpwd https://localhost:5555/v3/info

Enable HTTPS Jump to heading

To enable HTTPS for Data Plane API with HAProxy, you must add a tls section to your Data Plane API configuration file and set the scheme to https:

  1. Add the following to your Data Plane API configuration file:

    dataplaneapi.hcl
    hcl
    dataplaneapi {
    host = "0.0.0.0"
    port = 5555
    scheme = ["https"]
    ...
    tls {
    tls_port = 6443
    tls_certificate: "/etc/haproxy/ssl/certs/server-cert.pem"
    tls_key: "/etc/haproxy/ssl/certs/server-key.pem"
    }
    ...
    }
    dataplaneapi.hcl
    hcl
    dataplaneapi {
    host = "0.0.0.0"
    port = 5555
    scheme = ["https"]
    ...
    tls {
    tls_port = 6443
    tls_certificate: "/etc/haproxy/ssl/certs/server-cert.pem"
    tls_key: "/etc/haproxy/ssl/certs/server-key.pem"
    }
    ...
    }
    dataplaneapi.yml
    yaml
    dataplaneapi:
    host: 0.0.0.0
    port: 5555
    scheme:
    - https
    ...
    tls:
    tls_port: 6443
    tls_certificate: /etc/haproxy/ssl/certs/server-cert.pem
    tls_key: /etc/haproxy/ssl/certs/server-key.pem
    ...
    dataplaneapi.yml
    yaml
    dataplaneapi:
    host: 0.0.0.0
    port: 5555
    scheme:
    - https
    ...
    tls:
    tls_port: 6443
    tls_certificate: /etc/haproxy/ssl/certs/server-cert.pem
    tls_key: /etc/haproxy/ssl/certs/server-key.pem
    ...

    Set the following:

    • The scheme to https. Note that you can also have an entry for http, but you must specify different ports for port and tls_port to enable both HTTP and HTTPS.
    • The port for TLS connections as tls_port. This must be a different port than you specify for port if you intend to have both HTTP and HTTPS connections active.
    • The path to the certificate file to use with TLS connections as tls_certificate.
    • The path to the private key to use with TLS connections as tls_key.
  2. Restart Data Plane API:

    nix
    sudo systemctl restart dataplaneapi
    nix
    sudo systemctl restart dataplaneapi

You can test the HTTPS connection to the Data Plane API using curl, providing your username and password that you defined in the userlist during installation. The following example is for Data Plane API 3.0 (v3):

nix
curl -k --user <username>:<password> -X GET https://localhost:6443/v3/info
nix
curl -k --user <username>:<password> -X GET https://localhost:6443/v3/info
output
json
{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}
output
json
{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}

You can optionally set the following properties in the tls section:

Option Description
tls_host The IP to listen on for HTTPS. If you don’t specify a value, it’s the same as host.
tls_listen_limit Limits the number of outstanding requests.
tls_keep_alive Sets the TCP keep-alive timeouts on accepted connections.
tls_read_timeout Maximum duration before timing out read operation of the request.
tls_write_timeout Maximum duration before timing out write operation of the response.
tls_ca The certificate authority file to be used when you enable mTLS authentication. When you provide this option, basic authentication with the Data Plane API is disabled. You will need to authenticate using a client certificate and key.

Enable mTLS Jump to heading

If you need to perform client certificate authentication, also known as mTLS, for connections to the Data Plane API, you can set an additional parameter in the configuration tls_ca which sets the certificate authority with which to authenticate client certificates. To enable this behavior:

  1. Add this line to your Data Plane API configuration which specifies the path to your CA file:

    dataplaneapi.hcl
    hcl
    dataplaneapi {
    host = "0.0.0.0"
    port = 5555
    scheme = ["https"]
    ...
    tls {
    tls_port = 6443
    tls_certificate: "/etc/haproxy/ssl/certs/server-cert.pem"
    tls_key: "/etc/haproxy/ssl/certs/server-key.pem"
    tls_ca: "/etc/haproxy/ssl/certs/ca-cert.pem"
    }
    ...
    }
    dataplaneapi.hcl
    hcl
    dataplaneapi {
    host = "0.0.0.0"
    port = 5555
    scheme = ["https"]
    ...
    tls {
    tls_port = 6443
    tls_certificate: "/etc/haproxy/ssl/certs/server-cert.pem"
    tls_key: "/etc/haproxy/ssl/certs/server-key.pem"
    tls_ca: "/etc/haproxy/ssl/certs/ca-cert.pem"
    }
    ...
    }
    dataplaneapi.yml
    yaml
    dataplaneapi:
    host: 0.0.0.0
    port: 5555
    scheme:
    - https
    ...
    tls:
    tls_port: 6443
    tls_certificate: /etc/haproxy/ssl/certs/server-cert.pem
    tls_key: /etc/haproxy/ssl/certs/server-key.pem
    tls_ca: /etc/haproxy/ssl/certs/ca-cert.pem
    ...
    dataplaneapi.yml
    yaml
    dataplaneapi:
    host: 0.0.0.0
    port: 5555
    scheme:
    - https
    ...
    tls:
    tls_port: 6443
    tls_certificate: /etc/haproxy/ssl/certs/server-cert.pem
    tls_key: /etc/haproxy/ssl/certs/server-key.pem
    tls_ca: /etc/haproxy/ssl/certs/ca-cert.pem
    ...
  2. Restart Data Plane API:

    nix
    sudo systemctl restart dataplaneapi
    nix
    sudo systemctl restart dataplaneapi

Note that enabling mTLS in this way means that instead of authenticating with the Data Plane API using a username and password, you will use a client certificate and key.

You can test the HTTPS connection to the Data Plane API using curl, providing your client certificate and key. The following example is for Data Plane API 3.0 (v3):

nix
curl -k --cert client-cert.pem --key client-key.pem -X GET https://localhost:6443/v3/info
nix
curl -k --cert client-cert.pem --key client-key.pem -X GET https://localhost:6443/v3/info
output
json
{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}
output
json
{"api":{"build_date":"2024-08-23T15:38:09.000Z","version":"v3.0.3 1491b08a"},"system":{}}

Do you have any suggestions on how we can improve the content of this page?