We’re changing how dev environment URLs are generated

UPDATE 6 April 2022: There are times where we have to revisit our plan, and today is one of those times.

Last week, we released a fix to solve some inconsistencies in how our development URLs are generated.

Even though this change was not impacting any production environments, many customers reported that it was breaking their test integrations with third-party services, or that they were reaching a provisioning limit with our Let’s Encrypt certificates.

As our mission is to ensure that all of our customers can develop and deploy their applications with confidence, we decided to take a step back and revert this change.

Timeline

We will upgrade every project within the next few days. Once your project is upgraded, you can generate the new URLs by triggering a deployment (via the CLI or within Console).

Impact

After the upgrade, we are not going to prefix your default domain in your development URLs.

This means that the following route configuration below:

“https://{default}/”:
  type: upstream
  upstream: “app:http”

“https://foo.com/”:
  type: upstream
  upstream: “app:http”

“https://bar.com/”:
  type: upstream
  upstream: “app:http”

will generate the following set of development URLs:

<environment-name>-<hash>-<project-id>.<region>.platformsh.site
<environment-name>-<hash>-<project-id>.<region>.platformsh.site
bar.com-<environment-name>-<hash>-<project-id>.<region>.platformsh.site

Read more on our public documentation regarding routes configuration.

We sincerely apologize for any inconvenience this may have caused you. If you need more help, please contact our Support or join our Slack channel.

Original post

Everything Platform.sh provides is based on your configuration files. One of these files is the routes.yaml file which has a very important job of instructing our platform how to handle requests to your application. In this file, you can set some keywords that we call “placeholders” such as {default} and {all}. These placeholders make it easier to work with your domains without having to explicitly state them over and over again. Remember the DRY principle? ;-)

The way these domains are then generated as routes on your development environment can vary depending on whether you use these placeholders or not. This has led to some confusion as the route generation should be consistent no matter which technique you prefer. We have decided to correct this by standardizing the way these domains are generated.

This change has no impact on how routes are generated for your production environments, but it will mean that you may start seeing development URLs you have bookmarked returning 502 errors because they no longer exist.

As an example, let’s look at a project that has two domains associated with it, where the first (foo.com) is the default domain:

1. foo.com - default
2. bar.com

Scenario 1 - defining routes explicitly

In your routes.yaml file, instead of using a placeholder, you declare the routes explicitly:

“https://foo.com/”:
  type: upstream
  upstream: “app:http”

“https://bar.com/”:
  type: upstream
  upstream: “app:http”

When your development environments are being built, the URLs are generated for each domain as follows:

foo.com.<environment-name>-<hash>-<project-id>.<region>.platformsh.site
bar.com.<environment-name>-<hash>-<project-id>.<region>.platformsh.site

Scenario 2 - defining routes using placeholders

Alternatively, you could declare routes implicitly using the {default} placeholder:

“https://{default}/”:
  type: upstream
  upstream: “app:http”

“https://bar.com/”:
  type: upstream
  upstream: “app:http”

When your development environments are being built, the URLs are generated for each domain that you declare instead looked like this:

<environment-name>-<hash>-<project-id>.<region>.platformsh.site
bar.com.<environment-name>-<hash>-<project-id>.<region>.platformsh.site

The difference between these generated routes is the prefix of your default domain is missing when using the {default} placeholder. This is an inconsistency we would like to avoid - we want to keep the generated routes the same no matter how they are defined in the routes.yaml file.

So again what exactly is the change?

From now on, we are going to include the default domain into the development environment’s generated URL for both of the cases above. This means that both scenarios will now generate the same set of URLs no matter whether you use the domain explicitly or implicitly with the {default} placeholder:

That is, both scenarios will result in these development environment URLs:

foo.com.<environment-name>-<hash>-<project-id>.<region>.platformsh.site
bar.com.<environment-name>-<hash>-<project-id>.<region>.platformsh.site

Our recommendation is to adopt the {default} and {all} placeholders to take advantage of the reusability of your code and the simplicity of the routes that they generate. Otherwise, be sure to update any bookmarked development environment URLs you use for primary staging or other dedicated work.

Read more on our public documentation regarding Routes configuration.