Host URL is the domain address at which your devtron dashboard can be reached.

Add Host URL

To add host URL, go to the Host URL section of Global Configurations.

On the Host URL page:

• Enter the host URL in the Host URL field.

• Or, you can select auto-detect from your browser.

• Next, click Update.

You can add your existing Kubernetes clusters and environments on the Clusters and Environments section. You must have a super admin access to add a cluster.

Add Cluster:

To add cluster, go to the Clusters & Environments section of Global Configurations. Click Add cluster.

Add Clusters Using Server URL & Bearer Token

To add a Kubernetes cluster on Devtron using server url and the bearer token, provide the information in the following fields:

Get Cluster Credentials

Prerequisites: kubectl must be installed on the bastion.

Note: We recommend to use a self-hosted URL instead of cloud hosted URL. Refer the benefits of self-hosted URL.

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

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

curl -O https://raw.githubusercontent.com/devtron-labs/utilities/main/kubeconfig-exporter/kubernetes_export_sa.sh && sed -i 's/kubectl/microk8s kubectl/g' \
kubernetes_export_sa.sh && bash kubernetes_export_sa.sh cd-user \
devtroncd

Benefits of Self-hosted URL

• Disaster Recovery:

  • It is not possible to 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 is of single hosted domain independent of the cloud provider.

Add Clusters Using Kubeconfig

To add clusters using kubeconfig, follow these steps:

1. First, navigate to the global configurations menu, and then go to "clusters and environment" section.

2. Click on the Add cluster button. In the options provided, choose the From kubeconfig option.

3. Next, either paste the kubeconfig file or browse for it and select the appropriate file.

4. Afterward, click on the Get cluster button. This action will display the cluster details alongside the kubeconfig.

1. Select the desired cluster and click on Save to successfully add the cluster to Devtron.

Note: Please ensure that the kubeconfig file you use 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.

