Clusters

About Clusters

This section brings you answers to all the questions our users usually ask about clusters:

• What is a cluster?
• Why do I need a cluster?
• How do I set up a cluster?
• What are the different instance types available when creating a cluster?
• How does Qovery handle cluster updates and upgrades?

What is a cluster?

At Qovery, when we refer to clusters, we mean Kubernetes clusters. A Kubernetes cluster is a collection of node machines that allows you to run containerized applications. It is usually made up of:

• Pods: think of a pod as one instance of your application. Pods are the smallest deployable objects in Kubernetes, and they are hosted by worker nodes.
• Worker Nodes: worker nodes essentially run your applications and workloads. When you create a cluster from your Qovery Console, it generates the set up of worker nodes (also called “instances”, “EC2 instances” for AWS users, or “droplets” for DigitalOcean users). Qovery allows you to define worker nodes settings, so that you end up deploying the right type of instances on your infrastructure based on your CPU, memory, storage and network performance needs.
• a Control Plane (or Master Node): the control plane manages the worker nodes. Since we deploy managed Kubernetes services, the control plane is handled exclusively by your cloud provider, and left untouched by Qovery.

For more information on Kubernetes clusters, see the Kubernetes documentation.

Qovery allows you to create:

• (AWS users only) K3s (AWS EC2) single node clusters. This cluster type has been released in BETA
• EKS (Kubernetes Managed) multiple node clusters.

	K3s Cluster	EKS Cluster
Starting Cost	20$/month	200$/month
Usage	Hobby projects, trying out Qovery, deploying preview environments on AWS.	Hosting professional applications in production (resilient, scalable and powerful infrastructure).

K3s clusters are deployed on one AWS availability zone. Therefore, if a network or power disruption happens on the availability zone where your K3s instance is running, your applications will no longer be available until it is solved.

This is why we do not recommend installing K3s clusters to run professional applications in a production environment.

For information on how to install:

• (AWS users only) a K3s cluster, see Creating a K3s Cluster (Single node cluster).
• an EKS cluster, see Creating an EKS Cluster (Multiple Node cluster).

Why do I need a cluster?

Qovery is built on top of Kubernetes, which means we need Kubernetes clusters to be able to deploy and run your applications.

Thanks to clusters, you can easily deploy several (and many) instances of the same application, so that if one fails, the others can instantly take over. Also, clusters can auto-scale, meaning that the number of worker nodes in a cluster can automatically go up or down as traffic fluctuates on your application(s), thus ensuring high availability and performance. Clusters are also extremely useful to isolate your production environment from your staging environment.

In short, through the use of clusters, Kubernetes provides you with a resilient, flexible and powerful infrastructure, fit for production environment needs and requirements. And with the help of Qovery, setting up and maintaining your Kubernetes clusters has never been easier.

How do I set up a cluster?

For step-by-step guidelines on how to set up a cluster on your cloud provider account using the Qovery Console, see Creating a Cluster.

What are the different instance types available when creating a cluster?

The range of instance types available at cluster creation depends on your cloud provider:

• AWS offers over 400 instance types. You can view their details on the official AWS website, as well as their pricing.
• DigitalOcean offers 5 different plans according to the instance types (aka “droplets”) you need. You can view details and pricing on the official DigitalOcean website.
• Scaleway also offers a wide range of instance types, whose details and pricing you can view on the official Scaleway website.

Qovery supports only instance types having an x86_64 architecture.

How does Qovery handle cluster updates and upgrades?

As far as cluster updates and upgrades to a newer version of Kubernetes are concerned, our Qovery engineering team handles everything in due time, so you don’t even need to think about it!

You may notice that Qovery does not provide you with the latest Kubernetes version offered by your cloud provider. This is due to the high amount of testing we need to perform to ensure smooth upgrades with no interruptions for your applications. Our priority is always to guarantee you maximum uptime.

Managing your Clusters with Qovery

From the Qovery Console, you can manage the settings of the clusters you want to run on your infrastructure. The clusters are then created (or updated) by the cloud provider that hosts them.

Creating a Cluster

Qovery allows you to create:

• (AWS users only) K3s (AWS EC2) single node clusters. For information on how to install a K3s cluster, see Creating a K3s Cluster (Single Node Cluster).
• EKS (Kubernetes Managed) multiple node clusters. For information on how to install an EKS cluster, see Creating an EKS Cluster (Multiple Node Cluster)

