Last updated September 05, 2023

Private Spaces are dedicated environments for running dynos and certain types of add-ons within an isolated network. Access to apps in a Private Space can be controlled at the network level. Outbound requests from apps in a Private Space originate from a set of stable IP addresses, which allows you to securely communicate with services at allowed IPs on-premise or on other networks. Private Spaces enable you to build and run Heroku apps that meet strict requirements for data protection and change control, as commonly required by corporate and regulatory governance standards.

There are two types of Private Space: the standard Private Space and the Shield Private Space. The Shield Private Space includes additional features for building and running high-compliance applications.

You can deploy to Private Spaces with the familiar git push heroku master command or take full advantage of Heroku Pipelines. The powerful governance and security features provided by Private Spaces do not change the standard Heroku developer experience.

Private Space Management

Only team administrators can create, destroy, or modify Private Spaces. All team members can view details about Private Spaces in the team.

Regions

Private Spaces can be created in the following regions:

To create a Private Space in a given region, simply specify the location when creating the space.

The region cannot be changed after the Private Space is created. All apps created in a Private Space are in the same region as the space.

Heroku gives you more detailed information about each of these regions in the Platform API. For more information, see the Regions article.

Create a Private Space

To create a Private Space using Dashboard, click the Spaces tab inside your team and click Create new Private Space. When creating the Private Space, you can optionally choose a region (geographic location) for your apps and data services. When you fill out the form and click Create Private Space, your new space is created within ten minutes.

To create a Private Space using the Heroku CLI, use the spaces:create command:

$ heroku spaces:create my-space-name --team my-team-name
Creating space my-space-name in team my-team-name... done
=== my-space-name
Team:   my-team-name
Region: virginia
State:  allocating

Creating a new Private Space can take a few minutes. To track its status, use the spaces:wait command:

$ heroku spaces:wait my-space-name
Waiting for space my-space to allocate... done

Choose a Region

To create a Private Space in a particular region, specify the --region option with the region’s name from the list of regions. For example:

$ heroku spaces:create my-space-name --team my-team-name --region tokyo
Creating space my-space-name in team my-team-name... done
=== my-space-name
Team:   my-team-name
Region: tokyo
State:  allocating

Choose Your Private Network CIDR Range

If you wish to connect your Private Space to other networks, such as an Amazon VPC or an on-premises network, you may wish to specify the dyno or data CIDR ranges that your Private Space will use to ensure no overlap with your private network. You can specify a private network CIDR range to connect services in your environment to Heroku.

The data CIDR range is used for Heroku private data add-ons.

To create a space with a custom dyno or data VPC CIDR range, the --cidr and --data-cidr flags can be specified via the CLI.

$ heroku spaces:create --cidr 172.16.0.0/16 --data-cidr 10.100.0.0/20 --space my-space-name
Creating space my-space-name in team my-team-name... done
=== my-space-name
Team:   my-team-name
Region: tokyo
State:  allocating

• A /16 CIDR range is required for the dyno VPC (--cidr)
• A /20 is the minimum CIDR range size for the data VPC (--data-cidr)
• You cannot specify a CIDR range that overlaps with 172.17.0.0/16 or 10.1.0.0/16
• After Private Space creation, these dyno and data CIDR values cannot be changed
• Specifying the Private Space CIDR ranges can only be done via the CLI (and not the Dashboard)

View Info About a Private Space

All team members can view information about the Private Spaces in a team.

In Dashboard, click the Spaces tab inside your team. The Space info displays the team to which the Space belongs, as well as the current state of the Space. The allocating state indicates that the Space is being set up and is not yet operational. When it becomes operational, the state will change to allocated.

In the Heroku CLI, use the spaces:info command:

$ heroku spaces:info --space my-space-name
=== my-space-name
ID:           12345678-abcd-1234-abcd-12345678abcd
Team:         acme
Region:       Tokyo, Japan
State:        allocated
Shield:       on
Outbound IPs: 52.198.127.12, 52.197.133.34, 52.199.6.12, 52.198.222.211
Created at:   2016-10-13T05:36:15Z

Trusted IP ranges

Only team administrators can manage trusted IP ranges for a Private Space.

