URL redirects

Tab Settings → Redirects — platform administrators only.

A redirect answers every request sent to a host name with a 301 (permanent redirect) to the URL of your choice. It serves service migrations, both ways:

• from outside into the cluster: the former domain of a service (www.customer.com, for instance) is redirected to the application that replaces it in the cluster;
• from the cluster to the outside, or to another application: the former address of a cluster application (old-app.<cluster domain>) is redirected to its new service, internal or external.

Browsers and search engines remember a permanent redirect: existing links and bookmarks keep working.

Creating a redirect

New redirect:

1. Redirected host name: the name alone, without https:// or path. It cannot change afterwards: to change it, delete the redirect and create it again.
2. Target:
   • Cluster application: choose the namespace, then the application; the target URL becomes the root of the application;
   • URL: any http:// or https:// address, without a query string (?…) or fragment (#…).
3. Keep the request path (checked by default): https://old-address/docs/a.pdf leads to <target>/docs/a.pdf. Unchecked, every request leads to the target URL itself. The query string is kept in both cases.
4. Create.

http:// addresses of the redirected name are redirected too.

Host name certificate

• Cluster subdomain (old-app.<cluster domain>): covered by the cluster certificate, the redirect is active within seconds.
• External domain: a dedicated certificate is requested from Let's Encrypt. First point the domain's DNS to the public address of the cluster, shown in the creation dialog: Let's Encrypt checks the domain by reaching it. The certificate is usually issued within one or two minutes.

• Provided certificate (option of the dialog, for any host name): use a certificate generated outside the platform (internal authority, purchased certificate, etc.). Paste or load from a file:

  • the certificate in PEM format: the server certificate first, followed by the intermediate certificates;
  • the private key in PEM format, unencrypted.

  The Control Panel checks that the key matches the certificate, that the certificate covers the host name (exact name or *.domain wildcard) and that it has not expired. The key is only kept in the cluster (TLS Secret), never in the Control Panel database. The domain's DNS must still point to the cluster, but no Let's Encrypt check takes place.

No automatic renewal

A provided certificate is not renewed by the platform: the row shows its expiry date (in orange within 30 days). Before it expires, open Edit and upload the new certificate and its key; left empty, the current certificate is kept.

Following a redirect

Each row shows:

• Cluster domain or External domain;
• Path kept or Path replaced;
• Route: ready when the cluster gateway serves the redirect; pending right after a creation or a change;
• Certificate (external domain): pending until Let's Encrypt has issued the certificate. Hover the badge to read the details, for instance a DNS that does not point to the cluster yet. For a provided certificate: ready, or error once expired, with its issuer and expiry date.

Refresh reads the state from the cluster again.

Editing, deleting

• Edit: change the target, the path option, the description or the certificate (switch to a provided certificate or back to the automatic one, upload a new certificate). The new target applies within seconds.
• Delete: the host name is no longer redirected; its dedicated certificate (issued or provided) is deleted too.

Host name still in use

A redirect cannot be created for a host name that an application or a route still serves: the message names the object concerned. To redirect the former address of an application, delete the application first.