Heroku mTLS Plugin CLI Commands

Last updated April 21, 2023

Heroku provides a CLI plugin for managing mutual TLS for Private and Shield Heroku Postgres and Apache Kafka on Heroku add-ons. You must have the Heroku CLI installed before adding the mTLS CLI plugin. See Installation for details.

Overview

The mTLS plugin commands enable you to:

For more info on Heroku’s plugins in general, see Using CLI Plugins.

mTLS and Heroku Postgres

For Heroku Postgres, the mTLS plugin also has commands to:

For more info on Postgres and mTLS, see Connecting to a Private or Shield Heroku Postgres Database from an External Resource.

mTLS and Apache Kafka on Heroku

All Kafka clusters running on Heroku have mTLS enabled by default.

When provisioning the Kafka add-on, Heroku automatically creates mTLS certificates for its use. Connections to Kafka clusters require authenticating with these certificates. They’re available in the KAFKA_TRUSTED_CERT, KAFKA_CLIENT_CERT and KAFKA_CLIENT_CERT_KEY config vars for your application. For more info, see Connecting to a Private or Shield Kafka Cluster From an External Resource.

The mtls:create, mtls:destroy and the different mtls:certificates commands of the mTLS plugin only apply to Heroku Postgres add-ons.

Installation

You must have the Heroku CLI installed before adding the Heroku Connect CLI plugin. See Heroku CLI for instructions.

If you have the Heroku CLI installed, install the mTLS plugin with:

# Install the plugin
heroku plugins:install @heroku-cli/plugin-mtls

# List arguments and subcommands
heroku help data:mtls
heroku help data:mtls:certificates
heroku help data:mtls:ip-rules

mTLS Commands for Heroku Postgres Only

The commands in this section work only for Heroku Postgres.

Apache Kafka on Heroku add-ons have mTLS enabled by default and users can’t disable it. You can view certificate info for Apache Kafka on Heroku add-ons in the app’s config vars and not via the commands shown in this section.

heroku data:mtls:create

This command enables mutual TLS on a Heroku Postgres add-on.

USAGE
  $ heroku data:mtls:create [ADDON]

OPTIONS
  -a, --app=app  (required) app to run command against

EXAMPLE
  $ heroku data:mtls:create postgresql-sinuous-83720 --app example-app

It typically takes between 5-10 minutes to enable Mutual TLS. Track the progress with heroku data:mtls

heroku data:mtls:certificates

This command lists available client-side certificates, their creation date, and status for a Heroku Postgres add-on.

USAGE
  $ heroku data:mtls:certificates [ADDON]

OPTIONS
  -a, --app=app  (required) app to run command against

EXAMPLE
  $ heroku data:mtls:ip-rules postgresql-sinuous-83720 --app example-app

heroku data:mtls:certificates:create

This command creates a certificate for a Heroku Postgres add-on with mTLS enabled.

USAGE
  $ heroku data:mtls:certificates:create [ADDON]

OPTIONS
  -a, --app=app  (required) app to run command against

EXAMPLE
  $ heroku data:mtls:certificates:create postgresql-sinuous-83720 --app example-app

heroku data:mtls:certificates:download

This command downloads a .zip certificate bundle for a Heroku Postgres add-on. Provide the id of the certificate to download with the --id flag.

USAGE
  $ heroku data:mtls:certificates:download [ADDON]

OPTIONS
  -a, --app=app    (required) app to run command against
  --dir=dir        directory to download files to. defaults to HOME:/.postgresql
  --id=id          ID of certificate to download
  --prefix=prefix  (required) prefix to put in front of downloaded file names

EXAMPLES
  $ heroku data:mtls:certificates:download postgresql-sinuous-83720 --id "3559a4df-2c82-4473-86cf-181310a6ef4f" --app example-app
  $ heroku data:mtls:certificates:download postgresql-sinuous-83720 --id "3559a4df-2c82-4473-86cf-181310a6ef4f" --dir
  "./folder" --app example-app
  $ heroku data:mtls:certificates:download postgresql-sinuous-83720 --id "3559a4df-2c82-4473-86cf-181310a6ef4f" --prefix
  "prefix_" --app example-app

The certificate bundle includes three files:

  • PREFIX_postgres.crt (client certificate with chain)
  • PREFIX_postgres.key (client private key)
  • PREFIX_root.crt (server certificate chain)

heroku data:mtls:certificates:get

This command displays details of a specific certificate for a Heroku Postgres add-on.

USAGE
  $ heroku data:mtls:certificates:get [ADDON]

