Advanced features

Integrate with Git

Enterprise

This feature requires the Enterprise version of the HAProxy Data Plane API.

The Data Plane API integrates with Git, enabling you to sync load balancer configuration changes to a remote Git repository. The API serves as a Git client, providing commands to commit changes and push and pull from a remote repository.

Configure Git integration Jump to heading

  1. Create a new empty Git repository on your version control server (i.e. GitHub, GitLab, Jenkins).

  2. Create an access token so that the Data Plane API can access your remote Git repository.

  3. Configure the load balancer configuration directory as a Git clone:

    bash
    cd /etc/haproxy
    git init
    git remote add origin https://github.com/username/repo.git
    git checkout -b main
    bash
    cd /etc/haproxy
    git init
    git remote add origin https://github.com/username/repo.git
    git checkout -b main
    bash
    cd /etc/hapee-<VERSION>
    git init
    git remote add origin https://github.com/username/repo.git
    git checkout -b main
    bash
    cd /etc/hapee-<VERSION>
    git init
    git remote add origin https://github.com/username/repo.git
    git checkout -b main
    bash
    cd /etc/haproxy
    git init
    git remote add origin https://github.com/username/repo.git
    git checkout -b main
    bash
    cd /etc/haproxy
    git init
    git remote add origin https://github.com/username/repo.git
    git checkout -b main
  4. Set your username and email for commits.

    bash
    sudo git config --global user.name "Your Name"
    sudo git config --global user.email "name@example.com"
    bash
    sudo git config --global user.name "Your Name"
    sudo git config --global user.email "name@example.com"
  5. Commit and push the local configuration files to the remote repository.

    bash
    sudo git add .
    sudo git commit -m "Initial commit"
    sudo git push origin main
    bash
    sudo git add .
    sudo git commit -m "Initial commit"
    sudo git push origin main
  6. Add the file /etc/haproxy/git.settings:

    git.settings
    json
    {
    "url": "https://github.com/username/repo.git",
    "auth_method": "access_token",
    "auth_access_token": "C4Axa1kCcxPv-fzrhsde",
    "storage_type": "dir",
    "storage_dir": "/etc/haproxy/",
    "config_file": "haproxy.cfg"
    }
    git.settings
    json
    {
    "url": "https://github.com/username/repo.git",
    "auth_method": "access_token",
    "auth_access_token": "C4Axa1kCcxPv-fzrhsde",
    "storage_type": "dir",
    "storage_dir": "/etc/haproxy/",
    "config_file": "haproxy.cfg"
    }

    In this example:

    • url is the URL of your git repository
    • auth_access_token is your repository’s access token
    • storage_dir is the path to your load balancer configuration directory
    • config_file is the name of your configuration file
  7. Edit your Data Plane API configuration file (for example, /etc/haproxy/dataplaneapi.yml).

    Add the git_mode and git_settings_file fields to the dataplaneapi block:

    dataplaneapi.yml
    yaml
    dataplaneapi:
    host: 0.0.0.0
    port: 5555
    git_mode: true
    git_settings_file: /etc/haproxy/git.settings
    dataplaneapi.yml
    yaml
    dataplaneapi:
    host: 0.0.0.0
    port: 5555
    git_mode: true
    git_settings_file: /etc/haproxy/git.settings
  8. Restart the Data Plane API. If using the program section in your HAProxy configuration file, you can do this by restarting the HAProxy service:

    bash
    sudo systemctl restart haproxy
    bash
    sudo systemctl restart haproxy

    Otherwise, restart the Data Plane API service.

  9. Use the pull action on the /services/git/actions API endpoint to sync remote changes to the local repository.

    bash
    curl -X POST \
    -u admin:adminpwd \
    -H 'Content-Type: application/json' \
    -d '{ "action":"pull"}' \
    '127.0.0.1:5555/v2/services/git/actions'
    bash
    curl -X POST \
    -u admin:adminpwd \
    -H 'Content-Type: application/json' \
    -d '{ "action":"pull"}' \
    '127.0.0.1:5555/v2/services/git/actions'

Sync changes with the remote repository Jump to heading

Once the HAProxy configuration directory has been initialized as a local git clone, you can sync any changes by calling the commit and push actions.

For example, after adding a new server to an existing backend named webservers:

bash
CFGVER=$(curl -s -u admin:adminpass http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X POST \
-u admin:adminpwd \
-H "Content-Type: application/json" \
-d '{"name":"anotherserver", "address":"127.0.0.1", "port":8080, "check":"enabled"}' \
'127.0.0.1:5555/v2/services/haproxy/configuration/servers?backend=webservers&version=$CFGVER'
bash
CFGVER=$(curl -s -u admin:adminpass http://localhost:5555/v2/services/haproxy/configuration/version)
curl -X POST \
-u admin:adminpwd \
-H "Content-Type: application/json" \
-d '{"name":"anotherserver", "address":"127.0.0.1", "port":8080, "check":"enabled"}' \
'127.0.0.1:5555/v2/services/haproxy/configuration/servers?backend=webservers&version=$CFGVER'

Note

The version parameter in DELETE, POST, and PUT requests must match the system’s current version. The examples in this section use a GET request to /v2/services/haproxy/configuration/version to retrieve the version and populate the CFGVER environment variable for the URL version parameter.

Commit the change by calling the commit action on the /services/git/actions API endpoint:

bash
curl -X POST \
-u admin:adminpwd \
-H 'Content-Type: application/json' \
-d '{ "action":"commit", "commit_message":"add new web server" }' \
'127.0.0.1:5555/v2/services/git/actions'
bash
curl -X POST \
-u admin:adminpwd \
-H 'Content-Type: application/json' \
-d '{ "action":"commit", "commit_message":"add new web server" }' \
'127.0.0.1:5555/v2/services/git/actions'

Then push the change to the remote repository by calling the push action:

bash
curl -X POST \
-u admin:adminpwd \
-H 'Content-Type: application/json' \
-d '{ "action":"push" }' \
'127.0.0.1:5555/v2/services/git/actions'
bash
curl -X POST \
-u admin:adminpwd \
-H 'Content-Type: application/json' \
-d '{ "action":"push" }' \
'127.0.0.1:5555/v2/services/git/actions'

You can also pull the latest changes from the remote repository by calling the pull action:

bash
curl -X POST \
-u admin:adminpwd \
-H 'Content-Type: application/json' \
-d '{ "action":"pull" }' \
'127.0.0.1:5555/v2/services/git/actions'
bash
curl -X POST \
-u admin:adminpwd \
-H 'Content-Type: application/json' \
-d '{ "action":"pull" }' \
'127.0.0.1:5555/v2/services/git/actions'

If this page was useful, please, Leave the feedback.