Moving to the Current Routing Stack

Last Updated: 12 February 2015

bamboo routing

Table of Contents

Heroku has two routing stacks, a legacy stack and a current stack. We’re actively retiring the legacy stack, and you should migrate all apps to the current router. The legacy routing stack and associated infrastructure will be shut off on October 20th, 2014.

If you have questions or comments on how to change DNS settings to use the new router, feel free to post a topic on the Heroku Forums.

How to tell what routing stack an app is using

Apps using legacy routing has one or more of the following characteristics:

  • Has and uses example-app.heroku.com domain
  • Has any DNS records with values that are subdomains of .heroku.com (typically proxy.heroku.com or example-app.heroku.com)
  • Has DNS A records with values that are IP addresses of infrastructure maintained by Heroku
  • Uses SSL termination add-ons of types ssl:ip or ssl:hostname

Apps correctly configured to use the current routing stack have the following characteristics:

  • Uses example-app.herokuapp.com domain
  • Uses CNAME, ALIAS or similar records with values that are subdomains of .herokuapp.com

Heroku provides a tool that will check domains associated with all apps that you have access to for correct configuration. Find it here: https://legacy-routing.herokuapp.com/

You should migrate domains configured to use legacy routing as soon as possible. The legacy routing stack and the infrastructure supporting ssl:ip and ssl:hostname endpoints will be shut off on October 20th 2014.

Note that a single app with multiple domains may have some domains that are using legacy routing and some that are using current routing. Make sure that all domains actively used by your apps are correctly configured.

Legacy routing analyzer

Heroku maintains an analyzer that checks the routing set-up of your Heroku apps. Find it here: https://legacy-routing.herokuapp.com/.

The routing analyzer will check all the domains associated with all of your apps. For each domain, it will check whether the DNS records are suspect per the criteria above. If the DNS records are suspect, it will further check to see whether the Heroku legacy router has recently handled any requests for that domain. If the legacy router has seen requests for a domain it is show as “in use”.

The legacy routing analyzer will let you quickly find apps and domains that need migrating. In general you should upgrade DNS for any domain identified to be pointing at the legacy router, but pay particular attention to domains for which the legacy router has gotten requests recently.

Migrating to the current routing stack

Apps using example-app.heroku.com subdomain

For apps currently using example-app.heroku.com subdomains, Heroku has added a new example-app.herokuapp.com domain (note the change from heroku.com to herokuapp.com). Requests to .heroku.com subdomain will use the legacy routing stack while requests on .herokuapp.com will use the current routing stack.

You should migrate your users to use the new .herokuapp.com domain, for example by redirecting requests that come in on the legacy .heroku.com domain. The domain for any particular request is available in the Host HTTP header.

After October 20th, routing for customer apps on the legacy example-app.heroku.com domain will be shut down. Apps will only be available on example-app.herokuapp.com and on any custom domains correctly configured to use the current routing.

The example-app.heroku.com domain cannot be removed from an app. Instead of removing this domain, redirect users visiting it to the apps' primary domain as described above.

Apps with custom domains

If the routing analyzer flags custom domains on any of your apps, you most likely have to update the DNS records for the affected domain.

Currently, your DNS records are likely A records pointed at IP addresses maintained by Heroku or CNAME records pointed at a subdomain under the .heroku.com domain, for example proxy.heroku.com or example-app.heroku.com. You can check DNS records with your DNS provider or by running host example.com in a terminal (or nslookup example.com in a console on Windows).

You must change these to be CNAME records pointed at example-app.herokuapp.com as detailed in the Custom Domain name guide.

If you are using a root domain (i.e. mydomain.com vs. www.mydomain.com), you can still do so if your DNS provider supports CNAME-like records for the DNS zone apex. See the list of DNS providers that can be used to host sites on root domains on Heroku.

Using an SSL endpoint? DNS records should be pointed at the endpoint name, i.e. tokyo-2121.herokussl.com.. See the SSL Endpoint Dev Center article for details.

If you are not using one of those DNS providers and cannot switch to a DNS provider that supports CNAME-like records for the zone apex, then you cannot use root domains (eg. mydomain.com) with apps on Heroku after October 20th. Consider switching to www.mydomain.com and configure a redirect from mydomain.com to www.mydomain.com. Note that redirects from https://mydomain.com/ to https://www.mydomain.com/ most likely cannot be made to work because your DNS provider (who is issuing the HTTP redirect) won’t have the relevant certificate for your domain.

Technical differences between legacy and current routing stack

There are a few differences between the legacy and the current router that you should be mindful of when migrating. In particular, the legacy router offers gzip and deflate compression of HTTP responses and will buffer incoming requests before passing requests to dynos.

If these features are important to your app, you can get compression support by use Rack::Deflater in Ruby Rack apps, or you can use the nginx buildpack to get both response compression and request buffering.