Custom routes

How to set up custom routes in your project

Qovery allows you to define the routes used in your environments.

A route describes how an incoming HTTP request is going to be processed by Qovery. The routes are defined using .qovery.yml file in your application repository.

FAQ

Before digging deeper into this guide, I would explain why you should not or why you should use it.

Why you should use it

  • You need to expose your application publicly through HTTPS
  • You need to have one endpoint (foo.com) targeting multiple backend applications

Why you should not use it

  • You only have one application within your environment
  • You are not sure why you should use it (ask us)

Concepts

Router

Qovery has the concept of "router" which is where the traffic transit from the World and your application. Each application that needs to be accessible from outside - needs to be attached to at least one router.

An application can be attached to 0 to n routers. It's up to you and depends on your use case.

A router is defined by:

  • a name (must be unique through the project)
  • 0 to n custom domains
  • 1 to n routes

Here is a configuration example of a router:

.qovery.yml
application:
name: my-app-1
project: my-project
cloud_region: aws/us-west-2
publicly_accessible: true
routers:
- name: main
custom_domains:
- branch: master
domain: my.tld.com
routes:
- application_name: my-app-1
paths:
- /

Route

A "route" is a concept to connect a "router" to an application. An application can have 0 to n routes.

A route is defined by:

  • a path
  • an application name

Here is a configuration example of a route:

.qovery.yml
application:
name: my-app-1
project: my-project
cloud_region: aws/us-west-2
publicly_accessible: true
routers:
- name: main
custom_domains:
- branch: master
domain: my.tld.com
routes:
- application_name: my-app-1
paths:
- /

Multiple routes

As explained above, each router can have multiple routes targeting different applications. Each application can use the same router by using the same router name within the same project.

Here is an example with two applications, which each of them have their own .qovery.yml file.

Application 1 - .qovery.yml
application:
name: my-app-1
project: my-project
cloud_region: aws/us-west-2
publicly_accessible: true
routers:
- name: main
custom_domains:
- branch: master
domain: my.tld.com
routes:
- application_name: my-app-1
paths:
- /
Application 2 - .qovery.yml
application:
name: my-app-2
project: my-project
cloud_region: aws/us-west-2
publicly_accessible: true
routers:
- name: main
custom_domains:
- branch: master
domain: my.tld.com
routes:
- application_name: my-app-2
paths:
- /app2/

Behind the scene Qovery will merge the two .qovery.yml into a single one. Which gives a router that will look like this:

Merged router
...
routers:
- name: main
custom_domains:
- branch: master
domain: my.tld.com
routes:
- application_name: my-app-1
paths:
- /
- application_name: my-app-2
paths:
- /app2/

Meaning, traffic with a route starting with the URL https://my.tld.com/app2 is routed on my-app-2, and the remaining traffic is routed on my-app-1.

Custom domains

A custom domain can be attached (optional) to a "router" and an environment. Then, multiple application can benefit from the same domain.

Example

Here is a concrete example to show how custom routes could be your best friend in a real-world application.

The e-commerce website

Let's imagine that we have to build an e-commerce website which gives the possibility to order shoes. This website must be able to take orders and provide an invoice for each order. Our system has one web interface, one order service, and one billing service that is for each of them an independent application.

What do we want?

  • The web interface must be available through shopping.com and www.shopping.com
  • The order service must be available through api.shopping.com/order
  • The billing service must be available through api.shopping.com/billing as well
  • The traffic coming on api.shopping.com and not covered by the two rules above must be routed on order

This is what the custom routing definition looks like for each of them

Web interface

Here is what the .qovery.yml looks like for the web interface:

.qovery.yml web interface
application:
name: web-interface
project: my-ecommerce-project
cloud_region: aws/us-west-2
publicly_accessible: true
routers:
- name: frontend
custom_domains:
- branch: master
domain: shopping.com
- branch: master
domain: www.shopping.com
routes:
- application_name: web-interface
paths:
- /

Order service

Here is what the .qovery.yml looks like for the order service:

.qovery.yml order service
application:
name: order-service
project: my-ecommerce-project
cloud_region: aws/us-west-2
publicly_accessible: true
routers:
- name: backend
custom_domains:
- branch: master
domain: api.shopping.com
routes:
- application_name: order-service
paths:
- /
- /order/

Billing service

Here is what the .qovery.yml looks like for the billing service:

.qovery.yml billing service
application:
name: billing-service
project: my-ecommerce-project
cloud_region: aws/us-west-2
publicly_accessible: true
routers:
- name: backend
custom_domains:
- branch: master
domain: api.shopping.com
routes:
- application_name: billing-service
paths:
- /billing/

At the end, api.shopping.com, shopping.com and www.shopping.com work as expected. Happy custom routing.