If you need help to pick your cluster type, see What is a cluster?.

Creating a K3s Cluster (Single Node Cluster)

K3s (AWS EC2) is still in BETA phase and has the following limitations

• You can’t access the historical logs and thus you can access your application logs only if it's running (Since we don’t have loki installed)
• No public accessibility for DB container (we do not manage the public DNS entry for db). We will work on it in the upcoming weeks, in the meantime we will write a guide on how to connect to the DB via the ssh key / kubeconf
• You can configure only 1 instance per application. Thus you can’t change the number of instances nor activate the sticky session feature
• We do not manage YET the cluster version upgrades
• Stop instance feature not ready YET
• You can’t change the cluster settings without a service downtime since we kill the instance and we spawn a new one
• We do not manage YET the external storage
• We do not support YET the VPC setting
• If you want to connect via SSH, you can't get YET the instance hostname directly in the Qovery console, you need to get it from the AWS console

To create a K3s cluster (only available to AWS users):

1. Open your Qovery Console.

2. On the top right hand-side of the screen, click the cogwheel icon to access your Organization settings:

   

3. Click Add Cluster:

   

4. In the Create Cluster window:

   

   • Enter cluster name: enter the name of your choice for your cluster.
   • Production cluster: select this option if your cluster will be used for production.
   • Cloud provider: select your cloud provider.
   • Region: select the geographical area in which you want your cluster to be hosted.
   • Credentials: select the select the credentials generated on your cloud provider account.
   
   

   If this is the first time you are using these credentials on your Qovery Console, click the Credentials field, and select New Credentials to register them.

   To confirm, click Next.

5. In the Set Resources window:

   

   • Kubernetes: select BETA - EC2 K3S (single instance only - dev purpose).
   • Instance type: select the type of worker node you want to deploy to your cluster:
   
   

   Please note that the list of available instance types is updated based on what is selected in the Kubernetes field. Also, the list is not filtered based on the region of the cluster.

   Qovery does not currently support all the instance types provided by each cloud provider. For more information, see What are the different instance types available when creating a cluster?

   Instance type selection from your Qovery Console has direct consequences on your cloud provider’s bill. While Qovery allows you to switch to a different instance type whenever you want, it is your sole responsibility to keep an eye on your infrastructure costs, especially when you want to upsize.

   For more information on the instance types provided by each cloud provider and their associated pricing, see What are the different instance types available when creating a cluster?

   Also, before downsizing, you need to ensure that your applications will still have enough resources to run correctly.

   • (Optional) Instance type selection helper: click this toggle if you need help to pick the best instance type for your needs. This allows you to input the desired CPU and/or RAM per worker node on your cluster, and the Instance type field value is updated accordingly.

   • Node disk size (GB): enter the disk capacity you want to allocate to your worker node (meaning how much data, in gigabytes, you want your worker node to be able to hold).

   At the bottom of the window, you can see an estimate of the cost associated with the selected instance type.

   To confirm, click Next.

6. In the Set SSH Key window:

   

   Enter a public SSH key and click Create.

   The SSH key enables you (or Qovery on your behalf) to freely manage your cluster. For information on how to generate an SSH key, see Generating an SSH Key for Your Cluster.

   You can add an SSH key to your cluster settings later, however it is recommended to do it at cluster creation to avoid downtime.

7. In the Ready to install your cluster window, check that the services needed to install your cluster are correct, and click Install:

   

   A pop-up window opens to confirm that your cluster is installing.

   Your cluster is now displayed in your organization settings, featuring the Installing... status (orange status). Once your cluster is properly installed, its status turns to green.

How was it? Did this tutorial work?  Yes  No

Creating an EKS Cluster (Multiple Node Cluster)

To create an EKS (Kubernetes Managed) cluster:

1. Open your Qovery Console.

2. On the top right hand-side of the screen, click the cogwheel icon to access your Organization settings:

   

3. Click Add Cluster:

   

4. In the Create Cluster window:

   

   • Enter cluster name: enter the name of your choice for your cluster.
   • Production cluster: select this option if your cluster will be used for production.
   • Cloud provider: select your cloud provider.
   • Region: select the geographical area in which you want your cluster to be hosted.
   • Credentials: select the select the credentials generated on your cloud provider account.
   
   

   If this is the first time you are using these credentials on your Qovery Console, click the Credentials field, and select New Credentials to register them.

   To confirm, click Next.

