proxym is short for proxy manager. It generates configuration file(s) of a reverse proxy whenever something inside your system changes.

The original purpose of proxym is to use HAProxy as a reverse proxy for applications managed by Marathon and running on Apache Mesos with minimal downtime in case of a deployment.

Note that this is not so much about service discovery inside a Mesos cluster but about connecting services running in the cluster to the outside world.

However, its design makes it easy to integrate with systems other than Marathon.

The proxym executable itself is meant to run alongside a process of a reverse proxy (e.g. HAProxy), instructing it to reload its configuration whenever proxym recognizes a change in an outside system.

It takes a modular approach by dividing responsibility into three parts: Notifiers, ServiceGenerators and ConfigGenerators.

1. The Marathon Notifier has registered a callback via the Marathon Event Bus and receives an event in case an application is deployed or scaled. It notifies the Manager of that change.
2. The Manager asks all Service Generators for their available Services. In this case only the Marathon Service Generator is registered. It queries /v2/apps and /v2/tasks of a Marathon server, generates a list of Services and returns it back to the Manager.
3. The Manager calls all Annotators which enhance Services with additional configuration.
4. The Manager takes the list of Services and instructs the HAProxy Config Generator to create the configuration file for haproxy and restart it if the file has changed.

proxym provides a HTTP server where modules can register endpoints to expose an external API. The listen address of the server is configured by setting the environment variable PROXYM_LISTEN_ADDRESS.

A Notifier that watches PROXYM_FILE_CONFIGS_PATH for changes.

A ServiceGenerator that reads configuration from files. Configuration files are written in JSON and are a serialized representation of types.Service.

Environment variables:

# <PROXYM_FILE_CONFIGS_PATH>/myapp.json
{
  "ApplicationProtocol": "http",
  "Config": "option forwardfor",
  "Domains": ["example.org"],
  "Hosts": [
    {
      "Ip": "1.2.3.4",
      "Port": 56789
    }
  ],
  "Id": "file_example",
  "Port": 1234,
  "TransportProtocol": "tcp"
}

The value of types.Service.Source of services generated by the ServiceGenerator is File.

A ConfigGenerator that dynamically updates VHOSTs of Hipache.

Environment variables:

A ConfigGenerator that takes a list of Services and a template, writes the result to a file and issues a command to restart/reload a proxy process.

Environment variables:

The data passed to the template is a list of types.Service structs. Functions of the Hugo templating engine are available in the template. Take a look at this example configuration files of HAProxy and nginx.

Provides a Notifier that registers a callback with the event bus of Marathon and triggers a refresh whenever it receives a status_update_event.

A ServiceGenerator queries Marathon for applications and tasks.

Environment variables:

The value of types.Service.Source of services generated by the ServiceGenerator is Marathon.

A Notifier that constantly polls Mesos masters, extracts the current leader and triggers a refresh in case the leader has changed.

A ServiceGenerator that queries Mesos masters, extracts the current leader and emits a Service.

Environment variables:

The value of types.Service.Source of services generated by the ServiceGenerator is Mesos Master.

Triggers a refresh whenever the process receives a SIGUSR1 signal. The signal can be send by software such as Ansible, Chef or Puppet.

The log package defines the loggers AppLog, which writes to STDOUT, and ErrorLog, which writes STDERR.

The level of AppLog is configurable while the level of ErrorLog is ERROR.

Environment variables:

All available format options can be found in the docs of go-logging.