Accepting Custom Options on Provision

Last updated 15 August 2017

When provisioning at the command-line, customers have the option of specifying additional options which we pass along to you. You can use these to provide additional functionality to your install that cannot be determined simply by plan or by accessing additional customer information through the Unified API. For example, Heroku PostgreSQL uses customer options to support creating database forks and followers.

Command-line parameter format

The command-line accepts parameters in standard Unix-style switch format, with or without an equals sign. Single parameters are interpreted as boolean switches and will have the string 'true' as their value.

For example, the following command line:

$ heroku addons:create youraddon --foo=bar --bar foo --baz

Will be interpreted as:

{ "foo" : "bar", "bar" : "foo", "baz" : "true" }

Accessing parameters

Heroku passes command-line parameters given to the addons:create action during add-on provisioning to the add-on partner.

These options are passed in the JSON body of the provision request via the “options” key.

Consider this example:

$ heroku addons:create youraddon --foo=bar --bar foo --baz

The options are included as part of the JSON in the provision request:

POST /heroku/resources HTTP/1.0
Content-Type: application/json
{
  "options": {"foo":"bar","bar":"foo","baz":"true"},
  "heroku_id": "app12345@heroku.com",
  "plan": "test",
  "callback_url": "http://localhost:7779/callback/999"
}

You can use the kensa gem to test the extra command line parameters:

$ kensa test provision --foo=bar --bar foo --baz