5. In the Set Resources window:

   

   • Kubernetes: select EKS (Multiple node cluster.
   • Instance type: select the type of worker nodes you want to deploy to your cluster:
   
   

   Please note that the list of available instance types is updated based on what is selected in the Kubernetes field. Also, the list is not filtered based on the region of the cluster.

   Qovery does not currently support all the instance types provided by each cloud provider. For more information, see What are the different instance types available when creating a cluster?

   Instance type selection from your Qovery Console has direct consequences on your cloud provider’s bill. While Qovery allows you to switch to a different instance type whenever you want, it is your sole responsibility to keep an eye on your infrastructure costs, especially when you want to upsize.

   For more information on the instance types provided by each cloud provider and their associated pricing, see What are the different instance types available when creating a cluster?

   Also, before downsizing, you need to ensure that your applications will still have enough resources to run correctly.

   • (Optional) Instance type selection helper: click this toggle if you need help to pick the best instance type for your needs. This allows you to input the desired CPU and/or RAM per worker node on your cluster, and the Instance type field value is updated accordingly.

   • Node disk size (GB): enter the disk capacity you want to allocate to your worker nodes (meaning how much data, in gigabytes, you want your worker nodes to be able to hold).

   At the bottom of the window, you can see an estimate of the cost associated with the selected instance type.

   • Node: on the scale, you can define the range of worker nodes you want to deploy to your cluster.
   
   

   The lowest number is the number of worker nodes running on your infrastructure at any time, while the highest number is the maximum number of worker nodes that can automatically be deployed as traffic grows.

   Please note that a minimum of 3 worker nodes is required to deploy your EKS cluster.

   At the bottom of the window, you can see an estimate of the cost associated with the selected instance type.

   To confirm, click Next.

6. (Optional) In the Features window, select the features you want to enable on your cluster and click Create:

   

   For more information, see Features.

7. In the Ready to install your cluster window, check that the services needed to install your cluster are correct, and click Install:

   

   A pop-up window opens to confirm that your cluster is installing.

   Your cluster is now displayed in your organization settings, featuring the Installing... status (orange status). Once your cluster is properly installed, its status turns to green.

How was it? Did this tutorial work?  Yes  No

Managing your Cluster Settings

To manage the settings of an existing cluster:

1. Open your Qovery Console.

2. On the top right hand-side of the screen, click the cogwheel icon to access your Organization settings:

   

3. In the Organization settings menu, click Clusters:

   

4. To view your cluster options, click ...:

   

5. In the dropdown menu, click Settings:

   

   The cluster settings window opens.

How was it? Did this tutorial work?  Yes  No

General Information

The General Information tab allows you to define high-level information on your cluster:

Item	Description
Cluster Name	To enter or edit the name of your cluster.
Production Cluster	To enter or edit the production flag of your cluster.
Description	To enter or edit the description of your cluster.
Cloud Provider	(View-only, defined at cluster creation) To check which cloud provider your cluster is hosted by.
Region	(View-only, defined at cluster creation) To check which geographical location your cluster is hosted in.

Credentials

To allow Qovery to quickly deploy your applications, you need to install it on your cloud provider account. To do so:

• as an AWS user, see Connect your AWS account.
• as a Digital Ocean (DO) user, see Connect your Digital Ocean account.
• as a Scaleway user, see Connect your Scaleway account.

You then need to finalize the connection between Qovery and your cloud provider account from the Qovery Console. To do so:

1. In your cluster settings, access the Credentials tab and click Edit:

   

   The Edit Credentials window opens:

   

2. In the Name field, enter a name for your credentials.

3. In the two dedicated fields, enter the credentials you created on your cloud provider account:

   Account Provider	Field Labels
   AWS	Access Key and Secret Access Key
   DigitalOcean	Spaces Access Key and Spaces Secret Key
   Scaleway	Scaleway Access Key and Scaleway Project ID

4. Click Save.

   Qovery is now connected to your cloud provider account.

How was it? Did this tutorial work?  Yes  No

Resources

Qovery allows you to define the resources you want to allocate to your cluster. To do so:

1. In your cluster settings, access the Resources tab:

   

2. In the Instance type dropdown menu, select the type of worker node(s) you want to deploy to your cluster:

   

   If your cluster is an EKS cluster, the selected instance type applies to all its worker nodes.

   Also, please note that the list of available instance types is not filtered based on the region of the cluster.

   Qovery does not currently support all the instance types provided by each cloud provider. For more information, see What are the different instance types available when creating a cluster?

   Instance type selection from your Qovery Console has direct consequences on your cloud provider’s bill. While Qovery allows you to switch to a different instance type whenever you want, it is your sole responsibility to keep an eye on your infrastructure costs, especially when you want to upsize.

   For more information on the instance types provided by each cloud provider and their associated pricing, see What are the different instance types available when creating a cluster?

   Also, before downsizing, you need to ensure that your applications will still have enough resources to run correctly.

3. (Optional) Click the Instance type selection helper toggle if you need help to pick the best instance type for your needs. This allows you to input the desired CPU and/or RAM per worker node on your cluster, and the Instance type field value is updated accordingly:

   

4. (AWS users only) In the Node disk size (GB) field, enter the disk capacity you want to allocate to your worker node(s) (meaning how much data, in gigabytes, you want each worker node to be able to hold).

5. (EKS users only) On the Node scale, define the range of worker nodes you want to deploy to your cluster.

   The lowest number is the number of worker nodes running on your infrastructure at any time, while the highest number is the maximum number of worker nodes that can automatically be deployed as traffic grows.

   Please note that a minimum of 3 worker nodes is required to deploy your EKS cluster.

   K3s clusters can only have one node.

6. Click Save.

How was it? Did this tutorial work?  Yes  No

Features

The Features tab in your cluster settings allows you to check if the Static IP and Custom VPC subnet features are enabled on your cluster.

Static IP

The Static IP feature is currently only available to AWS users. It can only be enabled at cluster creation.

By default, when your cluster is created, its worker nodes are allocated public IP addresses, which are used for external communication. For improved security and control, the Static IP feature allows you to ensure that outbound traffic from your cluster uses specific IP addresses.

If you work in a sensitive business area such as financial technology, enabling the Static IP feature can help fulfill the security requirements of some of the external services you use, therefore making it easier for you to get whitelisted by them.

Custom VPC Subnet

The Custom VPC Subnet feature is currently only available to AWS users. It can only be enabled at cluster creation.

Virtual Private Cloud (VPC) peering allows you to set up a connection between your Qovery VPC and another VPC on your AWS account. This way, you can access resources stored on your AWS VPC directly from your Qovery applications.

A VPC can only be used if it has at least one range of IP addresses called a subnet. When you create a cluster, Qovery automatically picks a default subnet for it. However, to perform VPC peering, you may want to define which specific VPC subnet you want to use, so that you can avoid any conflicting settings. To do so, you can enable the Custom VPC Subnet feature on your cluster. For more information on how to set up VPC peering, see our dedicated tutorial.

Network

The Network tab in your cluster settings allows you to update your Qovery VPC route table so that you can perform VPC peering. For step-by-step guidelines on how to set up VPC peering, see our dedicated tutorial.

Performing Actions on your Clusters

Qovery allows you to update, stop, restart or delete your clusters at organization level.

Action	Description
Updating a cluster	To redeploy your cluster after a change has been made to it.
Stopping a cluster	To temporarily stop your cluster. Some services you have subscribed to via your cloud provider may still be active and incur costs when your cluster is stopped. For more information, see Stopping a cluster.
Restarting a cluster	To restart your cluster after it has been temporarily stopped.
Deleting a cluster	To delete your cluster. This is final and needs to be done properly to ensure all the services deployed by Qovery on your cloud provider's account are disabled, with no leftover cloud-related costs. For more information, see Deleting a cluster.

To access these actions:

1. Open your Qovery Console.

2. On the top right hand-side of the screen, click the cogwheel icon to access your Organization settings:

   

3. In the Organization settings menu, click Clusters:

   

4. To view your cluster options, click ...:

   

   A dropdown menu unfolds, featuring all the actions available on your cluster.

How was it? Did this tutorial work?  Yes  No

Updating a Cluster

To update a cluster so that it is redeployed with all the changes made to it:

1. Access your cluster options.

2. In the dropdown menu, click Update:

   

   A confirmation pop-up window opens.

3. In the dedicated field, enter the name of your cluster:

   

4. Click Update.

   Your cluster update is launched, and the status of your cluster turns to Updating... (orange status).

   Once the update is complete, the status dot next to your cluster turns to green.

How was it? Did this tutorial work?  Yes  No

Stopping a Cluster

Qovery allows you to temporarily stop your cluster instead of deleting it.

When you stop a cluster from the Qovery console, only the workers nodes managed by Qovery are stopped. If you have subscribed to services via your cloud provider (load balancing, storage system, or any other managed services), they will remain active and you will be charged for them. For more information, please contact your cloud provider. To permanently delete a cluster and all its associated costs, see Deleting a Cluster.

To temporarily stop a cluster:

1. Access your cluster options.

2. In the dropdown menu, click Stop:

   

   A confirmation pop-up window opens.

3. In the dedicated field, enter the name of your cluster:

   

4. Click Stop.

   Your cluster is being stopped, and its status turns to Pausing... (orange status).

   Once the stop is complete, the status dot next to your cluster turns to grey, and the status of your cluster turns to Paused (gray status).

How was it? Did this tutorial work?  Yes  No

Restarting a Cluster

To restart a cluster after it has been temporarily stopped:

1. Access your cluster options.

2. In the dropdown menu, click Resume:

   

   A confirmation pop-up window opens.

3. In the dedicated field, enter the name of your cluster:

   

4. Click Update.

   Your cluster is launched again, and the status of your cluster turns to Updating... (orange status).

   Once your cluster has restarted, the status dot next to your cluster turns to green.

How was it? Did this tutorial work?  Yes  No

Deleting a Cluster

Deleting a cluster from the Qovery console is final, and cuts all associated costs on your cloud provider's end. To only temporarily stop a cluster, see Stopping a Cluster.

To delete a cluster:

1. Access your cluster options.

2. In the dropdown menu, click Remove cluster:

   

   A confirmation pop-up window opens.

3. In the dedicated field, enter the name of your cluster:

   

4. Click Delete.

   Your cluster is being deleted, and its status turns to Deleting... (red status).

   Once the deletion is complete, the cluster is removed from your organization settings.

How was it? Did this tutorial work?  Yes  No

Cleaning up a Cluster from your AWS Account

The following troubleshooting procedure is intended for AWS users who did not properly delete their cluster before revoking Qovery's access to their platform.

To properly delete your clusters and avoid any unexpected issues or costs, see Deleting a Cluster.

To clean up a Qovery cluster from your cloud provider account, go to AWS Console>Services>Management & Governance>Resource Groups & Tag Editor> Create Resource Group:

Step	Description
1	In the Group type area, select Tag based.
2	In the Tags field of the Grouping criteria area, enter ClusterId.
3	Click Add.
4	Click Preview Resources. All your Qovery clusters are now displayed in the Group resources table, and you can delete them by hand.

Logs

Qovery allows you to access the logs of your cluster in order to follow its installation or investigate any issue happening on it.

To access the logs you need to open the cluster, click ...:

A new windows is opened, displaying the logs of the cluster.

The tab system on the right allows you to access the cluster information and, if an error occurred, the detail of the error.

The error message should provide you enough information to solve the issue. If that's not the case, feel free to ask for support on our forum or discord channel

Generating an SSH Key for Your Cluster

You need a public SSH key for your K3s clusters only.

To allow Qovery or yourself to connect remotely to your K3s instance and manage it, you need to generate an SSH key and add it to your cluster settings. To do so:

1. On your computer, open a terminal.

2. Run ssh-keygen -t, followed by the key type and an optional comment.

   This comment is included in the .pub file that is created. You may want to use an email address for the comment.

   For example, you can enter ssh-keygen -t rsa -b 2048 -C "<comment>".

3. Press Enter.

   You should get an output similar to:

   {
     Generating public/private ed25519 key pair.
     Enter file in which to save the key (/home/user/.ssh/id_ed25519):
   }

4. Accept the suggested filename and directory, unless you want to save your SSH key in a specific directory where you store other keys.

5. Enter a passphrase:

   {
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
   }

   A confirmation is displayed, including information about where your files are stored.

6. You can add the generated public SSH key at cluster creation (see Creating a Cluster), or later from your cluster settings.

   To do so, on your Qovery Console, access your cluster options and click Settings:

   

7. In the Remote Access tab, enter your SSH key and click Save:

   

   Your SSH key is now linked to your cluster.

How was it? Did this tutorial work?  Yes  No