Using the Auto Pools feature streamlines deployment by enabling pools to be automatically configured, started, and stopped using Marathon™ app labels or SDK task labels (annotations).

Edge-LB automatically provisions pools using pool templates. A default pool template is created at the time of Edge-LB installation. The template is rendered into a pool configuration based on the values of the app / task labels that follows. Use the command dcos edgelb pool-template show default to show the default Auto Pool template, which is always available unless the default Auto Pool is disabled on install of the Edge-LB service. If you have already created a pool, you can get the template through Edge-LB when you install it using dcos edgelb template show <pool_name> for the pool haproxy template.

Default Pool

The minimum label configuration to expose a service is:

"labels": {
  "edgelb.expose": "true"
}

This sample shows all of the supported labels with a <group> of secure and nonsecure:

"labels": {
  "edgelb.expose": "true",
  "edgelb.template": "default",
  "edgelb.delimiter": ",",
  "edgelb.item_delimiter": "|",
  "edgelb.key_delimiter": ":",
  "edgelb.nonsecure.frontend.redirectToHttps": "",
  "edgelb.secure.frontend.certificates": "$AUTOCERT",
  "edgelb.secure.frontend.port": "443",
  "edgelb.secure.frontend.protocol": "HTTPS",
  "edgelb.secure.frontend.rules": "hostEq:www.test.com|pathBeg:/a",
  "edgelb.secure.backend.balance": "roundrobin",
  "edgelb.secure.backend.portName": "web",
  "edgelb.secure.backend.protocol": "HTTP",
  "edgelb.secure.backend.rewriteHttp.path": "/a:/",
  "edgelb.secure.backend.rewriteHttp.sticky": ""
}

An example Marathon™ application can be found in the example apps. For an in-depth tutorial exposing applications, see the tutorial.

The default pool template selects tasks with the label "edgelb.expose" : true. You can then further customize the template using labels.

Some labels use a <group> in their name. The <group> value can be any ASCII string value except expose, template, delimiter, item_delimiter, key_delimiter, and the string cannot contain a ..

Groups are used for two tasks:

1. Grouping frontend and backend options, allowing a single task to be exposed in multiple frontends.
2. Grouping backend services, such as multiple instances on a Marathon app. All tasks with the same <group> will be listed as a separate service entry in a single backend named by the group. The default group if no options are provided is __default__.

We recommend using the <group> field to describe the frontend app, such as website, or broker.

Supported Labels

Managing Pool Templates

You can deploy multiple Auto Pools by creating additional poolTemplates using the API or command line. When created, the new poolTemplate is a copy of the default template which you can then modify, if needed. In addition, you can get the status of template rendering.

For more information about the api, such as parameters and payload, refer to the Edge-LB API reference.

CLI example usage

To list the templates created (including the default template):

dcos edgelb pool-template list
  NAME
  default

To create a new pool template:

dcos edgelb pool-template create dobby
Successfully created dobby. Check "dcos edgelb pool-template show dobby" or "dcos edgelb pool-template status dobby" for deployment status

dcos edgelb pool-template list
  NAME
  default
  dobby

Each new pool template is a copy of the default template with the magic string __ELB_POOL_TEMPLATE_NAME__ replaced with the poolTemplate's name.

To see rendering information and status:

dcos edgelb pool-template status default
  NAME     STATUS  MESSAGE
  default  OK      pool has been successfully
                   deployed

dcos edgelb pool-template status dobby
  NAME   STATUS    MESSAGE
  dobby  NO_TASKS  no matching mesos tasks for
                   the given pool template were
                   found

To fetch the current template:

dcos edgelb pool-template show dobby > dobby.tmpl

To update the current template:

dcos edgelb pool-template update dobby dobby.tmpl

To reset the current template back to the default:

dcos edgelb pool-template reset dobby
Successfully reset Pool Template dobby. Check "dcos edgelb pool-template show dobby" or "dcos edgelb pool-template status dobby" for deployment status

To delete the pool template and the pools deployed by it:

dcos edgelb pool-template delete dobby
Successfully deleted dobby. Check the DC/OS web UI for pool uninstall status.