Each Private Space has a set of trusted IP ranges, with each range represented in CIDR block notation (for example, 192.0.2.0/24). Only clients originating from one of these trusted IP ranges can access web processes running in the Private Space. Use trusted IP ranges to restrict traffic to apps that come from your corporate network or from a CDN service that proxies traffic for your apps.

When a new Private Space is created, it’s configured with a default trusted IP range of 0.0.0.0/0 which will admit traffic from the entire internet.

Trusted IP ranges can be managed in Dashboard by opening the Network tab for a Private Space.

List current trusted IP ranges for a Private Space using the CLI:

$ heroku trusted-ips --space acme-prod
=== Trusted IP Ranges
192.0.2.0/26
192.0.2.64/26

Add a new range using the CLI:

$ heroku trusted-ips:add 192.0.2.128/26 --space acme-prod
Added 192.0.2.128/26 to trusted IP ranges on acme-prod
 ▸    WARNING: It may take a few moments for the changes to take effect.

Trusted IP ranges for data services

By default, trusted IP ranges only apply to web processes running in the space. Data services, like Heroku Postgres, Heroku Data for Redis and Apache Kafka on Heroku, can only be accessed from dynos within the space. You can optionally choose to also allow access from trusted IP addresses to data services in the space. During the beta, this feature can only be controlled by a Heroku operator. Open a ticket at help.heroku.com to request to have Trusted IPs for data products enabled or disabled. Some caveats do exist for this feature:

• 0.0.0.0/0 will be ignored as a Trusted IP for data products because this CIDR block would expose the database to the wider Internet.
• Granular controls do not exist. A Trusted IP will be able to reach both web dynos and data products.

Stable Outbound IP addresses

All team members can view the list of stable outbound IP addresses for a Private Space.

All outbound traffic from apps in a Private Space will originate from a small, stable list of IP addresses that are dedicated to the space. You can use lists of allowed IPs to secure services being accessed by apps in the space. For example, you can configure a web services gateway in your corporate data center to only allow access from the IP addresses assigned to the Private Space. By using this in combination with TLS and application level authentication tokens, you get an extra level of security for protecting resources in your corporate data center.

You can find the stable outbound IP addresses for a Space on the Settings tab for the Space in Dashboard. You can also use the CLI:

$ heroku spaces:info --space acme-prod
=== acme-prod
ID:           12345678-ed4a-4e96-b998-3fcb499439e0
Team: acme
Region:       virginia
State:        allocated
Outbound IPs: 192.0.2.2, 192.0.2.3, 192.0.2.4, 192.0.2.5
Created at:   2015-08-07T16:16:56Z

Destroy a Private Space

Only team administrators can destroy a Private Space. Private Spaces that contain applications or other resources cannot be destroyed. Apps must be explicitly deleted before destroying a Private Space.

In the Heroku dashboard, click Space Settings and choose Delete Space.

In the Heroku CLI, use the spaces:destroy command:

$ heroku spaces:destroy --space my-space-name
Destroying space my-space-name... done
=== my-space-name
Team:  my-team-name
State: deleting

App Availability

If your app requires high availability, we suggest that you scale up your dyno formation to a minimum of 3 dynos for each process type. Dynos are provisioned via round robin in one of three availability zones (AZ) associated with the Private Space. This helps maintain application availability in the unlikely scenario of an AZ failure.

If an AZ becomes unhealthy or unavailable, Private Spaces will automatically reschedule your dyno on a working AZ. When the unhealthy AZ returns to a healthy state, Private Spaces automatically redistributes your dynos.

Rolling Deploys with Zero Downtime

The first time an app is deployed (pushed) to a Private Space, it can take several minutes for the app to become available because of the time needed to set up the underlying dedicated infrastructure (e.g., routing, DNS, and the dynos).

For subsequent releases (code deployments or config var changes) there is a much shorter delay, and users may experience little to no downtime. There may be brief downtime if there is only one dyno for the app. If there are multiple dynos, zero downtime is possible. This is because of a Private Spaces feature called rolling deploys.

