Extending Heroku

›

Building Add-ons

›

Add-on Development Tasks

›

Add-on Manifest

Add-on Manifest

Last updated 12 October 2018

Generating a manifest
Updating a manifest
Example manifest
Fields

The add-on manifest is a JSON document which describes the interface between Heroku and your cloud service. You write the manifest and use it with Kensa in your development environment, then send the final manifest to Heroku when you’re ready to submit your add-on to our marketplace.

Generating a manifest

You can initialize a new manifest using kensa:

$ kensa init
Initialized new addon manifest in addon-manifest.json

Updating a manifest

The new Partner Portal does not yet include the ability to update your add-on’s manifest in the interface. To update your add-on’s manifest, follow the instructions below to do so on the command line using kensa.

Make sure you have the latest kensa and then do an initial kensa pull:

$ kensa pull <add-on name>

When you’ve made the necessary changes and are ready to publish them, use push:

$ kensa push

Example manifest

{
  "id": "errorbucket",
  "name": "Errorbucket",
  "cli_plugin_name": "heroku-errorbucket",
  "api": {
    "config_vars_prefix": "ERRORBUCKET",
    "config_vars": [
      "ERRORBUCKET_URL"
    ],
    "password": "GqAGAmdrnkDFcvR9",
    "sso_salt": "7CwqmJLEjv8YZTXK",
    "regions": ["us","eu"],
    "requires": ["log_input"],
    "production": {
      "base_url": "https://errorbucket.com/heroku/resources",
      "sso_url": "https://errorbucket.com/sso/login"
    },
    "test": {
      "base_url": "http://localhost:4567/heroku/resources",
      "sso_url": "http://localhost:4567/sso/login"
    },
    "version": "3"
  }
}

Fields

`id`

An id for your add-on. This is what users will enter when they type “heroku addons:create [youraddon]” All lower case, no spaces or punctuation. This can’t be changed after the first push to Heroku. It is also used for HTTP basic auth when making provisioning calls.

`name`

The name of your add-on.

`cli_plugin_name`

The npm package name of your add-on service’s Heroku CLI plugin

`api/config_vars_prefix`

Optional and defaults to a normalized version of your add-on slug/ID (e.g. fast-db will have a prefix of FAST_DB). Config vars in your manifest and in response to provision requests MUST begin with this prefix, followed by a single _, then any valid identifier.

`api/config_vars`

A list of config vars that will be returned on provisioning calls. Typically you will have exactly one (the resource URL), but it’s perfectly fine to set multiple config vars to share secrets with an app.

`api/password`

A password that Heroku will send in HTTP basic auth when making provisioning calls.

`api/sso_salt`

Shared secret used in single sign-on between the Heroku admin panel and your service’s admin panel.

`api/regions`

The list of geographical regions supported by your add-on. It cannot be empty. Valid Cedar (standard stack) regions are:

us
eu

Valid Dogwood (Private Spaces) regions are:

dublin
frankfurt
oregon
sydney
tokyo
virginia

Add-ons must currently support at least the Cedar US region; EU and Dogwood support is optional. If your add-on is region-agnostic (e.g. not latency sensitive) and behavior does not differ from region-to-region, you may use the meta-region * to signify full support for any current or future region.

`api/requires`

A list of features you’d like to enable. The currently public list of features that can be enabled are:

log_input - Adds the log_input_url field to provision requests, which you can use to write your own messages to the log.
syslog_drain - Adds the log_drain_token field to provision requests. If you respond with a log drain URL, you can use this token to identify logs coming from the application. See this article for more details.
many_per_app - Allows developers to provision or attach multiple installations of your add-on. With this enabled, customers may also give attachments to the add-ons custom names.
attachable - Allows developers to share an add-on between multiple apps. If many_per_app is also enabled, it allows them to give the same add-on multiple aliases (attachments) to one app.

`api/version`

The version of the partner API (the HTTP interface Heroku uses to communicate with your add-on service). If no value is specified the manifest will assume 1, however the current version of the partner API is 3, so it is advisable to set this in your manifest.

`api/production/base_url`

The production endpoint for Heroku API actions (provision, deprovision, and plan change). The path /heroku/resources must always be at the end of this URL, and will be automatically appended on the server-side if it is missing.

`api/production/sso_url`

The production endpoint for single sign-on.

`api/test`

The root URL of your development host, typically local, or a map of URLs.

`api/test/base_url`

The test endpoint for heroku api actions. The path /heroku/resources must always be at the end of this URL, and will be automatically appended on the server-side if it is missing.

`api/test/sso_url`

The test endpoint for single sign-on.

Categories