Skip Navigation
Show nav
Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
    • .NET
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
Hide categories

Categories

  • Heroku Architecture
    • Compute (Dynos)
      • Dyno Management
      • Dyno Concepts
      • Dyno Behavior
      • Dyno Reference
      • Dyno Troubleshooting
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Developer Tools
    • Command Line
    • Heroku VS Code Extension
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery & Integration (Heroku Flow)
    • Continuous Integration
  • Language Support
    • Node.js
      • Troubleshooting Node.js Apps
      • Working with Node.js
      • Node.js Behavior in Heroku
    • Ruby
      • Rails Support
      • Working with Bundler
      • Working with Ruby
      • Ruby Behavior in Heroku
      • Troubleshooting Ruby Apps
    • Python
      • Working with Python
      • Background Jobs in Python
      • Python Behavior in Heroku
      • Working with Django
    • Java
      • Java Behavior in Heroku
      • Working with Java
      • Working with Maven
      • Working with Spring Boot
      • Troubleshooting Java Apps
    • PHP
      • Working with PHP
      • PHP Behavior in Heroku
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
    • .NET
      • Working with .NET
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
      • Migrating to Heroku Postgres
    • Heroku Key-Value Store
    • Apache Kafka on Heroku
    • Other Data Stores
  • AI
    • Working with AI
    • Heroku Inference
      • Inference API
      • Quick Start Guides
      • Inference Essentials
      • AI Models
    • Vector Database
    • Model Context Protocol
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
      • Single Sign-on (SSO)
    • Private Spaces
      • Infrastructure Networking
    • Compliance
  • Heroku Enterprise
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Databases & Data Management
  • Heroku Key-Value Store
  • Encrypting Heroku Key-Value Store with Your Encryption Key

Encrypting Heroku Key-Value Store with Your Encryption Key

English — 日本語に切り替える

Last updated April 22, 2025

Table of Contents

  • AWS Prerequisites
  • Create a Heroku Key-Value Store Instance With an Encryption Key
  • Migrate a Heroku Key-Value Store Instance to One Using an Encryption Key
  • Disabling Your Encryption Key
  • Enabling Your Encryption Key
  • Limitations

This article describes how to use AWS Key Management Service (KMS) to create a customer managed key (CMK) to encrypt Heroku Key-Value Store (KVS) in Private and Shield Spaces. This process involves three high-level steps:

  1. Create a customer managed key (CMK) in your AWS KMS
  2. Apply an identity and access management (IAM) policy to that CMK to permit Heroku Data to use the key on your behalf
  3. Create a Heroku Key-Value Store instance with the encryption key

AWS Prerequisites

You perform the steps in this section from your Amazon KMS dashboard. Alternatively, you can use the AWS CLI.

Step 1: Create a Customer Managed Key

When logged into the AWS web console, navigate to Key Management Service and click Create Key.

KMS console create key

Step 2: Select Symmetric Key

Select Symmetric for the key type, Encrypt and decrypt for the key usage, and click Next.

Symmetric Key

We use S3 to store backups and it only supports symmetric CMKs.

Step 3: Add Details and Set Permissions

Add an alias, such as heroku-data, and click Next. You can skip configuring key administrative permissions.

Add label

When defining key usage permissions, enter the Heroku Data AWS Account ID 021876802972 in the Other AWS accounts section, and click Next.

Account Id

Step 4: Review and Complete

Review the key policy and complete the creation. Make note of the Amazon resource name (ARN) of your CMK.

Review and complete

Step 5: Enable Automatic Key Rotation

You can enable automatic key rotation by navigating to the info page for your key. In the Automatic key rotation section, select Enable, and click Save.

Key Rotation

Alternative: Use the AWS CLI

You can use the AWS CLI to create your customer managed key (CMK) with the appropriate key policy.

$ export AWS_ACCOUNT_ID=`aws sts get-caller-identity --output text --query 'Account'`
$ export HEROKU_DATA_ACCOUNT_ID=021876802972
$ curl -s -o key-policy.json https://gist.githubusercontent.com/jdowning/8d146cd238de828141e81b458dc546f0/raw/fc2a69603dc1364f1bc2fd2b5beb0af210150444/key-policy.json
$ aws kms create-key --description 'heroku-data-test' --policy $(envsubst < key-policy.json)

