This document describes the API interface between the reference haproxy driver and its corresponding haproxy-based amphorae.
Octavia reference haproxy amphorae use a web service API for configuration and control. This API should be secured through the use of TLS encryption as well as bi-directional verification of client- and server-side certificates. (The exact process for generating and distributing these certificates should be covered in another document.)
In addition to the web service configuration and control interface, the amphorae may use an HMAC-signed UDP protocol for communicating regular, less- vital information to the controller (ex. statistics updates and health checks). Information on this will also be covered in another document.
If a given loadbalancer is being serviced by mutiple haproxy amphorae at the same time, configuration and control actions should be made on all these amphorae at approximately the same time. (Amphorae do not communicate directly with each other, except in an active-standby topology, and then this communication is limited to fail-over protocols.)
Contents
All Octavia APIs (including internal APIs like this one) are versioned. For the purposes of this document, the initial version of this API shall be v0.1. (So, any reference to a :version variable should be replaced with the literal string ‘v0.1’.)
Typical response codes are:
In the below API, it will become apparent that at times the amphora will need to be aware of the state of things (topology-wise, or simply in terms running processes on the amphora). When it comes to storing or gathering this data, we should generally prefer to try to resolve these concerns in the following order. Note also that not every kind of state data will use all of the steps in this list:
In no case should the amphora assume it ever has direct access to the Octavia database. Also, sensitive data (like TLS certificates) should be stored in a secure way (ex. memory filesystem).
JSON Response attributes:
Examples
JSON response:
{
'hostname': 'octavia-haproxy-img-00328',
'uuid': '6e2bc8a0-2548-4fb7-a5f0-fb1ef4a696ce',
'topology': 'SINGLE',
'role': 'ACTIVE',
'ha_ip': '',
}
Notes: In an ACTIVE-STANDBY configuration, the ‘role’ parameter might change spontaneously due to a failure of one node. In other topologies, the role is not used.
Also note that some topology changes can take several minutes to enact, yet we want all API commands to return in a matter of seconds. In this case, a topology change is initiated, and the amphora status changes from “OK” to “TOPOLOGY-CHANGE”. The controller should not try to change any resources during this transition. (Any attempts will be met with an error.) Once the topology change is complete, amphora status should return to “OK”. (When the UDP communcation from amphorae to controller is defined, a ‘transition complete’ message is probably one good candidate for this type of UDP communication.)
Examples
JSON POST parameters:
{
'topology': 'ACTIVE-STANDBY',
'role': 'ACTIVE',
'ha_ip': ' 203.0.113.2',
'secret': 'b20e06cf1abcf29c708d3b437f4a29892a0921d0',
}
Response:
OK
Response:
{
'message': 'Invalid request',
'details': 'Unknown topology: BAD_TEST_DATA',
}
Response:
{
'message': 'Topology transition in progress',
}
JSON Response attributes:
Notes: The data in this request is used by the controller for determining the amphora and API version numbers.
It’s also worth noting that this is the only API command that doesn’t have a version string prepended to it.
Examples:
{
'hostname': 'octavia-haproxy-img-00328.local',
'uuid': '6e2bc8a0-2548-4fb7-a5f0-fb1ef4a696ce',
'haproxy_version': '1.5.11',
'api_version': '0.1',
}
JSON Response attributes:
Notes: The data in this request is meant to provide intelligence for an auto-scaling orchestration controller (heat) in order to determine whether additional (or fewer) virtual amphoras are necessary to handle load. As such, we may add additional parameters to the JSON listing above if they prove to be useful for making these decisions.
The data in this request is also used by the controller for determining overall health of the amphora, currently-configured topology and role, etc.
Examples
{
'hostname': 'octavia-haproxy-img-00328.local',
'uuid': '6e2bc8a0-2548-4fb7-a5f0-fb1ef4a696ce',
'haproxy_version': '1.5.11',
'api_version': '0.1',
'networks': {
'eth0': {
'network_tx': 3300138,
'network_rx': 982001, }}
'active': 'TRUE',
'haproxy_count': 3,
'cpu':{
'total': 0.43,
'user': 0.30,
'system': 0.05,
'soft_irq': 0.08,
},
'memory':{
'total': 4087402,
'free': 760656,
'available': 2655901,
'buffers': 90980,
'cached': 1830143,
'swap_used': 943,
'shared': 105792,
'slab': 158819,
'committed_as': 2643480,
},
'disk':{
'used': 1234567,
'available': 5242880,
},
'load': [0.50, 0.45, 0.47],
'tolopogy': 'SINGLE',
'topology_status': 'OK',
'listeners':[
'02d0da8d-fc65-4bc4-bc46-95cadb2315d2',
'98e706a7-d22c-422f-9632-499fd83e12c0',
],
'packages':[
{'haproxy': '1.5.1'},
{'bash': '4.3.23'},
{'lighttpd': '1.4.33-1'},
{'openssl': '1.0.1f'},
<cut for brevity>
],
}
URL: /:version/interface/:ip
Method: GET
URL params:
- :ip = the ip address to find the interface name
Data params: none
Success Response:
Error Response:
Response:
Examples:
GET URL:
https://octavia-haproxy-img-00328.local/v0.1/interface/10.0.0.1
JSON Response:
{
'message': 'OK',
'interface': 'eth1'
}
GET URL:
https://octavia-haproxy-img-00328.local/v0.1/interface/10.5.0.1
JSON Response:
{
'message': 'Error interface not found for IP address',
}
GET URL:
https://octavia-haproxy-img-00328.local/v0.1/interface/10.6.0.1.1
JSON Response:
{
'message': 'Bad IP address version',
}
JSON Response attributes:
Note that the command will return an array of all listeners’ statuses. Each listener status contains the following attributes:
Notes: Note that this returns a status if: the pid file exists, the stats socket exists, or an haproxy configuration is present (not just if there is a valid haproxy configuration).
Examples
[{
'status': 'ACTIVE',
'uuid': 'e2dfddc0-5b9e-11e4-8ed6-0800200c9a66',
'type': 'HTTP',
},
{
'status': 'STOPPED',
'uuid': '19d45130-5b9f-11e4-8ed6-0800200c9a66',
'type': 'TERMINATED_HTTPS',
}]
JSON Response attributes:
Notes: Note that this returns a status if: the pid file exists, the stats socket exists, or an haproxy configuration is present (not just if there is a valid haproxy configuration).
Examples
JSON Response:
{
'status': 'ACTIVE',
'uuid': 'e2dfddc0-5b9e-11e4-8ed6-0800200c9a66',
'type': 'HTTP',
'pools':[
{
'uuid': '399bbf4b-5f6c-4370-a61e-ed2ff2fc9387',
'status': 'UP',
'members':[
{'73f6d278-ae1c-4248-ad02-0bfd50d69aab': 'UP'},
{'2edca57c-5890-4bcb-ae67-4ef75776cc67': 'DOWN'},
],
},
{
'uuid': '2250eb21-16ca-44bd-9b12-0b4eb3d18140',
'status': 'DOWN',
'members':[
{'130dff11-4aab-4ba8-a39b-8d77caa7a1ad': 'DOWN'},
],
},
],
}
JSON Response:
{
'message': 'Listener Not Found',
'details': 'No listener with UUID: 04bff5c3-5862-4a13-b9e3-9b440d0ed50a',
}
Examples:
PUT URL:
https://octavia-haproxy-img-00328.local/v0.1/listeners/04bff5c3-5862-4a13-b9e3-9b440d0ed50a/start
JSON Response:
{
'message': 'OK',
'details': 'Configuration file is valid\nhaproxy daemon for 04bff5c3-5862-4a13-b9e3-9b440d0ed50a started',
}
PUT URL:
https://octavia-haproxy-img-00328.local/v0.1/listeners/04bff5c3-5862-4a13-b9e3-9b440d0ed50a/BAD_TEST_DATA
JSON Response:
{
'message': 'Invalid Request',
'details': 'Unknown action: BAD_TEST_DATA',
}
PUT URL:
https://octavia-haproxy-img-00328.local/v0.1/listeners/04bff5c3-5862-4a13-b9e3-9b440d0ed50a/stop
JSON Response:
{
'message': 'Listener Not Found',
'details': 'No listener with UUID: 04bff5c3-5862-4a13-b9e3-9b440d0ed50a',
}
PUT URL:
https://octavia-haproxy-img-00328.local/v0.1/listeners/04bff5c3-5862-4a13-b9e3-9b440d0ed50a/stop
Response:
{
'message': 'Error stopping haproxy',
'details': 'haproxy process with PID 3352 not found',
}
Response:
{
'message': 'Topology transition in progress',
}
Examples
DELETE URL:
https://octavia-haproxy-img-00328.local/v0.1/listeners/04bff5c3-5862-4a13-b9e3-9b440d0ed50a
JSON Response:
{
'message': 'OK'
}
DELETE URL:
https://octavia-haproxy-img-00328.local/v0.1/listeners/04bff5c3-5862-4a13-b9e3-9b440d0ed50a
JSON Response:
{
'message': 'Listener Not Found',
'details': 'No listener with UUID: 04bff5c3-5862-4a13-b9e3-9b440d0ed50a',
}
Response:
{
'message': 'Topology transition in progress',
}
Notes: * filename.pem should match the primary CN for which the certificate is valid. All-caps WILDCARD should be used to replace an asterisk in a wildcard certificate (eg. a CN of ‘*.example.com’ should have a filename of ‘WILDCARD.example.com.pem’). Filenames must also have the .pem extension. * In order for the new certificate to become effective the haproxy needs to be explicitly restarted
Examples:
PUT URI:
https://octavia-haproxy-img-00328.local/v0.1/listeners/04bff5c3-5862-4a13-b9e3-9b440d0ed50a/certificates/www.example.com.pem
(Put data should contain the certificate information, concatenated as
described above)
JSON Response:
{
'message': 'OK'
}
PUT URI:
https://octavia-haproxy-img-00328.local/v0.1/listeners/04bff5c3-5862-4a13-b9e3-9b440d0ed50a/certificates/www.example.com.pem
(If PUT data does not contain a certificate)
JSON Response:
{
'message': 'No certificate found'
}
PUT URI:
https://octavia-haproxy-img-00328.local/v0.1/listeners/04bff5c3-5862-4a13-b9e3-9b440d0ed50a/certificates/www.example.com.pem
(If PUT data does not contain an RSA key)
JSON Response:
{
'message': 'No RSA key found'
}
PUT URI:
https://octavia-haproxy-img-00328.local/v0.1/listeners/04bff5c3-5862-4a13-b9e3-9b440d0ed50a/certificates/www.example.com.pem
(If the first certificate and the RSA key do not have the same modulus.)
JSON Response:
{
'message': 'Certificate and key do not match'
}
PUT URI:
https://octavia-haproxy-img-00328.local/v0.1/listeners/04bff5c3-5862-4a13-b9e3-9b440d0ed50a/certificates/www.example.com.pem
JSON Response:
{
'message': 'Listener Not Found',
'details': 'No listener with UUID: 04bff5c3-5862-4a13-b9e3-9b440d0ed50a',
}
Response:
{
'message': 'Topology transition in progress',
}
Notes: The md5sum is the sum from the raw certificate data as stored on the amphora (which will usually include the RSA key, certificate and chain concatenated together). Note that we don’t return any actual raw certificate data as the controller should already know this information, and unnecessarily disclosing it over the wire from the amphora is a security risk.
Examples:
JSON response:
{
'md5sum': 'd8f6629d5e3c6852fa764fb3f04f2ffd',
}
JSON Response:
{
'message': 'Listener Not Found',
'details': 'No listener with UUID: 04bff5c3-5862-4a13-b9e3-9b440d0ed50a',
}
JSON Response:
{
'message': 'Certificate Not Found',
'details': 'No certificate with file name: www.example.com.pem',
}
Examples:
DELETE URL:
https://octavia-haproxy-img-00328.local/v0.1/listeners/04bff5c3-5862-4a13-b9e3-9b440d0ed50a/certificates/www.example.com.pem
JSON Response:
{
'message': 'OK'
}
DELETE URL:
https://octavia-haproxy-img-00328.local/v0.1/listeners/04bff5c3-5862-4a13-b9e3-9b440d0ed50a/certificates/www.example.com.pem
JSON Response:
{
'message': 'Certificate Not Found',
'details': 'No certificate with file name: www.example.com.pem',
}
Response:
{
'message': 'Topology transition in progress',
}
Notes: The uploaded configuration file should be a complete and syntactically-correct haproxy config. The amphora does not have intelligence to generate these itself and has only rudimentary ability to parse certain features out of the configuration file (like bind addresses and ports for purposes of setting up stats, and specially formatted comments meant to indicate pools and members that will be parsed out of the haproxy daemon status interface for tracking health and stats).
Examples:
PUT URL:
https://octavia-haproxy-img-00328.local/v0.1/listeners/d459b1c8-54b0-4030-9bec-4f449e73b1ef/04bff5c3-5862-4a13-b9e3-9b440d0ed50a/haproxy
(Upload PUT data should be a raw haproxy.conf file.)
JSON Response:
{
'message': 'OK'
}
JSON Response:
{
'message': 'Invalid request',
'details': '[ALERT] 300/013045 (28236) : parsing [haproxy.cfg:4]: unknown keyword 'BAD_LINE' out of section.\n[ALERT] 300/013045 (28236) : Error(s) found in configuration file : haproxy.cfg\n[ALERT] 300/013045 (28236) : Fatal errors found in configuration.',
}
Response:
{
'message': 'Topology transition in progress',
}
Examples:
GET URL:
https://octavia-haproxy-img-00328.local/v0.1/listeners/7e9f91eb-b3e6-4e3b-a1a7-d6f7fdc1de7c/haproxy
Response is the raw haproxy.cfg:
# Config file for 7e9f91eb-b3e6-4e3b-a1a7-d6f7fdc1de7c
(cut for brevity)
JSON Response:
{
'message': 'Listener Not Found',
'details': 'No listener with UUID: 04bff5c3-5862-4a13-b9e3-9b440d0ed50a',
}
URL: /:version/plug/vip/:ip
Method: Post
URL params:
- :ip = the vip’s ip address
Data params:
- subnet_cidr: The vip subnet in cidr notation
- gateway: The vip subnet gateway address
- mac_address: The mac address of the interface to plug
Success Response:
Error Response: * Code: 400
- Content: Invalid IP
- Content: Invalid subnet information
Response:
Examples:
POST URL:
https://octavia-haproxy-img-00328.local/v0.1/plug/vip/203.0.113.2
JSON POST parameters:
{
'subnet_cidr': '203.0.113.0/24',
'gateway': '203.0.113.1',
'mac_address': '78:31:c1:ce:0b:3c'
}
JSON Response:
{
'message': 'OK',
'details': 'VIP 203.0.113.2 plugged on interface eth1'
}
JSON Response:
{
'message': 'Invalid VIP',
}
JSON Response:
{
'message': 'No suitable network interface found',
}
- mac_address: The mac address of the interface to plug
Examples:
POST URL:
https://octavia-haproxy-img-00328.local/v0.1/plug/network/
JSON POST parameters:
{
'mac_address': '78:31:c1:ce:0b:3c'
}
JSON Response:
{
'message': 'OK',
'details': 'Plugged interface eth1'
}
JSON Response:
{
'message': 'No suitable network interface found',
}
Notes: Since certificates might be valid for a time smaller than the amphora is in existence this add a way to rotate them. Once the certificate is uploaded the agent is being recycled so depending on the implementation the service might not be available for some time.
Examples:
PUT URI:
https://octavia-haproxy-img-00328.local/v0.1/certificate
(Put data should contain the certificate information, concatenated as
described above)
JSON Response:
{
'message': 'OK'
}
PUT URI:
https://octavia-haproxy-img-00328.local/v0.1/certificates
(If PUT data does not contain a certificate)
JSON Response:
{
'message': 'No certificate found'
}
PUT URI:
https://octavia-haproxy-img-00328.local/v0.1/certificate
(If PUT data does not contain an RSA key)
JSON Response:
{
'message': 'No RSA key found'
}
PUT URI:
https://octavia-haproxy-img-00328.local/v0.1/certificate
(If the first certificate and the RSA key do not have the same modulus.)
JSON Response:
{
'message': 'Certificate and key do not match'
}
OK
Examples:
PUT URI:
https://octavia-haproxy-img-00328.local/v0.1/vrrp/upload
JSON Response:
{
'message': 'OK'
}
Examples:
PUT URL:
https://octavia-haproxy-img-00328.local/v0.1/vrrp/start
JSON Response:
{
'message': 'OK',
'details': 'keepalived started',
}
PUT URL:
https://octavia-haproxy-img-00328.local/v0.1/vrrp/BAD_TEST_DATA
JSON Response:
{
'message': 'Invalid Request',
'details': 'Unknown action: BAD_TEST_DATA',
}
PUT URL:
https://octavia-haproxy-img-00328.local/v0.1/vrrp/stop
JSON Response:
{
'message': 'Failed to stop keepalived service: keeepalived process with PID 3352 not found',
'details': 'keeepalived process with PID 3352 not found',
}