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
- Has any DNS records with values that are subdomains of
- Has DNS A records with values that are IP addresses of infrastructure maintained by Heroku
- Uses SSL termination add-ons of types
Apps correctly configured to use the current routing stack have the following characteristics:
- Uses CNAME, ALIAS or similar records with values that are subdomains of
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: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
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.
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
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.
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
www.mydomain.com. Note that redirects from
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.