The output of the create-key command includes the key’s ARN which you need during provisioning. This is referred to as CMK_ARN in later steps.

We recommend you enable automatic key rotation on your CMK:

$ aws enable-key-rotation --key-id CMK_ARN

Create a Heroku Key-Value Store Instance With an Encryption Key

Now that you have a customer managed key with the appropriate permissions configured, you can use that key to encrypt your data managed by Heroku Data. You need the full Amazon resource name (ARN) of your CMK. You can use the --encryption-key provisioning flag when creating your instance.

Encrypting Heroku Key-Value Store with your encryption key requires a Private or Shield Spaces plan.

 

The addons:create example follows the syntax for Heroku CLI v9.0.0 or later. If you’re on v8.11.5 or earlier, use the command:

$ heroku addons:create heroku-redis:private-7 --encryption-key CMK_ARN --app your-app-name
$ heroku addons:create heroku-redis:private-7 --app your-app-name -- --encryption-key CMK_ARN

Migrate a Heroku Key-Value Store Instance to One Using an Encryption Key

If you have an existing Heroku Key-Value Store instance, you can create a fork instance using your encryption key to migrate your data.

$ heroku addons:create heroku-redis:private-7 \
  --fork redis://h:<password>@<hostname>:<port> \
  --encryption-key CMK_ARN \
  --app your-app-name

After your fork is created and caught up to the leader, you can promote it.

$ heroku redis:promote <kvs-addon-name> --app example-app

Promoting a forked KVS instance updates the REDIS_URL config var, and restarts the application. You can read more details about promotion in Upgrading a Heroku Key-Value Store Version.

Disabling Your Encryption Key

As part of the lifecycle of your encryption key, you may need to disable the key. When performing this action, all data encrypted with the key is rendered inaccessible.

Disabling an encryption key triggers a shutdown of all services and servers that use that key. Use extreme caution when taking this action. We recommend you notify and coordinate with Support when performing this action.

You can disable your encryption key via the AWS web console or the AWS CLI.

$ aws kms disable-key --key-id CMK_ARN

When we receive notification of the key disablement, there’s a 10 minute waiting period before action is taken. This waiting period is to ensure accidental changes to the key status don’t unnecessarily alter resources that depend on the key.

After the 10 minute waiting period, we shut down all services that use the encryption key. Next, we stop all servers that run those services. Finally, we send an email notification to application administrators notifying them of the disabled action.

Expect approximately 20 minutes to elapse between key disablement and service shutdown.

Enabling Your Encryption Key

To regain access to data that is encrypted with your encryption key, you may enable that key to restore. You can enable your encryption key via the AWS web console or the AWS CLI.

$ aws kms enable-key --key-id CMK_ARN

After we receive notification of the key enablement, we start previously stopped servers. When they’re running, we start affected services. Finally, we send an email notification to application administrators notifying them of the enabled action.

Expect approximately five minutes to elapse between key enablement and service restart.

Limitations

There are limitations that apply to instances encrypted with a customer encryption key.

  • This feature is only available for Heroku Key-Value Store on Private and Shield plans.

For your security, there’s no automated way to migrate from using a customer-supplied key to a Heroku-managed key lifecycle. If you want to stop using this feature on one or more data services, contact Heroku Support.

Keep reading

  • Heroku Key-Value Store

Feedback

Log in to submit feedback.

Upgrading a Heroku Key-Value Store Version Heroku Key-Value Store

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure
  • .NET

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing
  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Github
  • LinkedIn
  • © 2025 Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners. Salesforce Tower, 415 Mission Street, 3rd Floor, San Francisco, CA 94105, United States
  • heroku.com
  • Legal
  • Terms of Service
  • Privacy Information
  • Responsible Disclosure
  • Trust
  • Contact
  • Cookie Preferences
  • Your Privacy Choices