Rolling deploys are analogous to Preboot on the Common Runtime. Both enable zero downtime during new releases. Preboot does this by ensuring that new web dynos are started (and receiving traffic) before the existing ones are terminated. Rolling deploys do this by stopping and changing only up to 25% of the existing dynos at a time in each of dyno types including web dynos and other worker dynos, while the remaining dynos handle requests and tasks. The effect is that all requests are handled (no user downtime) while the new release is pushed gradually to the entire formation.

To be more precise, because of rolling deploys, there will be zero downtime during a new release for a Private Space app if all of the following are true:

• The app has been deployed at least once and is running.
• The app has at least two dynos and is not currently at capacity (that is, it has enough dynos that it can still service requests with up to 25% of its dynos missing. If the app has only 2 or 3 dynos then the remaining 1 or 2 dynos must be able to handle the existing load while the release is rolled out).
• Any databases attached to the app are not incurring schema changes and are compatible with both the old and new app release (forwards- and backward-compatible).

Managing Apps in Private Spaces

A Private Space represents a trust boundary within which your team can deploy and manage apps that handle sensitive data. Therefore, the ability to create apps in a Private Space is constrained to team administrators and those who have been granted the “app creation” permission for a particular space. Once an app has been created, the administrator can give other members additional access to the app using fine-grained access controls.

Create an App in a Private Space

The only users who can create apps in a Private Space are:

• Team administrators
• Team members that have been granted the “app creation” permission by an administrator. (This can be done in the Heroku Dashboard by clicking on the Space and then clicking Access.)

In the Heroku Dashboard, click on a space and choose Create New App.

In the Heroku CLI use the create command:

$ heroku create my-space-app --space my-space-name
Creating my-space-app in space my-space-name... done
http://my-space-app-1234567890ab.herokuapp.com/ | https://git.heroku.com/my-space-app.git

After the app is created, you can grant other team members access using one of several app permissions. Only members who are trusted to access any sensitive data protected by the space should be granted more than view permissions. All other members, who may develop on the app but who do not need production access, should only be granted access to staging and development environments.

Deploy an App in a Private Space

Code can be deployed (pushed) to Private Space apps in the same ways as with Common Runtime apps (such as by using git push heroku master or a GitHub integration).

Scaling a Process

Scaling your dyno formation follows the same pattern within Private Spaces as with the Common Runtime. For example:

$  heroku ps:scale web=2 worker=1

One-Off Dynos

“One-off” dynos are available via heroku run:

$ heroku run bash
Running bash...
▸    WARNING: Warning: Dynos can take up to a few minutes to be provisioned in Private Spaces.

List Apps in a Private Space

All team members can view all apps in a Private Space:

$ heroku apps --space my-space-name
=== Apps in space my-space-name
my-space-app-1
my-space-app-2

View Info About an App in a Private Space

All team admins can view detailed info about a single app in a Private Space:

$ heroku info --app my-space-app
=== my-space-app
Collaborators: my-team-name@example.com

Git URL:       https://git.heroku.com/my-space-app.git
Owner:         my-team-name
Region:        tokyo
Space:         my-space-name
Stack:         heroku-20
Web URL:       http://my-space-app-1234567890ab.herokuapp.com/

Destroy an App in a Private Space

Team admins and members who have manage permission on an app can destroy it:

$ heroku apps:destroy -a my-space-app
Destroying my-space-app (including all add-ons)... done

Adding Custom Domains and SSL

Only team administrators and members who have manage permission on an app can add custom domains and manage SSL.

SSL and custom domains for apps in Spaces are handled similarly to apps in the Common Runtime. See the Custom Domains and SSL documentation for detailed steps.

Shield Private Spaces

Shield Private Spaces include additional features for building high-compliance applications. See the Shield Private Space article for details on features.

Add-ons and Private Spaces

If you attempt to provision an add-on for an app in a Heroku Private Space and that add-on is not available in that app’s Private Spaces region, you will see a message saying so.

To view which add-ons are available in a region, go to the Add-on Runtime Availability. Select the Private Spaces tab to view information for Private Spaces regions.

You can also view this information in the Region Availability section of the Elements listing page for each add-on.

Add-ons Marked as Available in a Private Space

