hpxd

hpxd is a daemon that runs on a node and manages the state of HAProxy. It listens for changes from a specified Git repository and updates the HAProxy configuration accordingly.

---

---

Features

• Dynamic Configuration Updates: Polls a Git repository for changes in HAProxy configuration and applies them dynamically.
• Prometheus Metrics: Provides metrics on Git pull successes/failures, HAProxy reloads, and configuration validation.
• Cross-Platform: Builds available for Linux (amd64 and arm64).

Installation

From Binary

You can download the latest release from here.

If you prefer to install using a script:

curl -sfL https://raw.githubusercontent.com/zcubbs/hpxd/main/scripts/install.sh | sudo bash -s -- \
    --repo-url https://github.com/yourusername/haproxy-configs.git \
    --branch main \
    --path /path/to/file/in/repo/haproxy.cfg \
    --haproxy-config-path /path/to/haproxy.cfg

From Source

go get github.com/zcubbs/hpxd
cd $GOPATH/src/github.com/zcubbs/hpxd
go install ./...

Usage

You'll need a configuration file (by default, the tool looks for ./configs/hpxd.yaml).

repoURL: https://github.com/yourusername/haproxy-configs.git
branch: main
haproxyConfigPath: /path/to/haproxy.cfg
pollingInterval: 5s
enablePrometheus: true
prometheusPort: 9100

Then, run the tool:

hpxd -c /path/to/config.yaml

Handling of Repository Credentials

If you're using a private Git repository, hpxd requires credentials for access. These credentials should be provided through environment variables to maintain security.

Setup for Private Repositories:

1. Username: Set the HPXD_GIT_USERNAME environment variable to your Git username.

2. Password/Token: Set the HPXD_GIT_PASSWORD environment variable to your Git password or, preferably, a personal access token if you're using platforms like GitHub, GitLab, etc.

export HPXD_GIT_USERNAME=your_git_username
export HPXD_GIT_PASSWORD=your_git_password_or_token

Monitoring Metrics

Monitoring is available for the application, and the following metrics are tracked:

• hpxd_git_pulls_total:

  • Description: Total number of times the config is pulled from Git.
  • Labels: status (values: success or failure).

• hpxd_haproxy_reloads_total:

  • Description: Total number of times HAProxy is reloaded.

• hpxd_invalid_configs_total:

  • Description: Total number of times an invalid config is detected.

• application_info:

  • Description: Provides application details such as version, commit, and build date.
  • Labels: version, commit, buildDate.

These metrics can be accessed via Prometheus and visualized using Grafana.

Development

Prerequisites

• Docker (https://rancherdesktop.io/)
• Task (https://taskfile.dev/#/installation)

Setup Development Environment

1. Build the development Docker image:

task build-docker-dev

2. Run the development Docker container:

task run-docker-dev

3. Build and test your Go project:

task build
task test

4. Install/Uninstall:

task install
task uninstall

Contributing

Contributions are welcome! Please read the contribution guidelines before submitting a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support and Feedback

If you need support or have any feedback, please open an issue here