Advanced features

Integrate with Git

On this page

Availability:

  • Available in HAProxy Enterprise
  • Not available in HAProxy ALOHA (doesn’t have git binary)

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 (for example, GitHub, GitLab, or 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:

    nix
    cd /etc/hapee-<VERSION>
    git init
    git remote add origin https://github.com/username/repo.git
    git checkout -b main
    nix
    cd /etc/hapee-<VERSION>
    git init
    git remote add origin https://github.com/username/repo.git
    git checkout -b main

  4. Set your username and email for commits.

    nix
    sudo git config --global user.name "Your Name"
    sudo git config --global user.email "name@example.com"
    nix
    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.

    nix
    sudo git add .
    sudo git commit -m "Initial commit"
    sudo git push origin main
    nix
    sudo git add .
    sudo git commit -m "Initial commit"
    sudo git push origin main

  6. Add the file /etc/hapee-<VERSION>/git.settings with the following contents:

    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/hapee-<VERSION>/",
      "config_file": "hapee-lb.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/hapee-<VERSION>/",
      "config_file": "hapee-lb.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. Add Git settings to your Data Plane API configuration file. Edit /etc/hapee-<VERSION>/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/hapee-<VERSION>/git.settings
    dataplaneapi.yml
    yaml
    dataplaneapi:
      host: 0.0.0.0
      port: 5555
      git_mode: true
      git_settings_file: /etc/hapee-<VERSION>/git.settings

  8. Restart the Data Plane API.

    nix
    sudo systemctl restart hapee-extras-dataplaneapi
    nix
    sudo systemctl restart hapee-extras-dataplaneapi

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

    nix
    curl -X POST \
      -u admin:adminpwd \
      -H 'Content-Type: application/json' \
      -d '{ "action":"pull"}' \
      '127.0.0.1:5555/v2/services/git/actions'
    nix
    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:

nix
CFGVER=$(curl -s -u admin:adminpwd 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'
nix
CFGVER=$(curl -s -u admin:adminpwd 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'

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

nix
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'
nix
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:

nix
curl -X POST \
  -u admin:adminpwd \
  -H 'Content-Type: application/json' \
  -d '{ "action":"push" }' \
  '127.0.0.1:5555/v2/services/git/actions'
nix
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:

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

Note that the version parameter in DELETE, POST, and PUT requests must match the load balancer’s current configuration version. This is because the Data Plane API uses optimistic concurrency control, or optimistic locking, to manage its transactions. This ensures that if multiple entities modify a resource that the changes are applied correctly. The APIv3 examples in this section make a GET request to /v3/services/haproxy/configuration/version immediately before making a call to update a resource to retrieve the version and populate the CFGVER environment variable for the URL version parameter as is shown in the following command:

nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)
nix
CFGVER=$(curl -s -u admin:adminpwd http://localhost:5555/v3/services/haproxy/configuration/version)

You will then use the value of the environment variable to populate the version parameter in the endpoint URL as is shown in the example below:

nix
CFGVER=$(curl -s -u admin:adminpwd 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'
nix
CFGVER=$(curl -s -u admin:adminpwd 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'

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

Previous page Consul service discovery Next page API specifications
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences