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.
Before you begin, this page assumes the following:
- You have installed the Qovery CLI
- You need to deploy more than one application (e.g backend and frontend)
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:
application:name: my-app-1project: my-projectpublicly_accessible: trueport: 8080routers:- name: maincustom_domains:- branch: masterdomain: my.tld.comroutes:- application_name: my-app-1paths:- /
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:
application:name: my-app-1project: my-projectpublicly_accessible: trueport: 8080routers:- name: maincustom_domains:- branch: masterdomain: my.tld.comroutes:- application_name: my-app-1paths:- /
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:name: my-app-1project: my-projectpublicly_accessible: trueport: 8080routers:- name: maincustom_domains:- branch: masterdomain: my.tld.comroutes:- application_name: my-app-1paths:- /
application:name: my-app-2project: my-projectpublicly_accessible: trueport: 8080routers:- name: maincustom_domains:- branch: masterdomain: my.tld.comroutes:- application_name: my-app-2paths:- /app2/
Behind the scene Qovery will merge the two .qovery.yml into a single one. Which gives a router that will look like this:
...routers:- name: maincustom_domains:- branch: masterdomain: my.tld.comroutes:- application_name: my-app-1paths:- /- application_name: my-app-2paths:- /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:
application:name: web-interfaceproject: my-ecommerce-projectpublicly_accessible: truerouters:- name: frontendcustom_domains:- branch: masterdomain: shopping.com- branch: masterdomain: www.shopping.comroutes:- application_name: web-interfacepaths:- /
Order service
Here is what the .qovery.yml
looks like for the order service:
application:name: order-serviceproject: my-ecommerce-projectpublicly_accessible: truerouters:- name: backendcustom_domains:- branch: masterdomain: api.shopping.comroutes:- application_name: order-servicepaths:- /- /order/
Billing service
Here is what the .qovery.yml
looks like for the billing service:
application:name: billing-serviceproject: my-ecommerce-projectpublicly_accessible: truerouters:- name: backendcustom_domains:- branch: masterdomain: api.shopping.comroutes:- application_name: billing-servicepaths:- /billing/
At the end, api.shopping.com
, shopping.com
and www.shopping.com
work as expected.
Happy custom routing.