Clusters & Environments
Last updated
Was this helpful?
Last updated
Was this helpful?
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 Configurations → Clusters & Environments → Add Cluster (button)
You can add any of the following cluster types:
Kubernetes Cluster - If you have access to the cluster, use this option.
Isolated Cluster - For airgapped-related use-cases, use this option.
Users need to have super-admin permission to add a Kubernetes cluster to Devtron.
On the Add Cluster screen, select Add Kubernetes Cluster.
You can choose to add your Kubernetes cluster using either of the following methods:
Refer Get Cluster Credentials to learn the process of getting Server URL and bearer token.
To add a Kubernetes cluster on Devtron using Server URL and Bearer Token, provide the following information:
Name
Enter the name of your cluster.
Server URL
Bearer Token
Paste the bearer token of your cluster
complete the remaining steps (optional):
If you have a kubeconfig file ready, you may skip the above process and refer Add Cluster Using Kubeconfig instead.
In case you prefer to add clusters using kubeconfig, follow these steps:
Copy and paste your kubeconfig file into the editor. Alternatively, you may browse and select the file as well.
Click the Get Cluster button. This action will display the cluster details alongside the kubeconfig.
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.
Click the saved cluster, and complete the remaining steps (optional):
Ensure that the kubeconfig file has admin permissions. It is crucial for Devtron to have the necessary administrative privileges; otherwise, it may encounter failures or disruptions during deployments and other operations. Admin permission is essential to ensure the smooth functioning of Devtron and to prevent any potential issues that may arise due to insufficient privileges.
When adding a new cluster to Devtron, you must choose how Devtron will connect to it. There are three connection options available:
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.
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.
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.
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.
Certificate Authority (CA) Data
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.
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.
Provide the information in the following fields:
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.
Users need to have super-admin permission to add an isolated/airgapped cluster to Devtron.
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.
On the Add Cluster screen, select Add Kubernetes Cluster.
Add a cluster name (e.g. banking-airgapped-cluster) and click Save Cluster.
You have successfully configured an isolated cluster.
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 air-gapped cluster (if pull access to the OCI registry is available).
Users need to have super-admin permission to add an environment to a cluster.
Whether it is a Kubernetes Cluster or Isolated Cluster, a newly created cluster initially has no environments, so click Add Environment.
Fill the following details within the Add Environment modal window.
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.
Click Save. Your new environment will be visible in your cluster as shown below.
Users need to have super-admin permission to edit an environment in a cluster.
You can also make edits to an existing environment if need be by clicking the edit icon.
Production/Non-Production Option
✅ Yes
Description
✅ Yes
Labels for Namespace
✅ Yes
Environment Name
❌ No
Namespace Name
❌ No
Click Update to save your changes.
Users need to have super-admin permission to delete an environment from a cluster.
If an environment is no longer needed, you can delete it by following these steps:
Click the delete icon for the environment you wish to remove.
Environment deletion is not allowed if any application has a CD pipeline corresponding to the environment. In such a case, go to Workflow Editor and delete the deployment pipeline first, and then return to delete the environment. This action is irreversible, so make sure no critical applications or resources depend on the environment before deleting.
A confirmation dialog will appear. Click Confirm to permanently delete the environment.
kubectl must be installed on the bastion.
We recommend using a self-hosted URL instead of a cloud-hosted URL. Refer 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:
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.
Enter the Server URL of your cluster (with https) Note: We recommend using a instead of cloud hosted URL.
The CA certificate (see: ) used to verify the Kubernetes API server’s identity.
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.
