Clusters & Environments

Introduction

Devtron allows you to connect and manage your existing Kubernetes clusters by adding them to its platform. Once a cluster is added, you can create different environments within it, making it possible to deploy your applications.

Go to Global ConfigurationsClusters & EnvironmentsAdd Cluster (button)

Figure 1: Adding a Cluster

You can add any of the following cluster types:

Figure 2: Choosing Cluster Type

Add Kubernetes Cluster

Who Can Perform This Action?

On the Add Cluster screen, select Connect Cluster.

Figure 3: Selecting 'Connect Cluster'

You can choose to add your Kubernetes cluster using either of the following methods:

Figure 4: Choosing a Method

Add Cluster Using Server URL & Bearer Token

Note

Refer to Get Cluster Credentials to learn the process of getting the Server URL and bearer token.

  1. To add a Kubernetes cluster on Devtron using Server URL and Bearer Token, provide the following information:

Field
Description

Name

Enter the name of your cluster.

Server URL

Enter the Server URL of your cluster (with https) Note: We recommend using a self-hosted URL instead of a cloud-hosted URL.

Bearer Token

Paste the bearer token of your cluster

Figure 5: Enter Cluster Credentials
  1. Complete the remaining steps (optional):

Tip

If you have a kubeconfig file ready, you may skip the above process and refer to Add Cluster Using Kubeconfig instead.

Add Cluster Using Kubeconfig

In case you prefer to add clusters using kubeconfig, follow these steps:

  1. Copy and paste your kubeconfig file into the editor. Alternatively, you may browse and select the file as well.

Figure 6: Choosing Kubeconfig Option
  1. Click the Get Cluster button. This action will display the cluster details alongside the kubeconfig.

Figure 7: Get Cluster List from Kubeconfig
  1. If your kubeconfig file lists multiple clusters, they will be displayed in the window. Use the checkboxes to select the desired cluster(s) and click Save.

Figure 8: Clicking Save
  1. Click the saved cluster, and complete the remaining steps (optional):

Note

Assign Category to a Cluster

Devtron allows you to assign a category (for e.g. Prod, QA, Dev, or Stage) to your clusters. This enables category-based filtering in the UI, allowing you to determine whether an application is deployed to the Prod, QA, Dev, or Stage environment.

Before assigning a category, you must first add the category. To add a category, refer to the Adding a Category section to learn more.

To assign a category to a cluster, follow the steps below:

  1. Select a category from the dropdown under Assign Category and click Update Cluster.

    Figure 9: Assigning Category
  2. The selected category will be assigned to the cluster.

    Figure 10: Category Assigned

Choose Method of Connection

When adding a new cluster to Devtron, you must choose how Devtron will connect to it. There are three connection options available:

Direct Connection

Clusters with a directly accessible API server endpoint—either publicly or via private peering—can be added as Direct Connection clusters.

  • Devtron connects directly without an intermediary.

  • Recommended when the cluster is publicly accessible or has a direct network route from Devtron.

Figure 11: Choosing Direct Connection

Via Proxy