OPTIONS
  -a, --app=app  (required) app to run command against
  --id=id        (required) id of IP Rule

EXAMPLE
  $ heroku data:mtls:certificates:create postgresql-sinuous-83720 --id "1862ec85-fdc1-47b3-924e-a91d26ca3a7c" --app example-app

heroku data:mtls:certificates:delete

This command deletes a specific certificate for a Heroku Postgres add-on.

USAGE
  $ heroku data:mtls:certificates:delete [ADDON]

OPTIONS
  -a, --app=app  (required) app to run command against
  --id=id        (required) id of certificate

EXAMPLE
  $ heroku data:mtls:certificates:delete postgresql-sinuous-83720 --id "1862ec85-fdc1-47b3-924e-a91d26ca3a7c" --app example-app

heroku data:mtls:destroy

This command disables mTLS for a Heroku Postgres add-on.

USAGE
  $ heroku data:mtls:destroy [ADDON]

OPTIONS
  -a, --app=app  (required) app to run command against

ALIASES
  $ heroku data:mtls:delete

EXAMPLE
  $ heroku data:mtls:destroy postgresql-sinuous-83720 --app example-app

mTLS Commands for Heroku Postgres and Apache Kafka on Heroku

The following commands are available for both Heroku Postgres and Apache Kafka on Heroku.

heroku data:mtls

This command displays the status of mTLS for an add-on.

For Heroku Postgres add-ons, this command displays the mTLS status, the list of IP rules and the certificate list.

For Apache Kafka on Heroku add-ons, this command displays the mTLS status and the list of IP rules. Certificate details are available in the app’s config vars.

USAGE
  $ heroku data:mtls [ADDON]

OPTIONS
  -a, --app=app  (required) app to run command against

EXAMPLE
  $ heroku data:mtls postgresql-sinuous-83720 --app example-app

heroku data:mtls:ip-rules

This command displays details of all the IP rules configured for mTLS for an add-on.

USAGE
  $ heroku data:mtls:ip-rules [ADDON]

OPTIONS
  -a, --app=app  (required) app to run command against

EXAMPLE
 $ heroku data:mtls:ip-rules postgresql-sinuous-83720 --app example-app
 $ heroku data:mtls:ip-rules kafka-animated-02313 --app example-app

heroku data:mtls:ip-rules:get

This command displays details of a specific IP rule. Provide the IP rule id with the --id flag.

USAGE
  $ heroku data:mtls:ip-rules:get [ADDON]

OPTIONS
  -a, --app=app  (required) app to run command against
  --id=id        (required) id of IP Rule

EXAMPLE
  $ heroku data:mtls:ip-rules:get postgresql-sinuous-83720 --id "1862ec85-fdc1-47b3-924e-a91d26ca3a7c" --app example-app
  $ heroku data:mtls:ip-rules:get kafka-animated-02313 --id "1862ec85-fdc1-47b3-924e-a91d26ca3a7c" --app example-app

heroku data:mtls:ip-rules:create

This command adds an IP rule to the mTLS configuration to include an IP range in the list of allowlisted IP blocks. Provide the IP address to allowlist with the --cidr parameter. Optionally, provide the --description flag to define a name or include metadata about the IP range.

USAGE
  $ heroku data:mtls:ip-rules:create [ADDON]

OPTIONS
  -a, --app=app              (required) app to run command against
  --cidr=cidr                (required)
  --description=description

EXAMPLE
  $ heroku data:mtls:ip-rules:create postgresql-sinuous-83720 --cidr "1.2.3.4/32" --description "home IP address" --app example-app
  $ heroku data:mtls:ip-rules:create kafka-animated-02313 --cidr "6.7.8.0/24" --description "office IP range" --app example-app

A hard limit of 60 IP blocks can be allowlisted per add-on.

Define individual IP addresses as /32 CIDR blocks.

heroku data:mtls:ip-rules:delete

This command deletes a specific IP rule from your mTLS configuration.

USAGE
  $ heroku data:mtls:ip-rules:delete [ADDON]

OPTIONS
  -a, --app=app  (required) app to run command against
  --cidr=cidr    cidr of IP Rule
  --id=id        id of IP Rule

EXAMPLE
  $ heroku data:mtls:ip-rules:delete postgresql-sinuous-83720 --id "1862ec85-fdc1-47b3-924e-a91d26ca3a7c" --app example-app
  $ heroku data:mtls:ip-rules:delete kafka-animated-02313 --id "1862ec85-fdc1-47b3-924e-a91d26ca3a7c" --app example-app

Feedback

Log in to submit feedback.