Configure Prometheus (Enable Applications 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.

Note: Make sure that you install Monitoring (Grafana) from the Devtron Stack Manager to configure prometheus. If you do not install Monitoring (Grafana), then the option to configure prometheus will not be available.

Enable the application metrics to configure prometheus and provide the information in the following fields:

Now, click Save Cluster to save your cluster on Devtron.

Installing Devtron Agent

Your Kubernetes cluster gets mapped with Devtron when you save the cluster configurations. Now, the Devtron agent must be installed on the added cluster so that you can deploy your applications on that cluster.

When the Devtron agent starts installing, click Details to check the installation status.

A new window pops up displaying all the details about the Devtron agent.

Add Environment

Once you have added your cluster in the Clusters & Environments, you can add the environment by clicking Add environment.

A new environment window pops up.

Click Save and your environment will be created.

Update Environment

• You can also update an environment by clicking the environment.

• You can change Production and Non-Production options only.

• You cannot change the Environment Name and Namespace Name.

• Make sure to click Update to update your environment.

Introduction

In Devtron, you can either use Helm or GitOps (Argo CD) to deploy your applications and charts. GitOps is a branch of DevOps that focuses on using Git repositories to manage infrastructure and application code deployments.

If you use the GitOps approach, Devtron will store Kubernetes configuration files and the desired state of your applications in Git repositories.

Steps to Configure GitOps

1. Go to Global Configurations → GitOps
2. Select any one of the supported Git providers to configure GitOps.

1. Fill all the mandatory fields. Refer supported Git providers to know more about the respective fields.
2. In the Directory Management in Git section, you get the following options:

   • Use default git repository structure:

     This option lets Devtron automatically create a GitOps repository within your organization. The repository name will match your application name, and it cannot be changed. Since Devtron needs admin access to create the repository, ensure the Git credentials you provided in Step 3 have administrator rights.

   • Allow changing git repository for application:

     Select this option if you wish to use your own GitOps repo. This is ideal if there are any confidentiality/security concerns that prevent you from giving us admin access. Therefore, the onus is on you to create a GitOps repo with your Git provider, and then add it to the specific application on Devtron. Make sure the Git credentials you provided in Step 3 have at least read/write access. Choosing this option will unlock a GitOps Configuration page under the App Configuration tab.
3. Click Save/Update. A green tick will appear on the active Git provider.

Feature Flag

Alternatively, you may use the feature flag FEATURE_USER_DEFINED_GITOPS_REPO_ENABLE to enable or disable custom GitOps repo.

How to Use Feature Flag

1. Go to Devtron's Resource Browser.

2. Select the cluster where Devtron is running, i.e., default_cluster.

3. Go to the Config & Storage dropdown on the left.

4. Click ConfigMap.

5. Use the namespace filter (located on the right-hand side) to select devtroncd namespace. Therefore, it will show only the ConfigMaps related to Devtron, and filter out the rest.

6. Find the ConfigMap meant for the dashboard of your Devtron instance, i.e., dashboard-cm (with an optional suffix).

7. Click Edit Live Manifest.

8. Add the feature flag (with the intended boolean value) within the data dictionary

9. Click Apply Changes.

Supported Git Providers

Below are the Git providers supported in Devtron for storing configuration files.

• GitHub

• GitLab

• Azure

• Bitbucket

GitHub

Fill the following mandatory fields:

GitLab

Fill the following mandatory fields:

Azure

Fill the following mandatory fields:

Bitbucket

Here, you get 2 options:

• Bitbucket Cloud - Select this if you wish to store GitOps configuration in a web-based Git repository hosting service offered by Bitbucket.

• Bitbucket Data Center - Select this if you wish to store GitOps configuration in a git repository hosted on a self-managed Bitbucket Data Center (on-prem).

Bitbucket Cloud

Fill the following mandatory fields:

Bitbucket Data Center

Fill the following mandatory fields:

Miscellaneous

Creating Organization in GitHub

1. Create a new account on GitHub (if you do not have one).

2. On the upper-right corner of your GitHub page, click your profile photo, then click Settings.

3. On the Access section, click Organizations.

4. On the Organizations section, click New organization.

5. Pick a plan for your organization. You have the option to select create free organization also.

6. On the Set up your organization page,

   • Enter the organization account name, contact email.

   • Select the option your organization belongs to.

   • Verify your account and click Next.

   • Your GitHub organization name will be created.

7. Go to your profile and click Your organizations to view all the organizations you created.

For more information about the plans available for your team, see GitHub's products. You can also refer GitHub organization official doc page for more detail.

Note:

• repo - Full control of private repositories (able to access commit status, deployment status, and public repositories).

• admin:org - Full control of organizations and teams (Read and write access).

• delete_repo - Grants delete repo access on private repositories.

Creating Group in GitLab

1. Create a new account on GitLab (if you do not have one).

2. You can create a group by going to the 'Groups' tab on the GitLab dashboard and click New group.

3. Select Create group.

4. Enter the group name (required) and select the optional descriptions if required, and click Create group.

5. Your group will be created and your group name will be assigned with a new Group ID (e.g. 61512475).

Note:

• api - Grants complete read/write access to the scoped project API.

• write_repository - Allows read/write access (pull, push) to the repository.

Creating Project in Azure DevOps

1. Go to Azure DevOps and navigate to Projects.

2. Select your organization and click New project.

3. On the Create new project page,

   • Enter the project name and description of the project.

   • Select the visibility option (private or public), initial source control type, and work item process.

   • Click Create.

   • Azure DevOps displays the project welcome page with the project name.

You can also refer Azure DevOps - Project Creation official page for more details.

Note:

• code - Grants the ability to read source code and metadata about commits, change sets, branches, and other version control artifacts. More information on scopes in Azure DevOps.

Creating Workspace in Bitbucket

1. Create a new individual account on Bitbucket (if you do not have one).

2. Select your profile and settings avatar on the upper-right corner of the top navigation bar.

3. Select All workspaces from the dropdown menu.

4. Select the Create workspace on the upper-right corner of the Workspaces page.

5. On the Create a Workspace page:

• Enter a Workspace name.

• Enter a Workspace ID. Your ID cannot have any spaces or special characters, but numbers and capital letters are fine. This ID becomes part of the URL for the workspace and anywhere else where there is a label that identifies the team (APIs, permission groups, OAuth, etc.).

• Click Create.

1. Your Workspace name and Workspace ID will be created.

You can also refer official Bitbucket Workspace page for more details.

Note:

• repo - Full control of repositories (Read, Write, Admin, Delete) access.

Git Accounts allow you to connect your code source with Devtron. You will be able to use these git accounts to build the code using the CI pipeline.

Add Git Account

To add git account, go to the Git accounts section of Global Configurations. Click Add git account.

Provide the information in the following fields to add your git account:

Update Git Account

To update the git account:

1. Click the git account which you want to update.

2. Update the required changes.

3. Click Update to save the changes.

Updates can only be made within one Authentication type or one protocol type, i.e. HTTPS (Anonymous or User Auth) & SSH. You can update from Anonymous to User Auth & vice versa, but not from Anonymous or User Auth to SSH and vice versa.

Note:

Projects are the logical grouping of your applications so that you can manage and control the access level of users.

Refer for more detail.

Add Project:

1. To add a project name, go to the Projects section of Global Configurations.

2. Click Add Project.

3. Provide a project name in the field and click Save.

A global configuration allows you to easily share common configuration between multiple repositories without copy/pasting it to these repositories.

Before you start creating an application, we recommend to provide basic information in different sections of Global Configurations available in Devtron.

You can also refer our YouTube video provided here.

While are typically used for storing built by the CI Pipeline, an OCI registry can store container images as well as other artifacts such as . In other words, all container registries are OCI registries, but not all OCI registries are container registries.

You can configure a container registry using any registry provider of your choice. It allows you to build, deploy, and manage your container images or charts with easy-to-use UI.

Add Container Registry

1. From the left sidebar, go to Global Configurations → Container/OCI Registry.
2. Click Add Registry.
3. Choose a provider from the Registry provider dropdown. View the .

4. Choose the Registry type:

   • Private Registry: Choose this if your images or artifacts are hosted or should be hosted on a private registry restricted to authenticated users of that registry. Selecting this option requires you to enter your registry credentials (username and password/token).

   • Public Registry: Unlike private registry, this doesn't require your registry credentials. Only the registry URL and repository name(s) would suffice.

5. Assuming your registry type is private, here are few of the common fields you can expect:

   Fields	Description

6. Click Save.

Supported Registry Providers

ECR

Amazon ECR is an AWS-managed container image registry service. The ECR provides resource-based permissions to the private repositories using AWS Identity and Access Management (IAM). ECR allows both Key-based and Role-based authentications.

Provide the following additional information apart from the common fields:

Docker

Provide the following additional information apart from the common fields:

Azure

Provide the following additional information apart from the common fields:

Artifact Registry (GCP)

Provide the following additional information apart from the common fields:

Google Container Registry (GCR)

Quay

Provide the following additional information apart from the common fields:

Other

Provide below information if you select the registry type as Other.

Registry Credential Access

Super-admin users can decide if they want to auto-inject registry credentials or use a secret to pull an image for deployment to environments on specific clusters.

1. To manage the access of registry credentials, click Manage.

There are two options to manage the access of registry credentials:

1. You can choose one of the two options for defining credentials:

Use Registry Credentials

If you select Use Registry Credentials, the clusters will be auto-injected with the registry credentials of your registry type. As an example, If you select Docker as Registry Type, then the clusters will be auto-injected with the username and password/token which you use on the Docker Hub account.

Click Save.

Specify Image Pull Secret

You can create a Secret by providing credentials on the command line.

Create this Secret and name it regcred (let's say):

where,

• namespace is your sub-cluster, e.g., devtron-demo

• your-registry-server is your Private Docker Registry FQDN. Use https://index.docker.io/v1/ for Docker Hub.

• your-name is your Docker username

• your-pword is your Docker password

• your-email is your Docker email

You have successfully set your Docker credentials in the cluster as a Secret called regcred.

Enter the Secret name in the field and click Save.

Authorization section describes how to authenticate and authorize access to resources, also managing role-based access levels in Devtron.

Access can be granted to a user via:

• SSO Login Services

• User Permissions

• Permission Groups

• API Tokens

You can add more chart repositories to Devtron. Once added, they will be available in the All Charts section of the Chart Store.

Note: After the successful installation of Devtron, click Refetch Charts to sync and download all the default charts listed on the dashboard.

Add Chart Repository

To add chart repository, go to the Chart Repositories section of Global Configurations. Click Add repository.

Note: Only public chart repositories can be connected as of now via Devtron.

Provide below information in the following fields:

Update Chart Repository

You can also update your saved chart repository settings.

1. Click the chart repository which you want to update.

2. Modify the required changes and click Update to save you changes.

Note:

• You can perform a dry run to validate the below chart repo configurations by clicking Validate.

• You can enable or disable your chart repository. If you enable it, then you will be able to see the enabled chart in All Charts section of the Chart Store.

Devtron includes predefined helm charts that cover the majority of use cases. For any use case not addressed by the default helm charts, you can upload your own helm chart and use it as a custom chart in Devtron.

• Who can upload a custom chart - Super admins

• Who can use the custom chart - All users

A super admin can upload multiple versions of a custom helm chart.

Prerequisites

1. A valid helm chart, which contains Chart.yaml file with name and version fields.

2. Image descriptor template file .image_descriptor_template.json.

3. Custom chart packaged in the *.tgz format.

1. How to create a helm chart

You can use the following command to create the Helm chart:

helm create my-custom-chart

Note: Chart.yaml is the metadata file that gets created when you create a helm chart.

Please see the following example:

2. Create the image descriptor template file .image_descriptor_template.json

It's a GO template file that should produce a valid JSON file upon rendering. This file is passed as the last argument in helm install -f myvalues.yaml -f override.yaml command.

Place the .image_descriptor_template.json file in the root directory of your chart.

You can use the following variables in the helm template (all the placeholders are optional):

The values from the CD deployment pipeline are injected at the placeholder specified in the .image_descriptor_template.json template file.

{
    "server": {
        "deployment": {
            "image_tag": "{{.Tag}}",
            "image": "{{.Name}}"
        }
    },
    "pipelineName": "{{.PipelineName}}",
    "releaseVersion": "{{.ReleaseVersion}}",
    "deploymentType": "{{.DeploymentType}}",
    "app": "{{.App}}",
    "env": "{{.Env}}",
    "appMetrics": {{.AppMetrics}}
}

For example:

To create a template file to allow Devtron to only render the repository name and the tag from the CI/CD pipeline that you created, edit the .image_descriptor_template.json file as:

Copy

{
    "image": {
          "repository": "{{.Name}}",
          "tag": "{{.Tag}}"
    }
}

3. Package the custom chart in the *.tgz format

Before you begin, ensure that your helm chart includes both Chart.yaml (with name and version fields) and .image_descriptor_template.json files.

The helm chart to be uploaded must be packaged as a versioned archive file in the format <helm-chart-name>-vx.x.x.tgz.

helm package my-custom-chart

The above command will create a my-custom-chart-0.1.0.tgz file.

Uploading a custom chart

A custom chart can only be uploaded by a super admin.

• On the Devtron dashboard, select Global Configurations > Custom charts.

• Select Import Chart.

• Select tar.gz file... and upload the packaged custom chart in the *.tgz format.

The chart is being uploaded and validated. You may also Cancel upload if required.

Validation

The uploaded archive will be validated against:

• Supported archive template should be in *.tgz format.

• Content of values.yaml should be there in app-values.yaml file.

• release-values.yaml file is required.

• ConfigMap/Secret template should be same as that of our reference chart.

• Chart.yaml must include the name and the version number.

• ..image_descriptor_template.json file should be present and the field format must match the format listed in the image builder template section.

The following are the validation results:

View the custom charts

All users can view the custom charts.

To view a list of available custom charts, go to Global Configurations > Custom charts page.

• The charts can be searched with their name, version, or description.

• New custom charts can be uploaded by selecting Upload chart.

Use the custom chart in an application

The custom charts can be used from the Deployment Template section.

Info:

The deployment strategy for a custom chart is fetched from the custom chart template and cannot be configured in the CD pipeline.

Sample Configuration

Values You Would Require at SSO Provider

Devtron provides a sample configuration out of the box. There are some values that you need to either get from your SSO provider or give to your SSO provider.

Values to Fetch

• clientID

• clientSecret

Values to Provide

• redirectURI (provided in SSO Login Services by Devtron)

Reference

• View Google Documentation

• View Dex IdP Documentation

Sample Configuration

Values You Would Require at SSO Provider

Devtron provides a sample configuration out of the box. There are some values that you need to either get from your SSO provider or give to your SSO provider.

Values to Fetch

• clientID
• clientSecret

Values to Provide

• redirectURI (already provided in SSO Login Services by Devtron)

Reference

Once Devtron is installed, it has a built-in admin user with super admin privileges with unrestricted access to all Devtron resources. We recommended to use a user with super admin privileges for initial and global configurations only and then switch to local users or configure SSO integration.

Only users with privileges can create SSO configuration. Devtron uses for authenticating a user against the identity provider.

To add/edit SSO configuration, go to the SSO Login Services section of Global Configurations.

Supported SSO Providers

Below are the SSO providers which are available in Devtron. Select one of the SSO providers (e.g., GitHub) to configure SSO:

Dex implements connectors that target specific identity providers for each connector configuration. You must have a created account for the corresponding identity provider and registered an app for client key and secret.

Refer the following documents for more detail.

• https://dexidp.io/docs/connectors/

• https://dexidp.io/docs/connectors/google/

1. Create new SSO Configuration

Make sure that you have a .

• Go to the Global Configurations → SSO Login Services and click any SSO Provider of your choice.

• In the URL field, enter the valid Devtron application URL where it is hosted.

• For providing redirectURI or callbackURI registered with the SSO provider, you can either select Configuration or Sample Script.

• Provide the client ID and client Secret of your SSO provider (e.g. If you select Google as SSO provider, then you must enter $GOOGLE_CLIENT_ID and $GOOGLE_CLIENT_SECRET in the client ID and client Secret respectively.)

• Select Save to create and activate SSO Login Service.

Note:

• Only single SSO login configuration can be active at one time. Whenever you create or update any SSO configuration, it will be activated and used by Devtron and previous configurations will be deleted.

• Except for the domain substring, URL and redirectURI remains same.

2. Update SSO Configuration

You can change SSO configuration anytime by updating the configuration and click Update. Note: In case of configuration change, all users will be logged out of Devtron and will have to login again.

3. Configuration Payload

• type : Any platform name such as (Google, GitLab, GitHub etc.)

• name : Identity provider platform name

• config : User can put connector details for this key. Platforms may not have same structure but common configurations are clientID, clientSecret, redirectURI.

• hostedDomains : Domains authorized for SSO login.

Next Steps

Sample Configuration

Values You Would Require at SSO Provider

Devtron provides a sample configuration out of the box. There are some values that you need to either get from your SSO provider or give to your SSO provider.

Values to Fetch

• clientID

• clientSecret

Values to Provide

• redirectURI (provided in SSO Login Services by Devtron)

Reference

Sample Configuration

Values You Would Require at SSO Provider

Devtron provides a sample configuration out of the box. There are some values that you need to either get from your SSO provider or give to your SSO provider.

Values to Fetch

• clientID

• tenantID (required only if you want to use Azure AD for auto-assigning permissions)
• clientSecret

Values to Provide

• redirectURI (provided in SSO Login Services by Devtron)

Reference

Sample Configuration

Values to fetch from LDAP

Devtron provides a sample configuration out of the box. Here are some values you need to fetch from your LDAP.

• bindDN

• bindPW

• baseDN

Reference

Sample Configuration

Values You Would Require at SSO Provider

Devtron provides a sample configuration out of the box. There are some values that you need to either get from your SSO provider or give to your SSO provider.

Values to Fetch

• clientID

• clientSecret

Values to Provide

• redirectURI (provided in SSO Login Services by Devtron)

Reference

Sample Configuration

Values You Would Require at SSO Provider

Devtron provides a sample configuration out of the box. There are some values that you need to either get from your SSO provider or give to your SSO provider.

Values to Fetch

• clientID

• clientSecret

Values to Provide

• redirectURI (provided in SSO Login Services by Devtron)

Reference

External Links allow you to connect to the third-party applications within your Devtron dashboard for seamlessly monitoring/debugging/logging/analyzing your applications. You can select from the pre-defined third-party applications such as Grafana to link to your application for quick access.

Configured external links will be available on the App details page. You can also integrate Document or Folder using External Links.

Some of the third-party applications which are pre-defined on Devtron Dashboard are:

• Grafana

• Kibana

• Newrelic

• Coralogix

• Datadog

• Loki

• Cloudwatch

• Swagger

• Jira etc.

Use Case for Monitoring Tool

To monitor/debug an application using a specific Monitoring Tool (such as Grafana, Kibana, etc.), you may need to navigate to the tool's page, then to the respective app/resource page.

External Links can take you directly to the tool's page, which includes the context of the application, environment, pod, and container.

Prerequisites

Before you begin, configure an application in the Devtron dashboard.

• Super admin access

• Monitoring tool URL

Note: External links can only be added/managed by a super admin, but non-super admin users can access the configured external links on the App Configuration page.

Add an External Link

1. On the Devtron dashboard, go to the Global Configurations from the left navigation pane.

2. Select External links.

1. Select Add Link.

2. On the Add Link page, select the external link (e.g. Grafana) which you want to link to your application from Webpage.

The following fields are provided on the Add Link page:

Note: To add multiple links, select + Add another at the top-left corner.

Click Save.

Access an external link

The users (admin and others) can access the configured external link on the App Details page.

Note: If you enable App admins can edit on the External Links page, then only non-super admin users can view the selected links on the App Details page.

Manage External links

On the External Links page, the configured external links can be filtered/searched, as well as edited/deleted.

Select Global Configurations > External links.

• Filter and search the links based on the link's name or a user-defined name.

• Edit a link by selecting the edit icon next to an external link.

• Delete an external link by selecting the delete icon next to a link. The bookmarked link will be removed in the clusters for which it was configured.

With the Manage Notification feature, you can manage the notifications for your build and deployment pipelines. You can receive the notifications on Slack or via e-mail.

Go to the Global Configurations -> Notifications

Notification Configurations:

Click Configurations to add notification configuration in one of the following options:

• SES Configurations

• SMTP Configurations

• Slack Configurations

Manage SES Configurations

You can manage the SES configuration to receive e-mails by entering the valid credentials. Make sure your e-mail is verified by SES.

Click Add and configure SES.

Click Save to save your SES configuration or e-mail ID

Manage SMTP Configurations

You can manage the SMTP configuration to receive e-mails by entering the valid credentials. Make sure your e-mail is verified by SMTP.

Click Add and configure SMTP.

Click Save to save your SMTP configuration or e-mail ID

Manage Slack Configurations

You can manage the Slack configurations to receive notifications on your preferred Slack channel.

Click Add to add new Slack Channel.

Click Save and your slack channel will be added.

Manage Notifications

Click Add New to receive new notification.

Manage Slack Notifications

Send To

When you click on the Send to box, a drop-down will appear, select your slack channel name if you have already configured Slack Channel. If you have not yet configured the Slack Channel, Configure Slack Channel

Select Pipelines

• Then, to fetch pipelines of an application, project and environment.

  • Choose a filter type(environment, project or application)

  • You will see a list of pipelines corresponding to your selected filter type, you can select any number of pipelines. For each pipeline, there are 3 types of events Trigger, Success, and Failure. Click on the checkboxes for the events, on which you want to receive notifications.

Click Save when you are done with your Slack notification configuration.

Manage SES Notifications

Send To

• Click Send To box, select your e-mail address/addresses on which you want to send e-mail notifications. Make sure e-mail id are SES Verified.

If you have not yet configured SES, Configure SES.

Select Pipelines

• To fetch pipelines of an application, project and environment.

  • Choose a filter type(environment, project or application)

  • You will see a list of pipelines corresponding to your selected filter type, you can select any number of pipelines. For each pipeline, there are 3 types of events Trigger, Success, and Failure. Click on the checkboxes for the events, on which you want to receive notifications.

Click Save once you have configured the SES notification.

Manage SMTP Notifications

Send To

• Click Send To box, select your e-mail address/addresses on which you want to send e-mail notifications. Make sure e-mail IDs are SMTP Verified.

If you have not yet configured SMTP, Configure SMTP.

Select Pipelines

• To fetch pipelines of an application, project and environment.

  • Choose a filter type(environment, project or application)

  • You will see a list of pipelines corresponding to your selected filter type, you can select any number of pipelines. For each pipeline, there are 3 types of events Trigger, Success, and Failure. Click on the checkboxes for the events, on which you want to receive notifications.

Click Save once you have configured the SMTP notification.

Like any enterprise product, Devtron supports fine grained access control to the resources based on:

1. Type of action allowed on Devtron resources (Create Vs View)

2. Sensitivity of the data (Editing image Vs Editing memory)

Access can be added to the User either directly or via Permission groups.

Role-based Access Levels

Devtron supports the following levels of access:

1. View only: User with View only access has the least privilege. This user can only view combination of environments, applications and helm charts on which access has been granted to the user. This user cannot view sensitive data like secrets used in applications or charts.

2. Build and Deploy: In addition to View only access, user with Build and deploy permission can build and deploy the image of the permitted applications and helm charts to the permitted environments.

3. Admin: User with Admin access can create, edit, delete and view permitted applications in the permitted projects.

4. Manager: User with Manager access can do everything that an Admin type user can do, in addition, they can also give and revoke access of users for the applications and environments of which they are Manager.

5. Super Admin: User with Super admin privilege has unrestricted access to all Devtron resources. Super admin can create, modify, delete and view any Devtron resource without any restriction; its like Superman without the weakness of Kryptonite. Super Admin can also add and delete user access across any Devtron resource, add delete git repository credentials, container registry credentials, cluster and environment.

User Roles And Permissions

1. Custom Applications

2. Helm Charts

3. User Access

4. Global Configurations

Add User

To add a user, go to the Authorization > User Permissions section of Global Configurations. Click Add user.

There are two types of permissions in Devtron:

Assign Super admin permission

To assign a super admin access, go to the Authorization > User Permissions section of Global Configurations.

• Click Add user.

• Provide the email address of a user. You can add more than one email address. Please note that email address must be same as that in the email field in the JWT token returned by OIDC provider.

• Select Super admin permission and click Save.

• A user now will have a Super admin access.

Note:

• Only users with Super admin permission can assign super admin permissions to a user.

• We suggest that super admin access must be given to the selected users only.

Assign Specific permissions

To assign a specific permission, go to the Authorization > User Permissions section of Global Configurations.

• Click Add user.

• Provide the email address of a user. You can add more than one email address. Please note that email address must be same as that in the email field in the JWT token returned by OIDC provider.

• Select Specific permissions.

• Select the group permission from the drop-down list, if required.

• Selecting Specific permission option allows you to manage access and provide the role-based access accordingly for

  • Devtron Apps

  • Helm Apps

  • Kubernetes Resources

  • Chart Groups

Devtron Apps Permissions

In Devtron Apps option, you can provide access to a user to manage permission for custom apps created using Devtron.

Note: The Devtron Apps option will be available only if you install CI/CD integration.

Provide the information in the following fields:

You can add multiple rows for Devtron app permission.

Once you have finished assigning the appropriate permissions for the users, Click Save.

Helm Apps Permissions

In Helm Apps option, you can provide access to a user to manage permission for Helm apps deployed from Devtron or outside Devtron.

Provide the information in the following fields:

You can add multiple rows for Devtron app permission.

Once you have finished assigning the appropriate permissions for the users, Click Save.

Kubernetes Resources Permissions

In Kubernetes Resources option, you can provide permission to view, inspect, manage, and delete resources in your clusters from Kubernetes Resource Browser page in Devtron. You can also create resources from the Kubernetes Resource Browser page.

Note: Only super admin users will be able to see Kubernetes Resources tab and provide permission to other users to access Resource Browser.

To provide Kubernetes resource permission, click Add permission.

On the Kubernetes resource permission, provide the information in the following fields:

You can add multiple rows for Kubernetes resource permission.

Once you have finished assigning the appropriate permissions for the users, Click Save.

Chart Group Permissions

In Chart group permission option, you can manage the access of users for Chart Groups in your project.

Note: The Chart group permission option will be available only if you install CI/CD integration.

NOTE: You can only give users the ability to create or edit, not both.

Click Saveonce you have configured all the required permissions for the users.

Edit User Permissions

You can edit the user permissions by clicking on the downward arrow.

Edit the user permissions.

After you have done editing the user permissions, click Save.

If you want to delete the user/users with particular permissions, click Delete.

Using the Permission groups, you can assign a user to a particular group and a user inherits all the permissions granted to the group.

The advantage of the Permission groups is to define a set of privileges like create, edit, or delete for the given set of resources that can be shared among the users within the group.

Add Group

Go to Global Configurations → Authorization → Permissions groups → Add group.

Enter the Group Name and Description.

You can either grant super-admin permission to a user group or specific permissions to manage access for:

• Devtron Apps

• Helm Apps

• Jobs

• Kubernetes Resources

• Chart Groups

Devtron Apps Permissions

In Devtron Apps option, you can provide access to a group to manage permission for custom apps created using Devtron.

Provide the information in the following fields:

You can add multiple rows for Devtron Apps permission.

Once you have finished assigning the appropriate permissions for the groups, Click Save.

Helm Apps Permissions

In Helm Apps option, you can provide access to a group to manage permission for Helm apps deployed from Devtron or outside Devtron.

Provide the information in the following fields:

You can add multiple rows for Devtron app permission.

Once you have finished assigning the appropriate permissions for the groups, Click Save.

Jobs

In Jobs option, you can provide access to a group to manage permission for jobs created using Devtron.

Provide the information in the following fields:

You can add multiple rows for Jobs permission.

Once you have finished assigning the appropriate permissions for the groups, Click Save.

Kubernetes Resources Permissions

In Kubernetes Resources option, you can provide permission to view, inspect, manage, and delete resources in your clusters from Kubernetes Resource Browser page in Devtron. You can also create resources from the Kubernetes Resource Browser page.

To provide Kubernetes resource permission, click Add permission.

On the Kubernetes resource permission, provide the information in the following fields:

You can add multiple rows for Kubernetes resource permission.

Once you have finished assigning the appropriate permissions for the groups, Click Save.

Chart Group Permissions

In Chart group permission option, you can manage the access of groups for Chart Groups in your project.

Click Save once you have configured all the required permissions for the groups.

Edit Permissions Groups

You can edit the permission groups by clicking the downward arrow.

Edit the permission group.

Once you are done editing the permission group, click Save.

If you want to delete the groups with particular permission group, click Delete.

Prerequisites

A verified account on Okta. Okta activates your account only if email verification is successful.

Here's a reference guide to set up your Okta org and application: Link

Tutorial

Steps on Okta Admin Console

Once your Okta org is set up, create an app integration on Okta to get a Client ID and Client Secret.

1. In the Admin Console, go to Applications → Applications.

2. Click Create App Integration.

3. Select OIDC - OpenID Connect as the Sign-in method.

1. Select Web as the application type and click Next.

2. On the App Integration page:

   • Give a name to your application.

   • Select the Interaction Code and Refresh Token checkbox.

   • Now go to Devtron's Global Configurations → SSO Login Services → OIDC.

   • Copy the redirect URI given in the helper text (might look like: https://xxx.xxx.xxx/xxx/callback).

   • Return to the Okta screen, and remove the prefilled value in Sign-in redirect URIs.

   • Paste the copied URI in Sign-in redirect URIs.

   • Click Save.

3. On the General tab:

   • Note the Client ID value.

   • Click the Edit option.

   • In Client Authentication, choose Client Secret.

   • Click Save.

   • Click Generate new secret.

   • Note the Client Secret value.

Steps on Devtron

1. Go to the Global Configurations → SSO Login Services → OIDC.

2. In the URL field, enter the Devtron application URL (a valid https link) where it is hosted.

3. Under Configuration tab, locate the config object, and provide the clientID and clientSecret of the app integration you created on Okta.

4. Add a key insecureSkipEmailVerified: true. Note that this key is only required for Okta SSO. For other types of OIDC SSO, refer OIDC supported configurations.

5. Provide issuer value as https://${yourOktaDomain}. Replace ${yourOktaDomain} with your domain on Okta as shown in the video.

6. For providing redirectURI or callbackURI registered with the SSO provider, you can either select Configuration or Sample Script. Note that the redirect URI is already given in the helper text (as seen in the previous section).

7. Click Save to create and activate Okta SSO login.

Now your users will be able to log in to Devtron using the Okta authentication method. Note that existing signed-in users will be logged out and they have to log in again using their OIDC account.

Sample Configuration

API tokens are the access tokens for authentication. Instead of using username and password, it can be used for programmatic access to API. It allows users to generate API tokens with the desired access. Only super admin users can generate API tokens and see the generated tokens.

Generate API Token

To generate API tokens, go to Global Configurations -> Authorization -> API tokens and click Generate New Token.

• Enter a name for the token.

• Add Description.

• Select an expiration date for the token (7 days, 30 days, 60 days, 90 days, custom and no expiration).

• To select a custom expiration date, select Custom from the drop-down list. In the adjacent field, you can select your custom expiration date for the API token.

• You can assign permission to the token either with:

  • Super admin permission: To generate a token with super admin permission, select Super admin permission.

  • Specific permissions: Selecting Specific permissions option allows you to generate a token with a specific role for:

    • Devtron Apps

    • Helm Apps

    • Kubernetes Resources

    • Chart Groups

• Click Generate Token.

A pop-up window will appear on the screen from where you can copy the API token.

Use API Token

Once Devtron API token has been generated, you can use this token to request Devtron APIs using any API testing tool like Jmeter, Postman, Citrus. Using Postman here as an example.

Open Postman. Enter the request URL with POST method and under HEADERS, enter the API token as shown in the image below.

In the Body section, provide the API payload as shown below and click Send.

As soon as you click Send, the created application API will be triggered and a new Devtron app will be created as provided in the payload.

Update API Token

To set a new expiration date or to make changes in permissions assigned to the token, we need to update the API token in Devtron. To update the API token, click the token name or click on the edit icon.

To set a new expiration date, you can regenerate the API token. Any scripts or applications using this token must be updated. To regenerate a token, click Regenerate token.

A pop-up window will appear on the screen from where you can select a new expiration date.

Select a new expiration date and click Regenerate token.

This will generate a new token with a new expiration date.

To update API token permissions, give the permissions as you want to and click Update Token.

Delete API Token

To delete an API token, click delete icon. Any applications or scripts using this token will no longer be able to access the Devtron API.

Introduction

The Deployment Template might contain certain configurations intended for the DevOps team (e.g., ingress), and not meant for developers to modify.

Therefore, Devtron allows super-admins to restrict such fields from modification or deletion.

This stands true for deployment templates in:

• Base configuration

• Environment-level configuration

How is this different from the Protect Configuration feature?

The 'protect configuration' feature is meant to verify the edits by introducing an approval flow for any changes made to the configuration files, i.e., Deployment template, ConfigMaps, and Secrets. This is performed at application-level.

Whereas, the 'lock deployment configuration' feature goes one step further. It is meant to prevent any edits to specific keys by non-super-admins. This applies only to deployment templates and is performed at global-level.

Locking Deployment Keys

1. Go to Global Configurations → Lock Deployment Config. Click Configure Lock.
2. (Optional) Click Refer Values.YAML to check which keys you wish to lock.
3. Enter the keys inside the editor on the left-hand side, e.g., autoscaling.MaxReplicas. Use JSONpath expressions to enter specific keys, lists, or objects to lock.
4. Click Save.
5. A confirmation dialog box would appear. Read it and click Confirm.

Result

While super-admins can directly edit the locked keys, let's look at a scenario where a user (non-super-admin) tries to edit the same in an unprotected base deployment template.

• User can hide/unhide the locked keys as shown below.

• Let's assume the user edits one of the locked keys...

  ...and saves the changes.
• A modal window will appear on the right highlighting the non-eligible edits.
• Let's assume the user edits a key that is not locked or adds a new key.
• The modal window will highlight the eligible edits. However, it will not let the user save those eligible edits unless the user clicks the checkbox: Save changes which are eligible for update.

• Once the user clicks the Update button, the permissible changes will reflect in the deployment template.

  However, if it's a protected template, the user will require the approval of a configuration approver as shown below.

The same result can be seen if the user tries to edit environment-specific deployment templates.

Introduction

Ideally, all resources such as microservices, clusters, jobs, pods, etc. should contain detailed information so that its users know what each of those resources do, how to use them, as well as all their technical specs. Access to such data makes it easier for engineers to quickly discover and understand the relevant resources.

To achieve this, Devtron supports a feature known as Catalog Framework. Using this, you as a super-admin can decide the data you expect from the managers of different resource types. In other words, you can create a custom JSON schema that would ultimately render a form for the resource owners to fill. Once the form is filled, a GUI output will appear as shown below.

Currently, Devtron supports catalog framework for the following resource types (a.k.a. resource kind):

• Devtron applications

• Helm applications

• Clusters

• Jobs

There are two parts involved in the creation of a desirable resource catalog:

1. Defining a Schema

2. Filling the Schema-Generated Form

Defining a Schema

1. Go to Global Configurations → Catalog Framework.

2. Choose a resource type, for which you wish to define a schema, for e.g., Devtron applications.
3. You can edit the schema name and description.

4. There is a sample schema available for you to create your own customized schema. Using this schema, you can decide the input types that renders within the form, for e.g., a dropdown of enum values, a boolean toggle button, text field, label, and many more.
5. After defining your schema, click Review Changes.

6. You get a side-by-side comparison (diff) highlighting the changes you made.
7. Click Save.

Similarly, you can define schemas for other resource types.

Note: If you edit a field (of an existing schema) for which users have already filled the data, that data will be erased. You will receive a prompt (as shown below) to confirm whether you want to proceed with the changes.

Filling the Schema-Generated Form

Once a catalog schema exists for a resource type, its corresponding form would be available in the overview section of that resource type.

1. Since we defined a schema for Devtron applications in the above example, go to the Overview tab of your application (any Devtron application). Click the Edit button within the About section.
2. The schema created for Devtron applications would render into an empty form as shown below.
3. Fill as many details as an application owner to the best of your knowledge and click Save.
4. Your saved data would be visible in a GUI format (and also in JSON format) as shown below.

This catalog data would be visible to all the users who have access to the application, but its data can be edited only by the resource owners (in this case, application admin/managers).

Introduction

Devtron offers the option to pull container images using digest. Refer CD Pipeline - Image Digest to know the purpose it serves.

Though it can be enabled by an application-admin for a given CD Pipeline, Devtron also allows super-admins to enable pull image digest at environment level.

This helps in better governance and less repetitiveness if you wish to manage pull image digest for multiple applications across environments.

Steps to Enable Pull Image Digest

From the left sidebar, go to Global Configurations → Pull Image Digest.

As a super-admin, you can decide whether you wish to enable pull image digest for all environments or for specific environments.

For all Environments

This is for enabling pull image digest for deployment to all environments.

1. Enable the toggle button next to Pull image digest for all existing & future environments.
2. Click Save Changes.

For Specific Environments

This is for enabling pull image digest for specific environments. Therefore, only those applications deploying to selected environment(s) will have pull image digest enabled in its CD pipeline.

1. Use the checkbox to choose one or more environments present within the list of clusters you have on Devtron.
2. Click Save Changes.

Once you enable pull image digest for a given environment in Global Configurations, users won't be able to modify the image digest setting in the CD pipeline. The toggle button would appear disabled for that environment as shown below.

Devtron's Tags Policy feature enables you to assign tags to your applications. Devtron also offers the option to propagate the tags assigned to an application as labels within the associated Kubernetes resources.

Add Tags

To add tags, follow these steps:

1. From the left pane, navigate to the Global Configuration section.

2. Select Tags within the Global Configuration section.

Once you are in the Tags section, locate the Add Tag button in the upper-right corner of the screen and click it.

Within the Add Tag section, you will find two options for tags:

• Suggested tags: These tags appear as suggestions when adding tags to applications.

• Mandatory tags: These tags are required for applications within the selected project.

To create mandatory tags, choose the second option: Mandatory tags. This ensures that the specified tags are mandatory for the applications within the selected project.

1. Next, choose the project(s) for which you want to create mandatory tags. You can select multiple projects at once (if required).

2. After selecting the projects, proceed to add the mandatory tags for the selected projects.

Propagate Tags to Kubernetes Resources

By default, tags assigned to applications in Devtron are not automatically propagated to Kubernetes resources as labels. However, Devtron provides the flexibility to enable this feature if desired.

When the propagation is enabled for tags from the global configuration, the tags will be automatically propagated as labels for all applications within the projects where these tags are used. Even if tag propagation is disabled from the global configuration in Devtron, you still have the option to enable propagation at the application level.

Create Application With Mandatory Tags

In a project where mandatory tags are enabled, it is required to provide values for those tags when creating new applications. Without providing values for the mandatory tags, it is not possible to create a new application within that project.

When mandatory tags are enabled, Devtron enforces the requirement to specify values for these tags during the application creation process. This ensures that all applications within the project adhere to the specified tag values.

Propagate Tags to Kubernetes Resources While Creating Application

If tag propagation for a project is disabled globally, you can still enable it for individual applications. During the application creation process, you have the option to enable tag propagation specifically for that application. By doing so, the tags assigned to that application will be propagated as labels to the associated Kubernetes resources.

Introduction

An ideal deployment workflow may consist of multiple stages (e.g., SIT, UAT, Prod environment).

Therefore, Devtron offers a feature called 'Image Promotion Policy' that allows you to directly promote an image to the target environment, bypassing the intermediate stages in your workflow including:

Creating an Image Promotion Policy

You can create a policy using our APIs or through Devtron CLI. To get the latest version of the devtctl binary, please contact your enterprise POC or reach out to us directly for further assistance.

Here is the CLI approach:

Syntax:

Arguments:

• --name (required): The name of the image promotion policy.

• --description (optional): A brief description of the policy, preferably explaining what it does.

• --failCondition (optional): Images that match this condition will NOT be eligible for promotion to the target environment.

• --approverCount (optional): The number of approvals required to promote an image (0-6). Defaults to 0 (no approvals).

• --allowRequestFromApprove (optional): (Boolean) If true, user who raised the image promotion request can approve it. Defaults to false.

• --allowImageBuilderFromApprove (optional): (Boolean) If true, user who triggered the build can approve the image promotion request. Defaults to false.

• --allowApproverFromDeploy (optional): (Boolean) If true, user who approved the image promotion request can deploy that image. Defaults to false.

• --applyPath (optional): Specify the path to the YAML file that contains the list of applications and environments to which the policy should be applicable.

Applying an Image Promotion Policy

You can apply a policy using our APIs or through Devtron CLI. Here is the CLI approach:

• Create a YAML file and give it a name (say applyPolicy.yaml). Within the file, define the applications and environments to which the image promotion policy should apply, as shown below.

• Apply the policy using the following CLI command:

Result

Promoting Image to Target Environment

Here, you can promote images to the target environment(s).

1. Go to the Build & Deploy tab of your application.

2. Click the Promote button next to the workflow in which the you wish to promote the image. Please note, the button will appear only if image promotion is allowed for any environment used in that workflow.
3. In the Select Image tab, you will see a list of images. Use the Show Images from dropdown to filter the list and choose the image you wish to promote. This can be either be an image from the CI pipeline or one that has successfully passed all stages (e.g., pre, post, if any) of that particular environment.
4. Use the SELECT button on the image, and click Promote to...

5. Select one or more target environments using the checkbox.
6. Click Promote Image.

The image's promotion to the target environment now depends on the approval settings in the image promotion policy. If the super-admin has enforced an approval process, the image requires the necessary number of approvals before promotion. On the other hand, if the super-admin has not enforced approval, the image will be automatically promoted since there is no request phase involved.

1. If approval(s) are required for image promotion, you may check the status of your request in the Approval Pending tab.

Approving Image Promotion Request

1. Go to the Build & Deploy tab of your application.

2. Click the Promote button next to the workflow.

3. Go to the Approval Pending tab to see the list of images requiring approval. By default, it shows a list of all images whose promotion request is pending with you.

1. Click Approve for... to choose the target environments to which it can be promoted.

2. Click Approve.

You can also use the Show requests dropdown to filter the image promotion requests for a specific target environment.

If there are pending promotion requests, you can approve them as shown below:

Deploying a Promoted Image

In the Build & Deploy tab of your application, click Select Image for the CD pipeline, and choose your promoted image for deployment.

You can check the deployment of promoted images in the Deployment History of your application. It will also indicate the pipeline from which the image was promoted and deployed to the target environment.

Introduction

The you create in Devtron for managing the CI-CD of your application can be made flexible or restricting with the help of CD filter conditions, for e.g., not all events (such as image builds) generated during the CI stage require progression to the CD stage. Therefore, instead of creating multiple workflows that cater to complex requirements, Devtron provides you the option of defining filters to tailor your workflow according to your specific needs.

Using filter conditions, you can control the progression of events. Here are a few general examples:

• Images containing the label "test" should not be eligible for deployment in production environment

• Only images having tag versions greater than v0.7.4 should be eligible for deployment

• Images hosted on Docker Hub should be eligible but not the rest

Steps to Create a Filter

1. From the left sidebar, go to Global Configurations → Filter Condition.

2. Add a filter condition.
3. In the Define Filter condition section, you get the following fields:

   • Filter For: Choose the pipeline upon which the filter should apply. Currently, you can use filter conditions for CD pipelines only. Support for CI pipelines is underway.

   • Filter Name: Give a name to the filter.

   • Description: (Optional) Add a description to the filter, preferably explaining what it does.

   • Filter Condition: You can specify either a pass condition, fail condition, or both the conditions:

     • Pass Condition: Events that satisfy the pass condition are eligible to trigger your CD pipeline.

     • Fail Condition: Events that satisfy the fail condition are not eligible to trigger your CD pipeline.

   • Use CEL Expression: You can use Common Expression Language (CEL) to define the conditions. Currently, you can create conditions with the help of following variables:

     • containerImage: Package that contains all the necessary files and instructions to run an application in a container, e.g., gcr.io/k8s-minikube/kicbase:v0.0.39. It returns a string value in the following format: <registry>/<repository>:<tag>

     • containerRepository: Storage location for container images, e.g., kicbase

     • containerImageTag: Versioning of image to indicate its release, e.g., v0.0.39

     • imageLabels: The label(s) you assign to an image in the CD pipeline, e.g., ["PROD","Stage"]. It returns an array of strings.

     Click View filter criteria to check the supported criteria. You get a copy button and a description of each criterion upon hovering. Moreover, you can go to CEL expression to learn more about the rules and supported syntax. Check to know more.
4. Click Next.

5. In the Apply to section, you get the following fields:

   • Application: Choose one or more applications to which your filter condition must apply.

   • Environment: Choose one or more environments to which your filter condition must apply.

1. Click Save. You have successfully created a filter.

Examples

Pass Condition

Consider a scenario where you wish to make an image eligible for deployment only if its tag version is greater than v0.0.7

The CEL Expression should be containerImageTag > "v0.0.7"

Go to the Build & Deploy tab. The filter condition was created specifically for test environment, therefore the filter condition would be evaluated only at the relevant CD pipeline, i.e., test

Click Select Image for the test CD pipeline. The first tab Eligible images shows the list and count of images that have satisfied the pass condition since their tag versions were greater than v0.0.7. Hence, they are marked eligible for deployment.

The second tab Latest images shows the latest builds (up to 10 images) irrespective of whether they have satisfied the filter condition(s) or not. The ones that have not satisfied the filter conditions get marked as Excluded. In other words, they are not eligible for deployment.

Clicking the filter icon at the top-left shows the filter condition(s) applied to the test CD pipeline.

Fail Condition

Consider a scenario where you wish to exclude an image from deployment if its tag starts with the word trial or ends with the word testing

The CEL Expression should be containerImageTag.startsWith("trial") || containerImageTag.endsWith("testing")

Go to the Build & Deploy tab. The filter condition was created specifically for devtron-demo environment, therefore the filter condition would be evaluated only at the relevant CD pipeline, i.e., devtron-demo

Click Select Image for the devtron-demo CD pipeline. The first tab Eligible images shows the list and count of images that have not met the fail condition. Hence, they are marked eligible for deployment.

The second tab Latest images shows the latest builds (up to 10 images) irrespective of whether they have satisfied the filter condition(s) or not. The ones that have satisfied the filter conditions get marked as Excluded. In other words, they are not eligible for deployment.

Clicking the filter icon at the top-left shows the filter condition(s) applied to the devtron-demo CD pipeline.

Introduction

In any piece of software or code, variables are used for holding data such as numbers or strings. Variables are created by declaring them, which involves specifying the variable's name and type, followed by assigning it a value.

Devtron offers super-admins the capability to define scoped variables (key-value pairs). It means, while the key remains the same, its value may change depending on the following context:

• Global: Variable value will be universally same throughout Devtron.

• Cluster: Variable value might differ for each Kubernetes cluster.

• Environment: Variable value might differ for each environment within a cluster, e.g., staging, dev, prod.

• Application: Variable value might differ for each application.

• Environment + Application: Variable value might differ for each application on a specific environment.

Advantages of using scoped variables

• Reduces repeatability: Configuration management team can centrally maintain the static data.

• Simplifies bulk edits: All the places that use a variable get updated when you change the value of the variable.

• Keeps data secure: You can decide the exposure of a variable's value to prevent misuse or leakage of sensitive data.

How to Define a Scoped Variable

On Devtron, a super-admin can download a YAML template. It will contain a schema for defining the variables.

Download the Template

1. From the left sidebar, go to Global Configurations → Scoped Variables

2. Click Download template.
3. Open the downloaded template using any code editor (say VS Code).

Enter the Values

The YAML file contains key-value pairs that follow the below schema:

The spec.values array further contains the following elements:

Here's a truncated template containing the specification of two variables for your understanding:

Upload the Template

1. Once you save the YAML file, go back to the screen where you downloaded the template.

2. Use the file uploader utility to upload your YAML file.
3. The content of the file will be uploaded for you to review and edit. Click Review Changes.
4. You may check the changes between the last saved file and the current one before clicking Save.

How to Edit an Existing Scoped Variable

Only a super-admin can edit existing scoped variables.

Option 1: Directly edit using the UI

Option 2: Reupload the updated YAML file

How to Use a Scoped Variable

Once a variable is defined, it can be used by your authorized users on Devtron. A scoped variable widget would appear only on the screens that support its usage.

• Workflow Editor → Edit build pipeline → Pre-build stage (tab)

• Workflow Editor → Edit build pipeline → Post-build stage (tab)

• Workflow Editor → Edit deployment pipeline → Post-Deployment stage (tab)

• Workflow Editor → Edit deployment pipeline → Post-Deployment stage (tab)

• Deployment Template

• ConfigMaps

• Secrets

Upon clicking on the widget, a list of variables will be visible.

Use the copy button to copy a relevant variable of your choice.

It would appear in the following format upon pasting it within an input field: @{{variable-name}}

Order of Precedence

When multiple values are associated with a scoped variable, the precedence order is as follows, with the highest priority at the top:

5. Global

Example

1. Environment + App: This is the most specific scope, and it will take precedence over all other scopes. For example, the value of DB name variable for the app1 application in the prod environment would be app1-p, even though there is a global DB name variable set to Devtron. If a variable value for this scope is not defined, the App scope will be checked.

2. App: This is the next most specific scope, and it will take precedence over the Environment, Cluster, and Global scopes. For example, the value of DB name variable for the app1 application would be project-tahiti, even though the value of DB name exists in lower scopes. If a variable value for this scope is not defined, the Environment scope will be checked.

3. Environment: This is the next most specific scope, and it will take precedence over the Cluster and Global scopes. For example, the value of DB name variable in the prod environment would be devtron-prod, even though the value of DB name exists in lower scopes. If a variable value for this scope is not defined, the Cluster scope will be checked.

4. Cluster: This is the next most specific scope, and it will take precedence over the Global scope. For example, the value of DB name variable in the gcp-gke cluster would be Devtron-gcp, even though there is a global DB name variable set to Devtron-gcp. If a variable value for this scope is not defined, the Global scope will be checked.

5. Global: This is the least specific scope, and it will only be used if no variable values are found in other higher scopes. The value of DB name variable would be Devtron.