Many add-ons offer plans that are compatible with Private Space regions, even though they operate outside the Private Space. This means that network traffic between your private dyno and the add-on resource travels across the public Internet. These add-ons are marked as “Available” with a green dot in Add-on Runtime Availability.

You can add these add-ons to apps running in a Private Space as you would normally for our Common Runtime:

$ heroku addons:create newrelic:wayne -a appname
Creating newrelic-cubic-72448... done, (free)
Adding newrelic-cubic-72448 to appname... done
Setting NEW_RELIC_LICENSE_KEY, NEW_RELIC_LOG and restarting appname... done, v80
Use `heroku addons:docs newrelic` to view documentation.

Some add-ons of type “datastore” are compatible with Private Spaces regions. They can be provisioned through the CLI with the addons:create command, or they can be provisioned in the Dashboard. Either way, you will have to confirm that you understand that this use of a data store not contained within the Private Space network boundary is explicitly intended; that using this add-on plan will send data over the public Internet.

To provision from the CLI you must follow the confirmation prompt:

$ heroku addons:create <addon name> -a appname
 !    This add-on is not automatically networked with this Private Space.
 !    To proceed, type "appname" or re-run this command with --confirm appname

For information on Heroku add-on credits and overage payments mechanisms, see the Heroku Enterprise documentation.

Add-ons Marked as Available and Installable in a Private Space

Some add-ons are installable in Private Spaces. This means that all network traffic between dynos and the add-on resource stays within the private network of the space, and the add-on resource does not have to be exposed on the public Internet. These add-ons are marked as “Available & Installable in Private Space” with a blue dot in Add-on Runtime Availability.

Heroku Postgres and Heroku Data for Redis are examples of add-ons that are created inside Heroku Private Spaces. When you select a Heroku Postgres or Heroku Data for Redis private plan for an app in a Private Space, the resource will be automatically created in the same region as the Heroku Private Space and peered to the Heroku Private Space.

To create a Heroku Postgres instance inside your Heroku Private Space, you must select a private-0 plan or above. Since this Add-On will be automatically created inside your Space, confirmation is not required.

$ heroku addons:create heroku-postgresql:private-0 -a your-private-app-name

It is possible to provision Heroku Postgres and Heroku Data for Redis plans outside of your Space. Provision by specifying app, plan, and region using the --region flag.

$ heroku addons:create heroku-postgresql:standard-4 --region=us -a your-private-app-name

You are asked to confirm the addition of the plan via the CLI.

 !    This add-on is not automatically networked with this Private Space.
 !    To proceed, type "appname" or re-run this command with --confirm appname

Migrate Apps and Data to or From a Private Space

There is no automated feature, at this time, to migrate apps and data to or from a Private Space, but it can be done manually. You should first back up and migrate the database(s), if any. App code should then be re-pushed to the destination. You should also consider differences in the way Private Spaces operate and whether any add-ons the app uses will work or need to be configured differently in the destination. For instance, SSL for apps in Private Spaces works slightly differently. See Migrating Apps From the Common Runtime to a Private Space for more info.

Transferring a Private Space

It’s possible to transfer a Private Space from one Enterprise Team to another. The user making the transfer should be an “admin” in both Enterprise Teams or have “Manage” permissions in the company’s Enterprise Account. To transfer a Space navigate to its Settings tab, then find the Enterprise Team you want to move it to in the Space Ownership section.

Default Limits for Private Spaces

Private Spaces Runtime are built on a different architecture than the Common Runtime, and Private Spaces has different default limits. To have limits increased for any of your private spaces, please open a support ticket.

The current default limits for newly created Spaces are:

• 20 Trusted IP ranges
• 20 apps
• 100 process types (10 dynos per process type)
• 100 dynos for the entire Space

Concurrent One-off Dyno Limits

A Private Space app has the following limits for one-off dynos:

• Up to 5 one-off private-s dynos running concurrently
• Up to 5 one-off private-m dynos running concurrently
• Up to 5 one-off private-l dynos running concurrently
• Up to 5 one-off shield-s dynos running concurrently
• Up to 5 one-off shield-m dynos running concurrently
• Up to 5 one-off shield-l dynos running concurrently