This gem provides a simple interface for the Community Edition of the HAProxy Data Plane API.

Currently, it only supports a handful of requests that we needed. More may be added in the future.

We encourage you to make Pull Requests with more API endpoints.

HAProxy is a load balancer. The Data Plane API can be used to manage your HAProxy config, backends and servers.

Install the gem and add to the application's Gemfile by executing:

$ bundle add data_plane_api

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install data_plane_api

The main namespace/module of this gem is DataPlaneApi.

We used this documentation as the reference for implementing this gem.

Each section of the HAProxy Data Plane API should have its own module under DataPlaneApi. Each endpoint is represented as a singleton method of this module.

eg. DataPlaneApi::Server.get_runtime_settings.

In order to make requests, you need to configure the API URL, user and password.

You can configure the gem globally.

DataPlaneApi.configure do |c|
    # REQUIRED
    c.url = 'http://example.com'
    c.basic_user = 'api_user'
    c.basic_password = 'api_password'
    # OPTIONAL
    c.timeout = 25 # request timeout in seconds
    c.logger = Logger.new($stdout) # custom logger
end

These settings will be used by default in all requests without local configuration objects.

You can also create configuration objects and pass them as arguments to particular request method calls.

# create a config object
config = DataPlaneApi::Configuration.new(
    url: 'http://example.com',
    basic_user: 'api_user'
    basic_password: 'api_password'
)

# make a request
response = DataPlaneApi::Server.get_runtime_settings(
    backend: 'foo',
    config: config # use the configuration object
)

A configuration object like that may contain incomplete configuration data. Any missing options will be inherited from the global configuration object.

For example, let's say, that you've got a global configuration like that.

DataPlaneApi.configure do |c|
    c.url = 'http://example.com'
    c.basic_user = 'api_user'
    c.basic_password = 'api_password'
    c.timeout = 25 # request timeout in seconds
end

You want to change the timeout to 2 seconds for a single request. You can achieve it by creating a new config object which contains only the new data, that you want to change when compared to the global config. The rest will be inherited.

config = DataPlaneApi::Configuration.new(timeout: 2)
config.timeout #=> 2
config.url #=> 'http://example.com'
config.basic_user #=> 'api_user'

You will always get a Faraday::Response object as a return value from a request call.

The response body will be parsed to Ruby structures (Hash, Array, Integer, etc.)

You may want to look at the documentation of the faraday gem for more details.

Server endpoints live under the DataPlaneApi::Server module.

Return an array of runtime servers' settings

You can get an array of runtime servers' settings like so.

# @type [Faraday::Response]
response = DataPlaneApi::Server.get_runtime_settings(backend: 'my_backend_name')

response.status #=> 200
response.headers #=> {"server"=>"Fly/c375678 (2021-04-23)", "content-type"=> ...
response.body #=> [{"address":"12.0.5.102","admin_state":"ready","id":"1","name":"foo_bar1","operational_state":"up","port":4512}]

Return one server runtime settings

You can provide the name of a particular server to get only its settings.

# @type [Faraday::Response]
response = DataPlaneApi::Server.get_runtime_settings(backend: 'my_backend_name', name: 'my_server_name')

response.status #=> 200
response.headers #=> {"server"=>"Fly/c375678 (2021-04-23)", "content-type"=> ...
response.body #=> [{"address":"12.0.5.102","admin_state":"ready","id":"1","name":"foo_bar1","operational_state":"up","port":4512}]

You can override the global config by providing a config object.

# create a config object
config = DataPlaneApi::Configuration.new(timeout: 2)

response = DataPlaneApi::Server.get_runtime_settings(
    config: config # use the new config
    backend: 'my_backend_name',
    name: 'my_server_name'
)

Replace server transient settings

You can replace server transient settings like so.

# @type [Faraday::Response]
response = DataPlaneApi::Server.get_runtime_settings(
    backend: 'my_backend_name',
    name: 'my_server_name',
    settings: {
        admin_state: 'ready',
        operational_state: 'up'
    }
)

response.status #=> 200
response.headers #=> {"server"=>"Fly/c375678 (2021-04-23)", "content-type"=> ...
response.body #=> [{"address":"12.0.5.102","admin_state":"ready","id":"1","name":"foo_bar1","operational_state":"up","port":4512}]

You can override the global config by providing a config object.

# create a config object
config = DataPlaneApi::Configuration.new(timeout: 2)

response = DataPlaneApi::Server.get_runtime_settings(
    config: config # use the new config
    backend: 'my_backend_name',
    name: 'my_server_name',
    settings: {
        admin_state: 'ready',
        operational_state: 'up'
    }
)

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/espago/data_plane_api_ruby.

The gem is available as open source under the terms of the MIT License.