For security reasons, some Kubernetes clusters are deployed behind a proxy. In this setup, Devtron routes all communication through the specified proxy URL.

  • Use this option when network restrictions require traffic to go through a proxy server.

  • Requires specifying a Proxy URL (e.g., http://proxy.example.org:3128).

  • Limitation: Deployments via GitOps (ArgoCD) are not recommended for clusters connected via proxy.

Figure 12: Choosing 'Via Proxy'

Via SSH Tunnel

When a direct connection isn't possible, Devtron can connect to the Kubernetes cluster through an SSH tunnel, ensuring secure and encrypted communication.

  • Requires:

    • SSH Server URL (e.g., http://proxy.example.org).

    • Username for authentication.

    • Authentication Method:

      • Password

      • SSH Private Key

      • Both Password & SSH Private Key

  • Limitation: Deployments via GitOps (ArgoCD) are not recommended for clusters connected via SSH Tunnel.

Figure 13: Choosing 'Via SSH Tunnel'

Use Secure TLS Connection

For a secure cluster connection, you can opt for TLS connection, where you need to provide Certificate Authority Data, a TLS Key, and a TLS Certificate.

If your cluster is managed (e.g., EKS, AKS, GKE), you might need to download these certificates from your cloud provider’s dashboard or API.

Field
Description

Certificate Authority (CA) Data

The CA certificate (see: example) used to verify the Kubernetes API server’s identity.

TLS Key

The private key associated with the client certificate for authentication.

TLS Certificate

The client certificate used to authenticate with the Kubernetes API server.

Figure 14: Using Secure TLS Connection

Configure Prometheus (Enable Application Metrics)

If you want to see application metrics against the applications deployed in the cluster, Prometheus must be deployed in the cluster. Prometheus is a powerful tool to provide graphical insight into your application behavior.

Enable application metrics to configure Prometheus as shown below. In case it is not available, make sure to install the Monitoring (Grafana) integration from Devtron Stack Manager to configure Prometheus.

Figure 15: Enabling Application Metrics

Provide the information in the following fields:

Field
Description

Prometheus endpoint

Provide the URL of your Prometheus

Authentication Type

Prometheus supports two authentication types:

  • Basic: If you select the Basic authentication type, then you must provide the Username and Password of Prometheus for authentication.

  • Anonymous: If you select the Anonymous authentication type, then you do not need to provide the Username and Password. Note: The fields Username and Password will not be available by default.

TLS Key & TLS Certificate

These fields are optional and can be used when you use a customized URL.

Click Save Cluster to save your cluster on Devtron.


Add Isolated Cluster

Who Can Perform This Action?

For air-gapped Kubernetes clusters with restricted inbound and outbound traffic, Devtron enables seamless management using isolated clusters. While these are not actual clusters with API endpoints, they provide a convenient way to deploy applications in such environments.

  1. On the Add Cluster screen, select Add Kubernetes Cluster.

Figure 16: Selecting Isolated Cluster
  1. Add a cluster name (e.g. banking-airgapped-cluster) and click Save Cluster.

Figure 17: Saving Isolated Cluster

You have successfully configured an isolated cluster.

Figure 18: New Isolated Cluster

Note

When you deploy to an isolated environment, Devtron automatically packages application manifests and images into a Helm chart. You can then either:

  • Download and install manually in a fully air-gapped setup.

  • Push it to an OCI registry (provided pushing of helm package is enabled), allowing manifests to be pulled manually or automatically via Devtron on an air-gapped cluster (if pull access to the OCI registry is available).


Add Environment to a Cluster

Who Can Perform This Action?

  1. Whether it is a Kubernetes Cluster or Isolated Cluster, a newly created cluster initially has no environments, so click Add Environment.

Figure 19: Adding an Environment
  1. Fill the following details within the Add Environment modal window.

Field
Description

Environment Name

Enter a name for your environment.

Enter Namespace

Enter a namespace corresponding to your environment. Note: If this namespace does not exist in your cluster, Devtron will create it. If it already exists, Devtron will map the environment to it.

Environment Type

Select your environment type:

  • Production

  • Non-production

Note: Devtron shows deployment metrics (DORA metrics) for environments tagged as Production only.

Figure 20: Saving an Environment
  1. Assign a Category to environment - Devtron allows you to assign a category (for e.g. Prod, QA, Dev, or Stage) to your environments. This enables category-based filtering in the UI, allowing you to determine whether an application is deployed to Prod, QA, Dev, or Stage environment. To assign a category to your environment, follow the steps below:

    1. Select a category from the dropdown under Assign Category and click Update.

    Figure 21: Assigning Category
    1. The selected category will be assigned to the environment.

    Figure 22: Category Assigned

Note: Before assigning a category, you must first add the category. To add a category, refer to Adding a Category section to learn more.

  1. Add/Edit labels to namespace - You can attach labels to your specified namespace in the Kubernetes cluster. Using labels will help you filter and identify resources via CLI or other Kubernetes tools. Click here to know more about labels.

Figure 23: Adding Labels to Namespace
  1. Click Save. Your new environment will be visible in your cluster as shown below.

Figure 24: Newly Created Environment in the Cluster

Edit Environment

Who Can Perform This Action?

You can also make edits to an existing environment if needed by clicking the edit icon.

Figure 25: Editing Environment in the Cluster
Feature
Editable?

Production/Non-Production Option

✅ Yes

Description

✅ Yes

Labels for Namespace

✅ Yes

Assign a category

✅ Yes

Environment Name

❌ No

Namespace Name

❌ No

Click Update to save your changes.

Figure 26: Updating Environment in the Cluster

Delete Environment

Who Can Perform This Action?

If an environment is no longer needed, you can delete it by following these steps:

  1. Click the delete icon for the environment you wish to remove.

Figure 27: Deleting Environment

Important

  1. A confirmation dialog will appear. Click Confirm to permanently delete the environment.

    Figure 28: Confirming Environment Deletion

Add Category

Before assigning a category, you must first add the category. To add a category, follow the steps below:

  1. Go to Global Configurations.

    Figure 29: Navigating to Global Configurations
  2. Select Clusters and Environments and click Manage Categories, a modal window will open.

    Figure 30: Clicking Manage Categories
  3. Enter the name of the category in the CATEGORIES field and provide a description in the DESCRIPTION field.

Note:

  • The category name must be unique and cannot be changed once defined. It should be a minimum of 3 characters.

  • It can contain alphanumeric characters, but cannot start with a number.

  • The name should be in lowercase only.

Figure 31: Adding Category
  1. If you wish to add more categories, click Add Category, a new row will appear, enter the name and description of the new category.

    Figure 32: Adding More Categories
  2. Click Update and your categories will be added.

    Figure 33: Categories Added

Delete Category

To delete a category, follow the steps below:

  1. Go to Global Configurations.

    Figure 34: Navigating to Global Configurations
  2. Select Clusters and Environments and click Manage Categories, a modal window will open.

    Figure 35: Clicking Manage Categories
  3. Select the x icon next to the categories you want to delete.

    Note: You cannot delete a category if it is assigned to a cluster or environment.

Figure 36: Clicking 'x' icon
  1. Click Update to delete the categories.


Extras

Get Cluster Credentials

Prerequisite

kubectl must be installed on the bastion.

Note

We recommend using a self-hosted URL instead of a cloud-hosted URL. Refer to the benefits of a self-hosted URL.

You can get the Server URL and Bearer Token by running the following command, depending on the cluster provider:

If you are using EKS, AKS, GKE, Kops, Digital Ocean managed Kubernetes, run the following command to generate the server URL and bearer token:

curl -O https://raw.githubusercontent.com/devtron-labs/utilities/main/kubeconfig-exporter/kubernetes_export_sa.sh && bash kubernetes_export_sa.sh cd-user  devtroncd
Figure 34: Generating Cluster Credentials

Benefits of Self-hosted URL

  • Disaster Recovery:

    • You cannot edit the server URL of a cloud-specific provider. If you're using an EKS URL (e.g. *****.eu-west-1.elb.amazonaws.com), it will be a tedious task to add a new cluster and migrate all the services one by one.

    • But in case of using a self-hosted URL (e.g. clear.example.com), you can just point to the new cluster's server URL in DNS manager and update the new cluster token and sync all the deployments.

  • Easy Cluster Migrations:

    • In case of managed Kubernetes clusters (like EKS, AKS, GKE etc) which is a cloud provider specific, migrating your cluster from one provider to another will result in waste of time and effort.

    • On the other hand, migration for a self-hosted URL is easy, as the URL belongs to a single hosted domain independent of the cloud provider.

Last updated

Was this helpful?