Template Functions

Templates have access to all sprig functions with the exception of env and expandenv which have been removed for security reasons. This is the same set of functions used by Helm.

In addition a function mesosTasks returns a list of structs for the template to use:

// TmplMesosTask is a simplified view of the Task for use in the templates
// it is not a sprig `dict` (map[string]interface{}) to allow access to the
// `MesosTask` field in the template without type asserting.
type TmplMesosTask struct {
	TaskID      string                 `json:"-"`
	FrameworkID string                 `json:"-"`
	Labels      map[string]interface{} `json:"-"`
	Ports       []interface{}          `json:"-"`

	// Access to the raw task is given for advanced use
	MesosTask *mesos_v1.Task `json:"-"`

	// Only these fields will be rendered to json
	Message string              `json:"message"`
	Status  models.RenderStatus `json:"status"`
	URIs    []string            `json:"uris"`
}

Another function parseTaskLabels will parse the labels into a nested dict structure (discussed below).

Templates must use the renderPoolTemplate function to render a defined template. The defined template should either render a pool configuration, or call the noTasks function, to signal that no tasks were selected for the pool and therefore should not be started. (See the default pool template for an example).

Default Template Implementation

The default template transforms the task list into an intermediary representation, and then uses that representation to render the final pool configuration or determine that no tasks met its selection.

For example, suppose the mesosTasks function returned the following (shown in JSON for convenience):

[
  {
    "TaskID": "task1",
    "FrameworkID": "framework1_id",
    "Labels": {
      "edgelb.expose" : true
    }
  },
  {
    "TaskID": "task2",
    "FrameworkID": "framework2_id",
    "Labels": {
      "edgelb.expose" : true,
      "edgelb.template": "default",
      "edgelb.web.frontend.certificates": "mycertsecret",
      "edgelb.web.frontend.port": "443",
      "edgelb.web.frontend.protocol": "HTTPS",
      "edgelb.web.frontend.rules": "pathBeg:/web|hostEq:www.test.com",
      "edgelb.web.backend.portName": "web",
      "edgelb.web.backend.protocol": "HTTP",
      "edgelb.web.backend.rewriteHttp.path": "/web:/"
    }
  }
]

The default template pool then uses parseTaskLabels to transform the labels into a nested dict structure. For example the Labels from task2 will produce:

{
  "expose": "true",
  "template": "default",
  "web": {
    "frontend": {
      "certificates": [
        "mycertsecret"
      ],
      "port": "443",
      "protocol": "HTTPS",
      "rules": [
        {
          "hostEq": "www.test.com",
          "pathBeg": "/web"
        }
      ]
    },
    "backend": {
      "portName": "web",
      "protocol": "HTTP",
      "rewriteHttp": {
        "path": {
          "/web": "/"
        }
      }
    }
  }
}

This format is then further transformed within the template into the global intermediary variables $BACKENDS, $FRONTENDS and $SECRETS:

$BACKENDS

{
  "__default__": {
    "service": [
      {
        "task_id": "task1",
        "framework_id": "framework1_id",
        "endpoint": {
          "portName": "name_of_first_port",
        }
      }
    ]
  },
  "web": {
    "service": [
      {
        "task_id": "task2",
        "framework_id": "framework2_id",
        "endpoint": {
          "portName": "web",
        }
      }
    ],
    "rewriteHttp": {
      "path": {
        "fromPath": "/web",
        "toPath": "/"
      }
    }
  }
}

$FRONTENDS

{
  "80": {
    "protocol": "HTTP",
    "maps": [
      {
        "pathBeg": "/",
        "backend": "__default__"
      }
    ]
  },
  "443": {
    "protocol": "HTTPS",
    "certificates": ["$SECRETS/mycertsecret"],
    "maps": [
      {
        "hostEq": "www.test.com",
        "pathBeg": "/web",
        "backend": "web"
      }
    ]
  }
}

$SECRETS

[
  {
    "secret": "mycertsecret",
    "file": "mycertsecret"
  }
]

These intermediary variables are then used to render the final pool configuration. If there are no $BACKENDS, noTasks will be called.