# Technical Documentation: devtron-labs/devtron > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/devtron-labs/devtron) ### Overview (README.md)

Devtron is an open source software delivery workflow for kubernetes written in go.
Explore documentation »

Website · Blog · Join Discord · Twitter

Join Discord Go Report Card License CII Best Practices made-with-Go Website devtron.ai

## :book: Menu - [Why Devtron](https://github.com/devtron-labs/devtron#bulb-why-devtron) - [Features](https://github.com/devtron-labs/devtron#tada-features) - [Getting Started](https://github.com/devtron-labs/devtron#rocket-getting-started) - [Documentation](https://docs.devtron.ai/) - [Compatibility Notes](https://github.com/devtron-labs/devtron#memo-compatibility-notes) - [Community](https://github.com/devtron-labs/devtron#busts_in_silhouette-community) - [Contribute](https://github.com/devtron-labs/devtron#handshake-contribute) - [Vulnerability Reporting](https://github.com/devtron-labs/devtron#beetle-vulnerability-reporting) - [License](https://github.com/devtron-labs/devtron#bookmark-license) ## :bulb: Why Devtron? It is designed as a self-serve platform for operationalizing and maintaining applications (AppOps) on kubernetes in a developer friendly way.



## :tada: Features
Zero code software delivery workflow
- Workflow which understands the domain of **kubernetes, testing, CD, SecOps** so that you dont have to write scripts - Reusable and composable components so that workflows are easy to contruct and reason through
Multi cloud deployment
- Deploy to multiple kubernetes cluster - Test on aws cloud > coming soon: support for GCP and microsoft azure
Easy dev-sec-ops integration
- Multi level security policy at global, cluster, environment and application for efficient hierarchical policy management - Behavior driven security policy - Define policies and exception for kubernetes resources - Define policies for events for faster resolution
Application debugging dashboard
- One place for all historical kubernetes events - Access all manifests securely for e.g. secret obfuscation - ***Application metrics*** for cpu, ram, http status code and latency with comparison between new and old - ***Advanced logging*** with grep and json search - Intelligent ***correlation between events, logs*** for faster triangulation of issue - Auto issue identification
Enterprise grade security and compliances
- Fine grained access control; control who can edit configuration and who can deploy - Audit log to know who did what and when - History of all CI and CD events - Kubernetes events impacting application - Relevant cloud events and their impact on applications - Advanced workflow policies like blackout window, branch environment relationship to secure build and deployment pipelines
Gitops aware
- Gitops exposed through API and UI so that you dont have to interact with git cli - Gitops backed by postgres for easier analysis - Enforce finer access control than git
Operational insights
- Deployment metrics to measure success of agile process. It captures mttr, change failure rate, deployment frequency, deployment size out of the box. - Audit log to understand the failure causes - Monitor changes across deployments and revert easily
## :rocket: Getting Started #### Installing devtron with Helm ```bash $ git clone https://github.com/devtron-labs/devtron-installation-script.git $ cd devtron-installation-script/charts $ #modify values in values.yaml $ helm install devtron . -f values.yaml ``` For detail instructions checkout [devtron installation project](https://github.com/devtron-labs/devtron-installation-script/) #### :key: Access Devtron dashboard Devtron dashboard in now available at the `BASE_URL/dashboard`, where `BASE_URL` same as provided in `values.yaml` *****For login use username:`admin` and for password run command mentioned below.***** ```bash $ kubectl -n devtroncd get secret devtron-secret -o jsonpath='{.data.ACD_PASSWORD}' | base64 -d ``` *****[Detail configuration options](https://docs.devtron.ai/setup/install#configuration)***** #### Using devtron - [Deploying First Application](https://docs.devtron.ai/user-guide/creating-application) - [Deploying Helm charts](https://docs.devtron.ai/user-guide/deploy-chart) - [Configure Security policy](https://docs.devtron.ai/user-guide/security-features) - [Detail Userguide](https://docs.devtron.ai) ## :memo: Compatibility notes - Only AWS kubernetes cluster is supported as of now - It uses modified version of [argo rollout](https://argoproj.github.io/argo-rollouts/) - Application metrics only works for k8s 1.16+ ## :busts_in_silhouette: Community Get updates on Devtron's development and chat with the project maintainers, contributors and community members. - Join the [Discord Community](https://discord.gg/jsRG5qx2gp) - Follow [@DevtronL on Twitter](https://twitter.com/DevtronL) - Raise feature requests, suggest enhancements, report bugs at [GitHub issues](https://github.com/devtron-labs/devtron/issues) - Read the [Devtron blog](https://devtron.ai/blog/) ## :handshake: Contribute Check out our [contributing guidelines](CONTRIBUTING.md). Included are directions for opening issues, coding standards, and notes on our development processes. ## :beetle: Vulnerability Reporting We at Devtron take security and our users' trust very seriously. If you believe you have found a security issue in Devtron, please responsibly disclose us at security@devtron.ai. ## :bookmark: License Devtron is available under the [Apache License, Version 2.0](LICENSE) --- ### README (`docs/README.md`) # Introduction to Devtron Devtron is a tool integration platform for Kubernetes. Devtron deeply integrates with products across the lifecycle of microservices i.e., CI/CD, security, cost, debugging, and observability via an intuitive web interface. Devtron helps you to deploy, observe, manage & debug the existing Helm apps in all your clusters. {% embed url="https://www.youtube.com/watch?v=AG8HfTceHxw" caption="Introducing Devtron" %} ## Devtron's Key Features: ### No Code Software Delivery Workflow for Kubernetes * Workflow which understands the domain of **Kubernetes, testing, CD, SecOps** so that you don't have to write scripts * Reusable and composable components so that workflows are easy to construct and reason through ### Multi-cloud Deployment * Deploy to multiple Kubernetes clusters on multiple cloud/on-prem from one Devtron setup * Works for all cloud providers and on-premise Kubernetes clusters ### Easy DevSecOps Integration * Multi-level security policy at global, cluster, environment, and application-level for efficient hierarchical policy management * Behavior-driven security policy * Define policies and exceptions for Kubernetes resources * Define policies for events for faster resolution ### Application Debugging Dashboard * One place for all historical Kubernetes events * Access all manifests securely, such as secret obfuscation * _**Application metrics**_ for CPU, RAM, HTTP status code, and latency with a comparison between new and old * _**Advanced logging**_ with grep and JSON search * Intelligent _**correlation between events, logs**_ for faster triangulation of issue * Auto issue identification ### Enterprise-Grade Security and Compliances * Fine-grained access control; control who can edit the configuration and who can deploy. * Audit log to know who did what and when * History of all CI and CD events * Kubernetes events impacting application * Relevant cloud events and their impact on applications * Advanced workflow policies like blackout window, branch environment relationship to secure build and deployment pipelines ### Implements GitOps * GitOps exposed through API and UI so that you don't have to interact with git CLI * GitOps backed by Postgres for easy analysis * Enforce finer access control than Git ### Operational Insights * Deployment metrics to measure the success of the agile process. It captures MTTR, change failure rate, deployment frequency, and deployment size out of the box. * Audit log to understand the failure causes * Monitor changes across deployments and reverts easily ## Compatibility Notes * Devtron uses a modified version of [Argo Rollout](https://argoproj.github.io/argo-rollouts/). * Application metrics only work for K8s version 1.16+ ## Contributing Guidelines Check out our [contributing guidelines](https://github.com/devtron-labs/devtron/blob/main/CONTRIBUTING.md). Directions for opening issues, coding standards, and notes on our development processes are all included. ## Community Get updates on Devtron's development and chat with the project maintainers, contributors, and community members. * Join the [Discord Community](https://discord.gg/jsRG5qx2gp) * Follow [@DevtronL on Twitter](https://twitter.com/DevtronL) * Raise feature requests, suggest enhancements, report bugs at [GitHub issues](https://github.com/devtron-labs/devtron/issues) * Read the [Devtron blog](https://devtron.ai/blog/) ## Vulnerability Reporting We, at Devtron, take security and our users' trust very seriously. If you believe you have found a security issue in Devtron, please responsibly disclose it by contacting us at **security@devtron.ai**. --- ### Hyperion README (`docs/hyperion/README.md`) # Overview ## Hyperion 🦹 ### Why Hyperion? Hyperion is a lightweight Dashboard for Kubernetes deployments. Packed with full-fledged debugging features enabled with resource grouping for easier debugging for Development and Infra team. You can also upgrade to Devtron from Hyperion to enjoy full stack features of Devtron. > Do check the [Hyperion Installation Guide ⎈](../hyperion/setup/install.md) ### Hyperion Features #### Application-level resource grouping for easier Debugging - Hyperion groups your deployed microservices and displays them in a slick UI for easier monitoring or debugging. Access pod logs and resource manifests right from the Hyperion UI and even edit them! #### Centralized Access Management - Give access to users on Project, Environment and App level and control the level of access with customizable View only and Edit access. #### Manage and observe Multiple Clusters - Manage access of all the Kubernetes clusters (hosted on multiple cloud/on-prem) right from one Hyperion setup. #### View and Edit Kubernetes Manifests - View and Edit all Kubernetes resources right from the Hyperion dashboard. --- ## Contribute Check out our [contributing guidelines](https://github.com/devtron-labs/devtron/blob/main/CONTRIBUTING.md). Included are directions for opening issues, coding standards, and notes on our development processes. ## Community Get updates on Devtron's development and chat with the project maintainers, contributors and community members. * Join the [Discord Community](https://discord.gg/jsRG5qx2gp) * Follow [@DevtronL on Twitter](https://twitter.com/DevtronL) * Raise feature requests, suggest enhancements, report bugs at [GitHub issues](https://github.com/devtron-labs/devtron/issues) * Read the [Devtron blog](https://devtron.ai/blog/) ## Vulnerability Reporting We at Devtron take security and our users' trust very seriously. If you believe you have found a security issue in Devtron, please responsibly disclose by contacting us at security@devtron.ai. --- ### Setup Configurations Configurations Overview (`docs/setup/configurations/configurations-overview.md`) # Configurations You can configure Devtron by using configuration files. Configuration files are YAML files which are user-friendly. The configuration allows you to quickly roll back a configuration change if necessary. It also aids cluster re-creation and restoration. There are two ways you can perform configurations while setting up Devtron dashboard: * [Installation Configurations](../install/installation-configuration.md) * [Override Configurations](../install/override-default-devtron-installation-configs.md) You can also setup `ingress` while setting up Devtron dashboard. Refer [here](../install/ingress-setup.md) for ingress setup. --- ### Setup Getting Started Getting Started (`docs/setup/getting-started/getting-started.md`) # Getting Started This section includes information about the minimum requirements you need to install and use **Devtron**. Devtron is installed over a Kubernetes cluster. Once you create a Kubernetes cluster, Devtron can be installed standalone or along with CI/CD integration: * [Devtron with CI/CD](../install/install-devtron-with-cicd.md): Devtron installation with the CI/CD integration is used to perform CI/CD, security scanning, GitOps, debugging, and observability. * [Helm Dashboard by Devtron](../install/install-devtron.md): The Helm Dashboard by Devtron, which is a standalone installation, includes functionalities to deploy, observe, manage, and debug existing Helm applications in multiple clusters. You can also install integrations from [Devtron Stack Manager](../../user-guide/integrations/README.md). In this section, we will cover the basic details on how you can quickly get started with **Devtron**. First, lets see what are the prerequisite requirements before you install Devtron. ## Prerequisites * Create a [Kubernetes cluster, preferably K8s version 1.16 or higher](#create-a-kubernetes-cluster) * [Helm Installation](https://helm.sh/docs/intro/install/) * [Recommended Resources](#recommended-resources) ### Create a Kubernetes Cluster You can create any [Kubernetes cluster](https://kubernetes.io/docs/tutorials/kubernetes-basics/create-cluster/) (preferably K8s version 1.16 or higher) for installing Devtron. You can create a cluster using one of the following cloud providers as per your requirements: | Cloud Provider | Description | | --- | --- | | **AWS EKS** | Create a cluster using [AWS EKS](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-console.html).
`Note`: You can also refer our customized documentation for installing `Devtron with CI/CD` on AWS EKS [here](https://github.com/devtron-labs/devtron/blob/b33a37bb608d07966c8f8b89e4f59287db873c6c/docs/setup/install/install-devtron-on-aws-eks.md).
| | **Google Kubernetes Engine (GKE)** | Create a cluster using [GKE](https://cloud.google.com/kubernetes-engine/). | | **Azure Kubernetes Service (AKS)** | Create a cluster using [AKS](https://learn.microsoft.com/en-us/azure/aks/). | | **k3s - Lightweight Kubernetes** | Create a cluster using [k3s - Lightweight Kubernetes](https://devtron.ai/blog/deploy-your-applications-over-k3s-lightweight-kubernetes-in-no-time/).
`Note`: You can also refer our customized documentation for installing `Helm Dashboard by Devtron` on `Minikube, Microk8s, K3s, Kind` [here](../install/Install-devtron-on-Minikube-Microk8s-K3s-Kind.md).
| ### Install Helm Make sure to install [helm](https://helm.sh/docs/intro/install/). ### Recommended Resources The minimum requirements for installing `Helm Dashboard by Devtron` and `Devtron with CI/CD` as per the number of applications you want to manage on `Devtron` are provided below: * For configuring small resources (to manage not more than 5 apps on Devtron): | Integration | CPU | Memory | | --- | :---: | :---: | | **Devtron with CI/CD** | 2 | 6 GB | | **Helm Dashboard by Devtron** | 1 | 1 GB | * For configuring medium/larger resources (to manage more than 5 apps on Devtron): | Integration | CPU | Memory | | --- | :---: | :---: | | **Devtron with CI/CD** | 6 | 13 GB | | **Helm Dashboard by Devtron** | 2 | 3 GB | > Refer to the [Override Configurations](../install/override-default-devtron-installation-configs.md) section for more information. **Note:** * Please make sure that the recommended resources are available on your Kubernetes cluster before you proceed with Devtron installation. * It is NOT recommended to use brustable CPU VMs (T series in AWS, B Series in Azure and E2/N1 in GCP) for Devtron installation to experience consistency in performance. ## Installation of Devtron You can install Devtron standalone (Helm Dashboard by Devtron) or along with CI/CD integration. Or, you can upgrade Devtron to the latest version. Choose one of the options as per your requirements: | Installation Options | Description | | --- | --- | | [Devtron with CI/CD](../install/install-devtron-with-cicd.md) | Devtron installation with the CI/CD integration is used to perform CI/CD, security scanning, GitOps, debugging, and observability. | | [Helm Dashboard by Devtron](../install/install-devtron.md) | The Helm Dashboard by Devtron which is a standalone installation includes functionalities to deploy, observe, manage, and debug existing Helm applications in multiple clusters. You can also install integrations from [Devtron Stack Manager](../../user-guide/integrations/README.md). | | [Devtron with CI/CD along with GitOps (Argo CD)](../install/install-devtron-with-cicd-with-gitops.md) | With this option, you can install Devtron with CI/CD by enabling GitOps during the installation. You can also install other integrations from [Devtron Stack Manager](../../user-guide/integrations/README.md). | | **Upgrade Devtron to latest version** | You can upgrade Devtron in one of the following ways: | **Note**: If you have questions, please let us know on our discord channel. [](https://discord.gg/jsRG5qx2gp) --- ### Setup Install README (`docs/setup/install/README.md`) # Install Devtron Devtron is installed over a Kubernetes cluster. Once you create a Kubernetes cluster, Devtron can be installed standalone or along with CI/CD integration. Choose one of the options as per your requirements: | Installation Options | Description | When to choose | | --- | --- | --- | | [Devtron with CI/CD](../install/install-devtron-with-cicd.md) | Devtron installation with the CI/CD integration is used to perform CI/CD, security scanning, GitOps, debugging, and observability. | Use this option to install Devtron with `Build and Deploy CI/CD` integration. | | [Helm Dashboard by Devtron](../install/install-devtron.md) | The Helm Dashboard by Devtron which is a standalone installation includes functionalities to deploy, observe, manage, and debug existing Helm applications in multiple clusters. You can also install integrations from [Devtron Stack Manager](../../user-guide/integrations/README.md). | Use this option if you are managing the applications via Helm and you want to use Devtron to deploy, observe, manage, and debug the Helm applications. | | [Devtron with CI/CD along with GitOps (Argo CD)](../install/install-devtron-with-cicd-with-gitops.md) | With this option, you can install Devtron with CI/CD by enabling GitOps during the installation. You can also install other integrations from [Devtron Stack Manager](../../user-guide/integrations/README.md). | Use this option to install Devtron with CI/CD by enabling GitOps, which is the most scalable method in terms of version control, collaboration, compliance and infrastructure automation. | **Note**: If you have questions, please let us know on our discord channel. [](https://discord.gg/jsRG5qx2gp) --- ### Setup Upgrade README (`docs/setup/upgrade/README.md`) # Devtron Upgrade Devtron can be upgraded in one of the following ways: ## Upgrade Devtron using Helm **Versions Upgrade** - [0.6.x to 0.7.x](devtron-upgrade-0.6.x-0.7.x.md) - [0.5.x to 0.6.x](devtron-upgrade-0.5.x-0.6.x.md) - [0.4.x to 0.5.x](devtron-upgrade-0.4.x-0.5.x.md) - [0.4.x to 0.4.x](devtron-upgrade-0.4.x-0.4.x.md) - [0.3.x to 0.4.x](devtron-upgrade-0.3.x-0.4.x.md) - [0.3.x to 0.3.x](devtron-upgrade-0.3.x-0.3.x.md) - [0.2.x to 0.3.x](devtron-upgrade-0.2.x-0.3.x.md) ## Upgrade Devtron from the UI - [Update Devtron from Devtron UI](upgrade-devtron-ui.md) - [Update Devtron to beta version](devtron-upgrade-to-beta.md) --- ### User Guide Creating Application README (`docs/user-guide/creating-application/README.md`) # App Configuration **Please configure Global Configurations before moving ahead with App Configuration** {% embed url="https://www.youtube.com/watch?v=9u-pKiWV-tM" caption="" %} **Parts of Documentation** [Git Repository](git-material.md) [Build Configuration](docker-build-configuration.md) [Base Deployment Template](deployment-template.md) [GitOps Configuration](gitops-config.md) [Workflow Editor](workflow/README.md) [ConfigMaps](config-maps.md) [Secrets](secrets.md) [External Links](external-links.md) [Protect Configuration](config-approval.md) [Environment Overrides](environment-overrides.md) [Deleting Application](../deleting-application.md) --- ### User Guide Creating Application Overview (`docs/user-guide/creating-application/overview.md`) # Overview The `Overview` section contains the brief information of the application, any added tags, configured external links and deployment details of the particular application. In this section, you can also [change project of your application](#change-project-of-your-application) and [manage tags](#manage-tags) if you added them while creating application. The following details are provided on the **Overview** page: | Fields | Description | | :--- | :--- | | **App Name** | Displays the name of the application. | | **Created on** | Displays the day, date and time the application was created. | | **Created by** | Displays the email address of a user who created the application. | | **Project** | Displays the current project of the application. You can change the project by selecting a different project from the drop-down list. | ## Change Project of your Application You can change the project of your application by clicking **Project** on the `Overview` section. 1. Click `Project`. 2. On the `Change project` dialog box, select the different project you want to change from the drop-down list. 3. Click **Save**. The application will be moved to the selected project. {% hint style="info" %} ### If you change the project: The current users will lose the access to the application. The users who already have an access to the selected project, will get an access to the application automatically. {% endhint %} ## Manage Tags `Tags` are key-value pairs. You can add one or multiple tags in your application. When tags are propagated, they are considered as labels to Kubernetes resources. Kubernetes offers integrated support for using these labels to query objects and perform bulk operations e.g., consolidated billing using labels. You can use these tags to filter/identify resources via CLI or in other Kubernetes tools. `Manage tags` is the central place where you can create, edit, and delete tags. You can also propagate tags as labels to Kubernetes resources for the application. * Click `Edit`. * On the `Manage tags` page, click `+ Add tag` to add a new tag. * Click `X` to delete a tag. * Click the symbol on the left side of your tag to propagate a tag.
{% hint style="info" %} Dark grey colour in symbol specifies that the tags are propagated. {% endhint %} * To remove the tags from propagation, click the symbol again. * Click `Save`. The changes in the tags will be reflected in the `Tags` on the `Overview` section. ## Configure PersistentVolumeClaim (PVC) for Build Time Optimization A PersistentVolumeClaim (PVC) volume is a request for storage, which is used to mount a PersistentVolume (PV) into a Pod. In order to optimize build time, you can configure PVC in your application. If you want to optimize build time for the multiple target platforms (e.g., arm64, amd64), mounting a PVC will provide volume directly to a pod which helps in shorter build time by storing build cache. Mounting a PVC into a pod will provide storage for build cache which will not impact the normal build where the image is built on the basis of architecture and operating system of the K8s node on which CI is running. ### Create PVC file * The following configuration file describes persistent volume claim e.g.,`cache-pvc.yaml`, where you have to define the metadata `name` and `storageClassname`. ```bash apiVersion: v1 kind: PersistentVolumeClaim metadata: name: cache-pvc # here comes the name of PVC spec: accessModes: - ReadWriteOnce storageClassName: # here comes storage class name resources: requests: storage: 30Gi ``` * Create the PersistentVolumeClaim by running the following command: ```bash kubectl apply -f https://k8s.io/examples/pods/storage/pv-claim.yaml -n {namespace} ``` For more detail, refer [Kubernetes PVC](https://kubernetes.io/docs/tasks/configure-pod-container/configure-persistent-volume-storage/#create-a-persistentvolumeclaim). ## Configure PVC In order to configure PVC: * Go to the `Overview` section of your application. * On the right-corner, click `Edit`. * For app level PVC mounting, enter the following:`Note`: This PVC mounting will impact all the build pipelines of the application. * For pipeline level, enter the following:`Note`: This PVC mounting will impact only the particular build pipeline. To know the `pipelinename` detail, go to the `App Configuration`, click `Workflow Editor` the pipeline name will be on the `Build` pipeline as shown below. * Click `Save`. --- ### User Guide Deploy Chart README (`docs/user-guide/deploy-chart/README.md`) # Deploy Chart Welcome! This is the documentation for Deploying Charts. **Parts of Documentation** [Overview of Charts](overview-of-charts.md) [Charts Create, Update, Upgrade, Deploy, Delete](deployment-of-charts.md) [Chart Group Create Edit And Deploy](chart-group.md) [Examples](examples/README.md) --- ### User Guide Deploying Application README (`docs/user-guide/deploying-application/README.md`) # Deploying Application Each time you push a change to your application through GitHub, your application goes through a process to be built and deployed. There are two main steps for building and deploying applications: * [Triggering CI](triggering-ci.md) * [Triggering CD](triggering-cd.md) You can also rollback the deployment. Refer [Rollback Deployment](rollback-deployment.md) for detail. --- ### User Guide Global Configurations README (`docs/user-guide/global-configurations/README.md`) # Global Configurations 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`. [Host URL](host-url.md) [GitOps](gitops.md) [Projects](projects.md) [Clusters & Environments](cluster-and-environments.md) [Git Accounts](git-accounts.md) [Container/OCI Registry](container-registries.md) [Chart Repositories](chart-repo.md) [Deployment Charts](deployment-charts.md) [Authorization](authorization/README.md) [Notifications](manage-notification.md) [Deployment Window](deployment-window.md) [External Links](external-links.md) [Catalog Framework](catalog-framework.md) [Scoped Variables](scoped-variables.md) [Pull Image Digest](pull-image-digest.md) [Tags Policy](tags-policy.md) [Filter Condition](filter-condition.md) [Lock Deployment Configuration](lock-deployment-config.md) [Image Promotion Policy](image-promotion-policy.md) [Build Infra](build-infra.md) You can also refer our YouTube video provided here. {% embed url="https://www.youtube.com/watch?v=4VFjrjtieMI" caption="" %} --- ### User Guide Integrations README (`docs/user-guide/integrations/README.md`) # Devtron Integrations Devtron integrations extend the functionality of your Devtron stack. ## Discover and install integrations The current release of Devtron supports the Build and Deploy (CI/CD) integration. More integrations will be available soon; to request one, please [submit a ticket](https://github.com/devtron-labs/devtron/issues/new/choose) > Integrations can be installed by super admins; However other user roles can browse and request super admins to install the required integrations. > Integrations are updated along with [Devtron updates](../../setup/upgrade/README.md). Select **Devtron Stack Manager** from the left navigation bar. Under **INTEGRATIONS**, select **Discover**. > Although the integrations are installed separately, they cannot be upgraded separately. Integrations update happens automatically with [Devtron upgrade](#upgrade-devtron). --- ### User Guide Jobs README (`docs/user-guide/jobs/README.md`) # Jobs Job allows manual and automated execution of your source code. Job pipeline will not have CI/CD pipeline as the job is limited to your source code only. You can also configure [preset plugins](../creating-application/workflow/ci-build-pre-post-plugins.md#preset-plugins) in your job pipeline. With job, you can execute your source code quickly and easily without going through CI/CD pipelines, which also optimize time. There are two main steps in executing Job: * [Configurations](configuration-job.md) * [Trigger Job](triggering-job.md) In the next section, we will learn on how to create, configure, trigger a job. You can also view the details on the [Overview](overview-job.md) tab and `Run History`. --- ### User Guide Plugins README (`docs/user-guide/plugins/README.md`) # Pipeline Plugins Pipeline plugins (a.k.a. preset plugins) are micro tools that allow you to enhance and refine the [CI/CD workflow](../creating-application/workflow/README.md) of your application by adding new features, integrating with external tools, and automating tasks. Unlike [custom scripts](../creating-application/workflow/ci-build-pre-post-plugins.md#execute-custom-script), preset plugins come bundled with specific variables and conditions that help you make the plugins work seamlessly with your CI/CD pipeline. Some plugins are meant for pre-build/post-build, while some are meant for pre-deployment/post-deployment. From this section, you can know more about the individual plugins and its purpose. --- ### User Guide Sdh README (`docs/user-guide/sdh/README.md`) # Software Distribution Hub ## Introduction [](https://devtron.ai/pricing) Software Distribution Hub is a platform that simplifies the packaging, versioning, and delivery of your software products. By using it, you can manage your software release across multiple clients ([tenants](#release-versions)). ### When and Why to Use Devtron's Software Distribution Hub is designed to be used in scenarios where: * **Tenanted deployment**: You build software solutions for clients (tenants) who require updates deployed to their distinct environments. For every tenant, you may have to deploy a separate instance of your application, which has separate application layer and data layer on their infrastructure. * **Complex Release Management**: You need a centralized solution to manage the deployment of software updates across various environments and ensure smooth collaboration between different teams involved in the release process. * **Poor Visibility and Monitoring**: You need improved visibility into the release process for stakeholders such as Release Managers, Developers, DevOps teams, System Reliability Engineers (SREs), Tenant Points of Contact (POCs), and other stakeholders. They need to monitor releases, debug issues, and have access to current operational statuses. * **Inconsistent Deployment Processes**: You need standardization because you face operational challenges and deviation in your release outcomes, while carrying out deployment processes across multiple tenant environments. * **Insufficient Release Documentation**: You intend to eliminate confusion because your releases lack detailed documentation, including versioning, dependencies, configuration changes, and deployment prerequisites, causing inconsistencies and deployment failures. --- ## Advantages Devtron's Software Distribution Hub goes beyond basic deployment by providing end-to-end release management. Deployments involving manual processes might be prone to human error. However, Software Distribution Hub streamlines the [rollout](#rollout) process by enforcing [requirements](#requirements) for each release, and not just for one environment but multiple tenant environments. ### Normal Deployment vs SDH | Aspect | Normal Deployment | Software Distribution Hub | |--------------------------------------------|----------------------------------------------|----------------------------------------------------------------| | **Release Management** | No versioned deployments | Centralizes versioning and deployment into a unified platform | | **Visibility** | Limited visibility | Comprehensive visibility | | **Automated and Standardized Deployments** | Relies on manual scripts or basic automation (jobs) | Automates and standardizes deployments for consistency | | **End-to-End Release Management** | Focuses on pushing changes quickly | Manages entire release lifecycle from planning to post-release | | **Collaboration** | Gap or siloed communication among teams | Facilitates collaboration among developers, release managers, and other stakeholders | --- ## Concepts Devtron's Software Distribution Hub has 2 sections: * [Tenants](./tenants.md) * [Release Hub](./release-hub.md) Feel free to familiarize yourself with the following concepts (terms) before you proceed to Software Distribution Hub. ### Tenants Tenants are organizations or clients that use your software. You can think of each tenant as a separate customer. For example, if Microsoft and Google both use your software, they are considered separate tenants. Each tenant has its own environment to ensure their data and operations are kept separate from others. ### Installations One installation represents one deployment of your software for a specific [tenant](#tenants). Each installation serves as a separate instance of the software, customized for different stages of use or separate teams within your organization. For example, your organization might have three installations: * **Production Installation**: Where the live environment of the software runs for all your end-users. * **Development Installation**: Used by your team of developers for testing new features and changes before they go live. * **QA Installation**: Dedicated to quality assurance (team of testers) to ensure the software works correctly before it reaches users. ### Release Tracks A Release Track in Devtron is where you organize software releases. Each release within a Release Track is a unique version of your software. For example, think of Kubernetes as a release track, with "v1.28.8" as one of its releases. This helps in managing different versions and updates of a software project in a structured manner, ensuring that all versions are tracked and organized within their respective tracks. ### Requirements Requirements refer to specific steps that should be taken before deployment of applications. This includes selecting specific images for each application, specifying the [release order](#release-orderstage) of applications, adding release instructions, and locking these requirements to ensure readiness before a [rollout](#rollout). ### Release Order/Stage This is a part of [requirements](#requirements) where you decide the stages in which applications are deployed to ensure all dependencies are met. For example, you might need to deploy a backend service before a frontend feature that depends on it. In such a case, release order ensures that backend applications are deployed in the first stage, followed by frontend applications, ensuring a smooth and coordinated rollout. ### Rollout It is a process of delivering a new release to the tenant's environment. In Software Distribution Hub, this comes right after you lock the basic requirements of a release (i.e., application selection, release order, image selection, and release instructions). --- ### User Guide Use Cases README (`docs/user-guide/use-cases/README.md`) # Use Cases _**Welcome, this document consists of Devtron Use Cases**_ In this comprehensive guide, you will find a wide range of use cases, illustrating how Devtron can help optimize and streamline various aspects of your development and deployment processes. Explore the possibilities and discover how Devtron can enhance your workflows and empower your teams. Explore the following use cases to gain insights into the potential of Devtron: [Run Cron Jobs or One Time Job using Devtron Generic Helm Chart](devtron-generic-helm-chart-to-run-cron-job-or-one-time-job.md) [Connect SpringBoot with Mysql Database](connect-springboot-with-mysql-database.md) [Connect Expressjs With Mongodb Database](connect-expressjs-with-mongodb-database.md) [Connect Django With Mysql Database](connect-django-with-mysql-database.md) --- ### Hyperion User Guide Global Configurations README (`docs/hyperion/user-guide/global-configurations/README.md`) # Global Configurations This documentation consists of the Global Configurations available in Devtron. **Parts of the Documentation** [Cluster And Environments](cluster-and-environments.md) [SSO Login Service](sso-login.md) [User Access](user-access.md) --- ### User Guide Creating Application Eso README (`docs/user-guide/creating-application/eso/README.md`) # External Secret Operator (ESO) > **Prerequisites:** Chart version should be > 4.14.0 External Secrets Operator is a Kubernetes operator that integrates external secret management systems like AWS Secrets Manager, HashiCorp Vault, Google Secrets Manager, Azure Key Vault and many more. The operator reads information from external APIs and automatically injects the values into a Kubernetes Secret. ## Install External Secret Operator Before creating any external secrets on Devtron, `External Secret Operator` must be installed on the target cluster. `External Secret Operator` allows you to use external secret management systems (e.g., AWS Secrets Manager, Hashicorp Vault, Azure Secrets Manager, Google Secrets Manager etc.) to securely inject secrets in Kubernetes. You can install `External Secrets Operator` using charts store: 1. Go to charts store. 2. Search chart with name `external-secrets`. 3. If you don't find any chart with this name i.e `external-secrets`, add chart repository using repository url ` https://charts.external-secrets.io`. Please follow this [documentation](../../global-configurations/chart-repo.md#add-chart-repository) for adding chart repository. 4. Deploy the chart. --- ### User Guide Creating Application Workflow README (`docs/user-guide/creating-application/workflow/README.md`) # Workflow Workflow is a logical sequence of different stages used for continuous integration and continuous deployment of an application. Click on `New Build Pipeline` to create a new workflow On clicking `New Build Pipeline`, three options appear as mentioned below: * **Continuous Integration:** Choose this option if you want Devtron to build the image of source code. * **Linked CI Pipeline:** Choose this option if you want to use an image created by an existing CI pipeline in Devtron. * **Incoming Webhook:** Choose this if you want to build your image outside Devtron, it will receive a docker image from an external source via the incoming webhook. Then, create CI/CD Pipelines for your application. To know how to create the CI pipeline for your application, click on: [Create CI Pipelines](ci-pipeline.md) To know how to create the CD pipeline for your application, click on: [Create CD Pipelines](cd-pipeline.md) --- ### User Guide Deploy Chart Examples README (`docs/user-guide/deploy-chart/examples/README.md`) # Examples This Documentation guides you to Deploy different Helm Charts available on Devtron. **Parts of Documentation** [Deploying mySQL Helm Chart](deploying-mysql-helm-chart.md) [Deploying mongoDB Helm Chart](deploying-mongodb-helm-chart.md) --- ### User Guide Global Configurations Authorization README (`docs/user-guide/global-configurations/authorization/README.md`) `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](../sso-login.md) * [User Permissions](user-access.md) * [Permission Groups](permission-groups.md) * [API Tokens](api-tokens.md) --- ### SUMMARY (`docs/SUMMARY.md`) # Table of contents * [Introduction](README.md) * [Getting Started](setup/getting-started/getting-started.md) * [Install Devtron](setup/install/README.md) * [Install Devtron with CI/CD](setup/install/install-devtron-with-cicd.md) * [Install Devtron with CI/CD and GitOps (Argo CD)](setup/install/install-devtron-with-cicd-with-gitops.md) * [Install Devtron without Integrations](setup/install/install-devtron.md) * [Install Devtron on Minikube, Microk8s, K3s, Kind, Cloud VMs](setup/install/Install-devtron-on-Minikube-Microk8s-K3s-Kind.md) * [Install Devtron on Airgapped Environment](setup/install/install-devtron-in-airgapped-environment.md) * [Demo on Popular Cloud Providers](setup/install/demo-tutorials.md) * [Backup for Disaster Recovery](setup/install/devtron-backup.md) * [Uninstall Devtron](setup/install/uninstall-devtron.md) * [FAQs](setup/install/faq-on-installation.md) * [Devtron Kubernetes Client](setup/install/install-devtron-Kubernetes-client.md) * [Configurations](setup/configurations/configurations-overview.md) * [Installation Configurations](setup/install/installation-configuration.md) * [Override Configurations](setup/install/override-default-devtron-installation-configs.md) * [Ingress Setup](setup/install/ingress-setup.md) * [Global Configurations](user-guide/global-configurations/README.md) * [Host URL](user-guide/global-configurations/host-url.md) * [GitOps](user-guide/global-configurations/gitops.md) * [Projects](user-guide/global-configurations/projects.md) * [Clusters & Environments](user-guide/global-configurations/cluster-and-environments.md) * [Git Accounts](user-guide/global-configurations/git-accounts.md) * [Container/OCI Registry](user-guide/global-configurations/container-registries.md) * [Chart Repositories](user-guide/global-configurations/chart-repo.md) * [Deployment Charts](user-guide/global-configurations/deployment-charts.md) * [Authorization](user-guide/global-configurations/authorization/README.md) * [SSO Login Services](user-guide/global-configurations/sso-login.md) * [Google](user-guide/global-configurations/authorization/sso/google.md) * [GitHub](user-guide/global-configurations/authorization/sso/github.md) * [GitLab](user-guide/global-configurations/authorization/sso/gitlab.md) * [Microsoft](user-guide/global-configurations/authorization/sso/microsoft.md) * [LDAP](user-guide/global-configurations/authorization/sso/ldap.md) * [OIDC](user-guide/global-configurations/authorization/sso/oidc.md) * [Keycloak](user-guide/global-configurations/authorization/sso/keycloak.md) * [Okta](user-guide/global-configurations/authorization/sso/okta.md) * [OpenShift](user-guide/global-configurations/authorization/sso/openshift.md) * [User Permissions](user-guide/global-configurations/authorization/user-access.md) * [Permission Groups](user-guide/global-configurations/authorization/permission-groups.md) * [API Tokens](user-guide/global-configurations/authorization/api-tokens.md) * [Notifications](user-guide/global-configurations/manage-notification.md) * [Deployment Window](user-guide/global-configurations/deployment-window.md) * [External Links](user-guide/global-configurations/external-links.md) * [Catalog Framework](user-guide/global-configurations/catalog-framework.md) * [Scoped Variables](user-guide/global-configurations/scoped-variables.md) * [Pull Image Digest](user-guide/global-configurations/pull-image-digest.md) * [Tags Policy](user-guide/global-configurations/tags-policy.md) * [Filter Condition](user-guide/global-configurations/filter-condition.md) * [Lock Deployment Configuration](user-guide/global-configurations/lock-deployment-config.md) * [Image Promotion Policy](user-guide/global-configurations/image-promotion-policy.md) * [Build Infra](user-guide/global-configurations/build-infra.md) * [Devtron Upgrade](setup/upgrade/README.md) * [Update Devtron from Devtron UI](setup/upgrade/upgrade-devtron-ui.md) * [0.6.x-0.7.x](setup/upgrade/devtron-upgrade-0.6.x-0.7.x.md) * [0.5.x-0.6.x](setup/upgrade/devtron-upgrade-0.5.x-0.6.x.md) * [0.4.x-0.5.x](setup/upgrade/devtron-upgrade-0.4.x-0.5.x.md) * [0.4.x-0.4.x](setup/upgrade/devtron-upgrade-0.4.x-0.4.x.md) * [0.3.x-0.4.x](setup/upgrade/devtron-upgrade-0.3.x-0.4.x.md) * [0.3.x-0.3.x](setup/upgrade/devtron-upgrade-0.3.x-0.3.x.md) * [0.2.x-0.3.x](setup/upgrade/devtron-upgrade-0.2.x-0.3.x.md) ## Usage * [Applications](user-guide/applications.md) * [Create a New Application](user-guide/create-application.md) * [Clone an Existing Application](user-guide/cloning-application.md) * [Deploy a Sample Application](user-guide/Deploy-sample-app/nodejs\_app.md) * [App Configuration](user-guide/creating-application/README.md) * [Git Repository](user-guide/creating-application/git-material.md) * [Build Configuration](user-guide/creating-application/docker-build-configuration.md) * [Base Deployment Template](user-guide/creating-application/deployment-template.md) * [Deployment](user-guide/creating-application/deployment-template/deployment.md) * [Rollout Deployment](user-guide/creating-application/deployment-template/rollout-deployment.md) * [Job and Cronjob](user-guide/creating-application/deployment-template/job-and-cronjob.md) * [StatefulSets](user-guide/creating-application/deployment-template/statefulset.md) * [GitOps Configuration](user-guide/creating-application/gitops-config.md) * [Workflow Editor](user-guide/creating-application/workflow/README.md) * [CI Pipeline](user-guide/creating-application/workflow/ci-pipeline.md) * [Pre-Build/Post-Build Stages](user-guide/creating-application/workflow/ci-build-pre-post-plugins.md) * [Override Build Configuration](user-guide/creating-application/container-registry-override.md) * [CD Pipeline](user-guide/creating-application/workflow/cd-pipeline.md) * [ConfigMaps](user-guide/creating-application/config-maps.md) * [Secrets](user-guide/creating-application/secrets.md) * [External Secret Operator (ESO)](user-guide/creating-application/eso/README.md) * [AWS Secrets Manager](user-guide/creating-application/eso/aws-eso.md) * [Google Secrets Manager](user-guide/creating-application/eso/gcp-eso.md) * [HashiCorp Vault](user-guide/creating-application/eso/hashicorp-eso.md) * [Protect Configuration](user-guide/creating-application/config-approval.md) * [Environment Overrides](user-guide/creating-application/environment-overrides.md) * [Deleting Application](user-guide/deleting-application.md) * [Build and Deploy](user-guide/deploying-application/README.md) * [Triggering CI](user-guide/deploying-application/triggering-ci.md) * [Triggering CD](user-guide/deploying-application/triggering-cd.md) * [Rollback Deployment](user-guide/deploying-application/rollback-deployment.md) * [Applying Labels to Images](user-guide/deploying-application/image-labels-and-comments.md) * [App Details](user-guide/creating-application/app-details.md) * [Debugging Deployment And Monitoring](user-guide/debugging-deployment-and-monitoring.md) * [Using Ephemeral Containers](user-guide/app-details/ephemeral-containers.md) * [Application Metrics](user-guide/creating-application/app-metrics.md) * [Overview](user-guide/creating-application/overview.md) * [Jobs](user-guide/jobs/README.md) * [Create a new job](user-guide/jobs/create-job.md) * [Configurations](user-guide/jobs/configuration-job.md) * [Workflow Editor](user-guide/jobs/workflow-editor-job.md) * [Trigger Job](user-guide/jobs/triggering-job.md) * [Overview](user-guide/jobs/overview-job.md) * [Application Groups](user-guide/application-groups.md) * [Software Distribution Hub](user-guide/sdh/README.md) * [Tenants](user-guide/sdh/tenants.md) * [Release Hub](user-guide/sdh/release-hub.md) * [Resource Browser](user-guide/resource-browser.md) * [Resource Watcher](user-guide/resource-watcher.md) * [Charts](user-guide/deploy-chart/README.md) * [Charts Overview](user-guide/deploy-chart/overview-of-charts.md) * [Deploy & Observe](user-guide/deploy-chart/deployment-of-charts.md) * [Examples](user-guide/deploy-chart/examples/README.md) * [Deploying Mysql Helm Chart](user-guide/deploy-chart/examples/deploying-mysql-helm-chart.md) * [Deploying MongoDB Helm Chart](user-guide/deploy-chart/examples/deploying-mongodb-helm-chart.md) * [Chart Group](user-guide/deploy-chart/chart-group.md) * [Security](user-guide/security-features.md) * [Security Scans](user-guide/security-features/security-scans.md) * [Security Policies](user-guide/security-features/security-policies.md) * [Bulk Edit](user-guide/bulk-update.md) * [Integrations](user-guide/integrations/README.md) * [Build and Deploy (CI/CD)](user-guide/integrations/build-and-deploy-ci-cd.md) * [GitOps (Argo CD)](user-guide/integrations/argocd.md) * [Vulnerability Scanning (Clair)](user-guide/integrations/clair.md) * [Notifications](user-guide/integrations/notifications.md) * [Monitoring (Grafana)](user-guide/integrations/grafana.md) * [Pipeline Plugins](user-guide/plugins/README.md) * [Create Your Plugin](user-guide/plugins/create-plugin.md) * [Our Plugins](user-guide/plugins/plugin-list.md) * [Codacy](user-guide/plugins/codacy.md) * [Code-Scan](user-guide/plugins/code-scan.md) * [Copacetic](user-guide/plugins/copacetic.md) * [Copy Container Image](user-guide/plugins/copy-container-image.md) * [Cosign](user-guide/plugins/cosign.md) * [CraneCopy](user-guide/plugins/crane-copy.md) * [Dependency track - Maven & Gradle](user-guide/plugins/dependency-track-maven-gradle.md) * [Dependency track - NodeJS](user-guide/plugins/dependency-track-nodejs.md) * [Dependency track - Python](user-guide/plugins/dependency-track-python.md) * [Devtron CD Trigger](user-guide/plugins/devtron-cd-trigger.md) * [Devtron Job Trigger](user-guide/plugins/devtron-job-trigger.md) * [DockerSlim](user-guide/plugins/docker-slim.md) * [GoLang-migrate](user-guide/plugins/golang-migrate.md) * [Jenkins](user-guide/plugins/jenkins.md) * [Jira Issue Validator](user-guide/plugins/jira-validator.md) * [Jira Issue Updater](user-guide/plugins/jira-updater.md) * [K6 Load Testing](user-guide/plugins/k6-load-testing.md) * [Pull images from container repository](user-guide/plugins/pull-images-from-container-repository.md) * [Semgrep](user-guide/plugins/semgrep.md) * [SonarQube](user-guide/plugins/sonarqube.md) * [SonarQube v1.1.0](user-guide/plugins/sonarqube-v1.1.0.md) * [Vulnerability Scanning](user-guide/plugins/vulnerability-scanning.md) ## Resources * [Glossary](reference/glossary.md) * [Troubleshooting](FAQs/devtron-troubleshoot.md) * [Use Cases](user-guide/use-cases/README.md) * [Devtron Generic Helm Chart To Run CronJob Or One Time Job](user-guide/use-cases/devtron-generic-helm-chart-to-run-cron-job-or-one-time-job.md) * [Connect SpringBoot with Mysql Database](user-guide/use-cases/connect-springboot-with-mysql-database.md) * [Connect Expressjs With Mongodb Database](user-guide/use-cases/connect-expressjs-with-mongodb-database.md) * [Connect Django With Mysql Database](user-guide/use-cases/connect-django-with-mysql-database.md) * [Pull Helm Charts from OCI Registry](user-guide/use-cases/oci-pull.md) * [Telemetry Overview](user-guide/telemetry.md) * [Devtron on Graviton](reference/graviton.md) * [Release Notes](https://github.com/devtron-labs/devtron/releases) --- ### FAQs Devtron Troubleshoot (`docs/FAQs/devtron-troubleshoot.md`) # Troubleshooting Guide We always try to make your experience of using Devtron as smooth as possible but still if you face any issues, follow the troubleshooting guide given below or join our [discord channel](https://discord.gg/jsRG5qx2gp) if you couldn't find the solution for the issue you are facing. #### 1. How to resolve unauthorized errors, while trying to save global configurations like hostname, GitOps etc. after successful devtron installation This occurs most of the time because any one or multiple jobs get failed during installation. To resolve this, you'll need to first check which jobs have failed. Follow these steps: - Run the following command and check which are the jobs with 0/1 completions: ```bash kubectl get jobs -n devtroncd ``` - Note down or remember the names of jobs with 0/1 completions and check if their pods are in running state still or not by running the command: ```bash kubectl get pods -n devtroncd ``` - If they are in running condition, please wait for the jobs to be completed as it may be due to internet issue. And if not in running condition, then delete those incomplete jobs using command: ```bash kubectl delete jobs -n devtroncd ``` - Now download `migrator.yaml` file from our GitHub repository using the command: ```bash wget https://raw.githubusercontent.com/devtron-labs/devtron/main/manifests/yamls/migrator.yaml ``` - Now edit the file you downloaded in step 3 and remove the postgresql-migrator secret resource creation and then apply the yaml file using the command: ```bash kubectl apply -f migrator.yaml -n devtroncd ``` - It will re-create the failed jobs and you’ll see their pods created again. Just wait for a few minutes until the jobs gets completed then you are good to go. You should be able to save your global configurations now. #### 2. Not able to see deployment metrics on production environment or Not able to enable application-metrics or Not able to deploy the app after creating a configmap or secret with data-volume option enabled Update the rollout CRDs to latest version, run the following command: ```bash kubectl apply -f https://raw.githubusercontent.com/devtron-labs/devtron/main/manifests/yamls/rollout.yaml -n devtroncd ``` #### 3. SSO Login not working even after entering correct SSO Credentials ```error: user/UserAuthHandler.go:236","msg":"service err, AuthVerification","err":"no token provided``` Or ```error: Failed to query provider "api/dex": Get "api/dex/.well-known/openid-configuration": unsupported protocol scheme``` Delete devtron pod once to reload the configurations using: ```bash kubectl delete pod -n devtroncd -l app=devtron ``` #### 4. Logs are not Visible on UI while running the build and not even able to abort the same Check if the pods are being created when you start a new build, run the command and look if a new pod is created when you started the build: ```bash kubectl get pods -n devtron-ci ``` If yes, delete kubewatch and devtron pod so that kubewatch can restart and start sharing the logs again: ```bash kubectl delete pod -n devtroncd -l app=devtron; kubectl delete pod -n devtroncd -l app=kubewatch ``` Wait for 5 minutes and then trigger a new build again, if still not resolved then run the following commands one by one ```bash kubectl delete pod -n devtroncd devtron-nats-0 kubectl delete pod -n devtroncd devtron-stan-0 kubectl delete pod -n devtroncd -l app=devtron kubectl delete pod -n devtroncd -l app=kubewatch ``` Again wait for 5 minutes and your issue should be resolved #### 5. Grafana dashboards not visible in App Details page even after adding prometheus endpoint or Graphs showing error panel with id 2 not found If the graphs are not visible check if prometheus is configured properly. Then go to Global Configurations > Clusters & Environments > Click on any environment for the cluster where you added prometheus endpoint and simply click `Update`. If the charts are still not visible, try visiting the url: /grafana?orgId=2 If you see `Not Found` on this page, then follow all the given steps or if the page is accessible and you are getting `panel with id 2 not found` then follow from step 6: 1. Get grafana password using `kubectl -n devtroncd get secret devtron-secret -o jsonpath='{.data.GRAFANA_PASSWORD}' | base64 -d` 2. `kubectl run --rm -it --image quay.io/devtron/k8s-utils:tutum-curl curl` Run this command and it will create a pod for using `curl` 3. Copy the following and change `grafana-password` with your password of grafana and change the value of `prometheusUrl` with your prometheus endpoint ``` cat << EOF grafanaUrl="http://admin:grafana-password@devtron-grafana.devtroncd/grafana" prometheusUrl="http://prometheus.example.com" ORG_ID=$( curl -d '{"name":"devtron-metrics-view"}' -H "Content-Type: application/json" -X POST "${grafanaUrl}/api/orgs" ) echo $ORG_ID curl -X POST "${grafanaUrl}/api/user/using/2"; curl -X PUT -H "Content-Type: application/json" -d '{"homeDashboardId":0,"theme":"light","timezone":"browser"}' "${grafanaUrl}/api/org/preferences"; curl "${grafanaUrl}/api/datasources" -H 'content-type: application/json' -H 'x-grafana-org-id: 2' --data '{"name":"Prometheus-devtron-demo","type":"prometheus","access":"proxy","isDefault":true}' curl "${grafanaUrl}/api/datasources/2" -X PUT \ -H 'content-type: application/json' \ -H 'x-grafana-org-id: 2' \ --data '{"id": 2 , "orgId": 2, "name":"Prometheus-devtron-demo","type":"prometheus","access":"proxy", "url":${prometheusUrl}, "basicAuth":false,"jsonData":{},"version":1}' EOF ``` and run in the pod that we created above in step 2. 4. Now visit /grafana?orgId=2 again and you'll see grafana login page. Login using username `admin` and password from step 1 and check if prometheus url is updated in datasources. If not, update it in the default datasource. 5. Now from devtron UI, update any of the environment again and it's datasource will be created automatically. 6. In Grafana UI you need to be logged in and Go to Dashboards > Manage then click `Import` and Import the given dashboards one by one. ``` https://grafana.com/api/dashboards/13322/revisions/4/download https://grafana.com/api/dashboards/13320/revisions/4/download https://grafana.com/api/dashboards/13325/revisions/4/download https://grafana.com/api/dashboards/13321/revisions/6/download ``` After that, your issue should be resolved and you should be able to see all the graphs on UI. #### 6. Unable to Login Devtron dashboard even if the password is correct If you are not able to login into Devtron dashboard even after giving the correct password, it is possible that the argocd token of previous session has been stored in the cookies and is not able to override the new token that is generated for the new session. If you are facing this issue, follow the steps below - If using Firefox - 1. Goto login page of Devtron and open inspect. 2. Navigate to storage tab in inspect. 3. Click on url where Devtron has been installed under `Cookies` tab and you could see an argocd token with its value, something similar to below image. 4. Now right click on token, and click on `Delete All Session Cookies` option. If using Chrome - 1. Goto login page of Devtron and open inspect. 2. Navigate to Application tab, and under `Storage` tab click on `Cookies`. 3. Click on url under `Cookie` and you would be able tto see an argocd token with its value, as shown in the image below. 4. Now right click on token and click on `delete` option. If using Safari - 1. Goto Safari preferences >> Advanced options and check the show develop menu as shown in the image below. 2. Now goto login page of Devtron and press `option+command+I`. It will open inspect element. 3. Then navigate to `Storage`, click on `Cookies` and you would be able to see an argocd token with its value as shown in the image below. 4. Now right click on token and select `delete` option. After clearing `Cookies`, try again to login, you should be able to login now. #### 7. No charts found in Charts Discover Section In the Devtron's Discover Chart section, if you are not able to see any charts available, goto `Global Configuration` >> `Chart Repositories` and click on `Refresh Chart` at the top-right as shown in the image below. After clicking the button, it might take 4-5mins to show all the charts in `Discover` section depending upon the chart repositories added. #### 8. Not able to update cluster In `Global Configurations` >> `Cluters & Environments`, if you try to update a cluster which has been already added in Devtron, you might get an error as `{"message":"Failed to update datasource. Reload new version and try again"}`. If you are facing such issue, please follow the following steps - 1. Edit the changes you want to make in respective cluster 2. Click on save after making changes and you may get error message stated above. 3. Go to cluster where devtron has been installed and execute - `kubectl -ndevtroncd delete po -l app=devtron` 4. Now refresh the page and you should be able to save it. [Note: If you already have created some environments in that cluster, it needs to be updated again] #### 9. Postgresql is in crashloop with error - Failed to pull image There may be some other pods also in crashloop as they are not able to connect to database. To resolve this issue, you can either [update devtron to latest version](../setup/upgrade/README.md) or run the following commands to fix instantly on the same version you are using: ```bash kubectl patch -n devtroncd statefulset postgresql-postgresql -p '{"spec":{"template":{"spec":{"initContainers":[{"name":"init-chmod-data","image":"quay.io/devtron/minideb:latest"}],"containers":[{"name":"postgresql-postgresql","image":"quay.io/devtron/postgres:11.3.0-debian-9-r28"}]}}}}' ``` Then delete postgresql pod so that it can fetch the updated images: ```bash kubectl delete pod -n devtroncd postgresql-postgresql-0 ``` You can also delete other pods which are in crashloop after postgresql is up and running so that they can restart and connect to postgresql and Devtron will be up and running again in a few moments. #### 10. Unable to fetch the latest commit and not able to trigger auto build. To solve this, bounce the git-sensor-0 pod. ```bash kubectl delete pod -n devtroncd git-sensor-0 ``` #### 11. If you have restricted devtron-service to be accessible on certain IPs only and SSO login isn’t working Whitelist the NAT-gateway IPs of the cluster (There can be multiple NAT-gateways if your cluster is multi-AZ) #### 12. If CPU metrics are not showing but memory metrics are visible in graphs. Do the following:- 1. Go to Grafana and Login with the credentials. 2. Edit the CPU graphs and remove `image!=””` from the query. 3. Save the dashboard. CPU metrics should start showing up in a while. #### 13. If user not able to upload a file more than specific size. `Please use below annotation in ingress` ```bash nginx.ingress.kubernetes.io/proxy-body-size: 100m ``` `Note:- `Where m is MiB. #### 14. If AWS Load balancer controller is unable to provision ALB and getting message in alb controller as unauthorized, attach these IAM policy to the nodegroup IAM Role. [IAM policy](https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.3.1/docs/install/iam_policy.json) #### 15. When app metrics is not coming on grafana and devtron dashboard, set the value of the following parameter as false in kube prometheus stack values. ``` serviceMonitorSelectorNilUsesHelmValues: false ``` #### 16. Unable to deploy metrics-server using chart on devtron To solve Disable certificate validation by passing `--kubelet-insecure-tls` argument to metrics server chart. #### 17. Unable to delete a database from postgres `Description of issue` ERROR: database `` is being accessed by other users DETAIL: There is 1 other session using the database. You have to terminate the connections to the database first, for that you can use the command. ```bash SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname='TARGET_DB'; ``` Then run the command to delete database - `drop databases ` #### 18. Unable to login with admin password or reset devtron admin password `Debug` Run the command for admin credentials and use it for login in dashboard: ```bash kubectl -n devtroncd get secret devtron-secret -o jsonpath='{.data.ADMIN_PASSWORD}' | base64 -d ``` If you are getting an error message of "invalid username or password" or you want to "reset admin password", follow the steps given below: `Solution:` 1. Make sure you are on latest version or atleast you are using devtron version v0.6.9 or above. You can check your devtron version using `kubectl -n devtroncd get installers installer-devtron -o jsonpath='{.status.sync.data}' | grep "^LTAG=" | cut -d"=" -f2-` 1. Take a backup of devtron secret using `kubectl get secret devtron-secret -n devtroncd -o yaml > devtron-secret-backup.yaml` 2. Edit devtron secret using `kubectl edit secret devtron-secret -n devtroncd` and remove the key value pairs of ADMIN_PASSWORD, admin.password and admin.passwordMtime 3. Restart argocd dex server to create new admin password for devtron using `kubectl delete po -n devtroncd -l app.kubernetes.io/name=argocd-dex-server` 4. Run the command given above to get the new admin password #### 19. After installing Devtron using Helm, getting the admin password does not work.(if using windows) `Debug` 'base64' is not recognized as an internal or external command, operable program or batch file. `Solution` The first way to debug is either install base64 encode and decode into your windows machine and use the appropriate cmd to get the admin password. The other way is to get the password in the encoded form using the cmd `kubectl -n devtroncd get secret devtron-secret -o jsonpath='{.data.ACD_PASSWORD}'`, further decode it into plaintext using an online [encoder decoder](https://www.base64decode.org/). #### 20. Getting `UPGRADE FAILED: cannot patch "postgresql-postgresql"` while upgrading Devtron to newer versions `Debug:` 1. Make sure to [annotate and label](../setup/upgrade/devtron-upgrade-0.3.x-0.4.x.md#3.-annotate-and-label-all-the-devtron-resources) all the Devtron resources. 2. Description of error ``` Error: UPGRADE FAILED: cannot patch "postgresql-postgresql" with kind StatefulSet: StatefulSet.apps "postgresql-postgresql" is invalid: spec: Forbidden: updates to statefulset spec for fields other than 'replicas', 'template', 'updateStrategy' and 'minReadySeconds' are forbidden ``` `Solution:` Verify if annotations & labels are set to all k8s resources in `devtroncd` namespace and add `--set components.postgres.persistence.volumeSize=20Gi` parameter in Devtron upgrade command. ```bash helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ -f https://raw.githubusercontent.com/devtron-labs/devtron/main/charts/devtron/devtron-bom.yaml \ --set installer.modules={cicd} --reuse-values \ --set components.postgres.persistence.volumeSize=20Gi ``` #### 21. Configure Blob Storage You can configure blob storage with one of the following: {% tabs %} {% tab title="MinIO storage" %} This configuration will use MinIO for storing logs and cache. ```bash helm repo update helm upgrade devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --reuse-values \ --set installer.modules={cicd} \ --set minio.enabled=true ``` {% endtab %} {% tab title="AWS S3 Bucket" %} This configuration will use AWS S3 bucket for storing build logs and cache. Refer to the `AWS specific` parameters on the [Storage for Logs and Cache](../setup/install/installation-configuration.md#aws-specific) page. * **Configure using S3 IAM policy:** >NOTE: Pleasee ensure that S3 permission policy to the IAM role attached to the nodes of the cluster if you are using the below command. ```bash helm repo update helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ --set installer.modules={cicd} \ --reuse-values \ --set configs.BLOB_STORAGE_PROVIDER=S3 \ --set configs.DEFAULT_CACHE_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CACHE_BUCKET_REGION=us-east-1 \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CD_LOGS_BUCKET_REGION=us-east-1 ``` * **Configure using access-key and secret-key for aws S3 authentication:** ```bash helm repo update helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ --set installer.modules={cicd} \ --reuse-values \ --set configs.BLOB_STORAGE_PROVIDER=S3 \ --set configs.DEFAULT_CACHE_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CACHE_BUCKET_REGION=us-east-1 \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CD_LOGS_BUCKET_REGION=us-east-1 \ --set secrets.BLOB_STORAGE_S3_ACCESS_KEY= \ --set secrets.BLOB_STORAGE_S3_SECRET_KEY= ``` * **Configure using S3 compatible storages:** ```bash helm repo update helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ --set installer.modules={cicd} \ --reuse-values \ --set configs.BLOB_STORAGE_PROVIDER=S3 \ --set configs.DEFAULT_CACHE_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CACHE_BUCKET_REGION=us-east-1 \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CD_LOGS_BUCKET_REGION=us-east-1 \ --set secrets.BLOB_STORAGE_S3_ACCESS_KEY= \ --set secrets.BLOB_STORAGE_S3_SECRET_KEY= \ --set configs.BLOB_STORAGE_S3_ENDPOINT= ``` {% endtab %} {% tab title="Azure Blob Storage" %} This configuration will use Azure Blob Storage for storing build logs and cache. Refer to the `Azure specific` parameters on the [Storage for Logs and Cache](../setup/install/installation-configuration.md#azure-specific) page. ```bash helm repo update helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ --set installer.modules={cicd} \ --reuse-values \ --set secrets.AZURE_ACCOUNT_KEY=xxxxxxxxxx \ --set configs.BLOB_STORAGE_PROVIDER=AZURE \ --set configs.AZURE_ACCOUNT_NAME=test-account \ --set configs.AZURE_BLOB_CONTAINER_CI_LOG=ci-log-container \ --set configs.AZURE_BLOB_CONTAINER_CI_CACHE=ci-cache-container ``` {% endtab %} {% tab title="Google Cloud Storage" %} This configuration will use Google Cloud Storage for storing build logs and cache. Refer to the `Google Cloud specific` parameters on the [Storage for Logs and Cache](../setup/install/installation-configuration.md#google-cloud-storage-specific) page. ```bash helm repo update helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ --set installer.modules={cicd} \ --reuse-values \ --set configs.BLOB_STORAGE_PROVIDER: GCP \ --set secrets.BLOB_STORAGE_GCP_CREDENTIALS_JSON: {\"type\": \"service_account\",\"project_id\": \"\",\"private_key_id\": \"\",\"private_key\": \"\",\"client_email\": \"\",\"client_id\": \"\",\"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\",\"token_uri\": \"https://oauth2.googleapis.com/token\",\"auth_provider_x509_cert_url\": \"https://www.googleapis.com/oauth2/v1/certs\",\"client_x509_cert_url\": \"\"} \ --set configs.DEFAULT_CACHE_BUCKET: cache-bucket --set configs.DEFAULT_BUILD_LOGS_BUCKET: log-bucket ``` {% endtab %} {% endtabs %} #### 22. Rollout is showing error - :111: attempt to index a non-table object(nil) with key 'stableRS' stack traceback: :111: in main chunk [G]: ? This can occur if you are using or recently upgraded to Kubernetes version 1.22 or above and you are using rollout controller version 0.13.0 from chart `devtron-charts/rollout` or `devtron/rollout`. The issue can be because of CRDs which were updated in later versions of rollout chart. 1. Check which chart repo and version of rollout controller are you using on that cluster from Helm Apps section 2. Update the rollout chart version to latest and re-deploy. If your rollout controller is deployed from `devtron-charts` helm repo then change the repo to `devtron/rollout` and then update the version to latest. Also, if devtron helm repo is not showing on your devtron then go to Global Configurations > Chart Repositories and add a new repo with the name `devtron` and url `https://helm.devtron.ai`. Wait for few minutes and then charts from devtron repo will be there on your devtron. This should resolve your issue #### 23. How to resolve if Deployment Status shows Failed or Degraded when you pull images from private container registry If the deployment status shows `Failed` or `Degraded`, then the cluster is not able to pull container image from the private registry. In that case, the status of pod shows `ImagePullBackOff`. The failure of deployment can be one of the following reasons: * Provided credentials may not have permission to pull container image from registry. * Provided credentials may be invalid. You can resolve the `ImagePullBackOff` issue by clicking **How to resolve?** on the **App Details** page. To provide the auto-inject credentials to the specific clusters for pulling the image from the private repository, click **Manage Access** which will take you to the **Container Registries** page. 1. On the **Container Registries** page, select the docker registry and click **Manage**. 2. In the **Auto-inject credentials to clusters**, click **Confirm to edit** to select the specific cluster or all clusters for which you want to auto-inject the credentials to and click **Save**. 3. Redeploy the application after allowing the access. #### 24. Devtron Terminal Connection Timeout Issue on GKE Cluster **Problem:** When connecting to the pod or cluster terminal from the Devtron dashboard on an ingress with gce class in a GKE cluster, the connection gets disconnected after every 30 seconds. This issue is caused by the default timeoutSec value of 30 seconds in the `backendConfig`. **Solution:** To resolve this issue, you can increase the timeoutSec value in the backendConfig and apply the configuration to the Devtron service. Here are the steps to do this: 1. Create a `BackendConfig` yaml file with the increased `timeoutSec` value. For example: ```yaml apiVersion: cloud.google.com/v1beta1 kind: BackendConfig metadata: name: devtron-backendconfig spec: timeoutSec: 1800 ``` you can adjust the `timeoutSec` value in the `backendConfig` as per your specific requirement. This value determines the maximum amount of time the load balancer should wait for a response from the backend before timing out. You can set the timeoutSec value to a higher or lower value based on your use case and the response time of your backend. 2. Apply the BackendConfig to the GKE cluster using the following command: ```bash kubectl apply -f -n devtroncd ``` 3. Add the `cloud.google.com/backend-config: '{"default": "devtron-backendconfig"}'` annotation to the Devtron service with the BackendConfig name. For example: ```yaml apiVersion: v1 kind: Service metadata: name: devtron-service namespace: devtroncd annotations: cloud.google.com/backend-config: '{"default": "devtron-backendconfig"}' ... ``` 4. Save the changes to the Devtron service configuration. With these configuration changes, the Devtron dashboard connection should no longer timeout after 30 seconds, allowing for a more stable and consistent connection. #### 25. Refreshing ArgoCD Certificates When Expired 1. **Edit ArgoCD Secret** Use kubectl edit to edit the ArgoCD secret in the appropriate namespace (devtroncd in this case). Find the data section and delete the lines for tls.crt and tls.key: ```bash kubectl edit secret argocd-secret -n devtroncd ``` 2. **Delete Lines for `tls.crt` and `tls.key`** Once you've opened the ArgoCD secret for editing, find the data section and delete the lines for `tls.crt` and `tls.key`. Save your changes and exit the editor. 3. **Delete ArgoCD Server Pod** Use `kubectl delete pod` to delete the ArgoCD server pod. This will cause a new pod to be created with the updated certificate. ```bash kubectl delete pod -n devtroncd ``` Replace `` with the name of the ArgoCD server pod. 4. **Delete Devtron Pod** Wait for two minutes and then delete the Devtron pod using `kubectl delete pod`. This will force the Devtron pod to use the new certificate. ```bash kubectl delete pod -n devtroncd -l app=devtron ``` This command deletes the Devtron pod in the `devtroncd` namespace with the label `app=devtron`. Following these steps should allow you to refresh the ArgoCD certificates when they have expired. #### 26. Not able to see commits, throwing exit status 128 1. **Save the Git Repository Again** Wait for few minutes and check the build pipeline if commits are visible or not 2. **Check git sensor pod logs** ```yaml kubectl logs -n devtroncd -l app=git-sensor ``` If you still get the same issue, try to bounce the pod and save the git repository again ```yaml kubectl delete po -n devtroncd -l app=git-sensor ``` 3. **Try to clone the git repository with the token you have added for Git Account** In case the cloning fails, you can generate the token, update the Git account in Global Configurations, and try to save the git repository again. #### 27. Git-sensor PVC- disk full **Need to increase the PVC size if you are getting following error:** **Need to check the `Storageclass` by which PVC was provisioned.** Run the following command: ```yaml kubectl get storageclass ``` Check for the field `allowVolumeExpansion`, if it is set to `true`, run the following command and increase the size of the PVC. ```yaml kubectl edit pvc git-volume-git-sensor-0 -n devtroncd ``` However, if the field is `allowVolumeExpansion: false`, set it to `true` and run the above command. Edit the following field: ```yaml spec: capacity: storage: 10Gi # increase as per convenience ``` **Increase the PVC size as per your requirement. This will resolve the issue. If not, then try to bounce the pod using the following command.** ```yaml kubectl delete po -n devtroncd git-sensor-0 ``` #### 28. Getting 'Invalid JSON Document' while deploying via ArgoCD As shown above, Rollout object’s sync status is showing `Failed` and throwing an `Invalid JSON Document` error. This might happen due to manual changes in the Rollout object in the annotation `kubectl.kubernetes.io/last-applied-configuration:`
The value of the above annotation is a JSON. ArgoCD tries to validate that JSON and throws an error if it is invalid. Below is a sample annotation for your reference. ``` kubectl.kubernetes.io/last-applied-configuration: | {"apiVersion":"v1","data":{"foo":"bar"},"kind":"ConfigMap","metadata":{"annotations":{},"creationTimestamp":"2019-08-12T18:38:34Z","labels":{"argocd.argoproj.io/instance":"deploy-test-cd-argo"},"name":"test-cm-1154","namespace":"argo"}} ``` You may take the help of JSON validators to identify where the unintended human error has occured in the JSON. Rectifying the same should resolve this issue. {% hint style="info" %} The annotation `kubectl.kubernetes.io/last-applied-configuration:` is automatically added to each object when you run `kubectl apply`. {% endhint %} #### 29. Helm Charts provided by Bitnami are not visible in Chart Store. Getting 'tls: handshake failure' while deploying Bitnami Charts. `rpc error: code = Unknown desc = Get "https://repo.broadcom.com/bitnami-files/index.yaml": remote error: tls: handshake failure` Follow the below steps if you are getting the above error: * Make sure your [Devtron version](https://devtron-public-asset.s3.us-east-2.amazonaws.com/integrations/about-devtron.png) is 0.7.1 ([check how to upgrade](../setup/upgrade/README.md)). * Navigate to Global Configurations → Chart Repositories → Bitnami * Now in the Bitnami repository, uncheck the **Allow Insecure Connection** and update it as shown below. * Go to Chart Store and initiate the Chart Sync. --- ### Hyperion Devtron (`docs/hyperion/devtron.md`) Dont worry your beloved Hyperion is still supported. It has been merged with Devtron and if you want to install Devtron with same functionality as hyperion [visit here](../setup/install/install-devtron.md). Please reach out to us on [discord](https://discord.devtron.ai/) in case of any queries. --- ### Reference Glossary (`docs/reference/glossary.md`) # Glossary ### Artifacts An immutable blob of data generated as an output after the execution of a job, build, or deployment process, e.g., container image, helm chart. In Devtron, you can view the artifacts in the `Build History` and `Deployment History` of your application. Whereas, job artifacts are visible in the `Run history` of your job. * Once a build is complete, you can view the build artifacts by going to Applications (choose your app) → Build History (tab) → (choose a pipeline and date of triggering the build) → Artifacts (tab). * Once a deployment is complete, you can view the deployment artifacts by going to Applications (choose your app) → Deployment History (tab) → (choose an environment and date of deployment) → Artifacts (tab). * Once a job is complete, you can view the job artifacts by going to Jobs → Run history (tab) → (choose a pipeline and date of triggering the build) → Artifacts (tab). ### ArgoCD Apps ArgoCD Apps are the micro-services deployed using a [GitOps](#gitops) deployment tool named [Argo CD](https://argo-cd.readthedocs.io/en/stable/). If ArgoCD applications are present in your cluster, they will appear in the [ArgoCD Apps listing](../user-guide/applications.md#enabling-argocd-app-listing). ### Base Deployment Template A deployment template is a manifest of the application defining its runtime behavior. You can select one of the default deployment charts or custom deployment charts created by super-admin. It’s a single entry point for you to enter the values, so that when the application is deployed your filled values go to the respective template files (YAML), and accordingly the resources would be created. In Devtron, you get the option to select a base deployment template in the `App Configuration` tab at the time of creating an application. [Read More...](../user-guide/creating-application/deployment-template.md) ### Build Context For building a docker image we require a [Dockerfile](#dockerfile) and a build context. The Dockerfile contains the instructions to build. Context is the path where the build process may refer for getting the files required for build. To build files from the root, use (.) as the build context. Or to refer a subdirectory, enter the path in the format `/myfolder` or `/myfolder/mysubfolder`. If the path is not set, the default path will be the root directory of selected git repository. Go to Applications (choose your app) → App Configuration (tab) → Build Configuration → (choose 'I have a Dockerfile') → Set Build Context. ### Build Pipeline A series of automated steps that transform source code into a deployable container image. In Devtron, you can create a build pipeline by going to Applications (choose your app) → App Configuration (tab) → Workflow Editor → New Workflow. [Read More...](../user-guide/creating-application/workflow/ci-pipeline.md) ### Chart Store A place where all Helm charts are centrally listed for users to deploy applications on Kubernetes. In Devtron, the chart store is available in the left sidebar. You can view, configure, and deploy the existing charts or add new chart repositories too. [Read More...](../user-guide/global-configurations/chart-repo.md) ### Cluster A cluster in Kubernetes refers to a set of connected computers (nodes) that collectively manage containerized applications using Kubernetes. It provides resources and services to run, manage, and scale applications. In Devtron, you can view the list of clusters in 'Global Configurations' as well as 'Resource Browser'. [Read More...](../user-guide/resource-browser.md) ### Commit Hash A unique identifier representing a specific version of source code in a Git [repository](#repo). In Devtron, you can view the commit hash of the top 15 commits you pushed to your branch while selecting the git material under the `Build & Deploy` tab of your application. ### ConfigMaps Kubernetes objects used to store configuration data as key-value pairs. They allow separation of configuration from application code, making it easier to manage and update settings. You can use different ConfigMaps for respective environments too. [Read More...](../user-guide/creating-application/config-maps.md) ### Container/OCI Registry It is a collection of repositories that store container images. It allows developers to store, share, and manage images used to deploy containers. In Devtron, you can add a container registry by going to Global Configurations → Container / OCI Registry. Your CI images are pushed to the container registry you configure. [Read More...](../user-guide/global-configurations/container-registries.md). An OCI-compliant registry can also store artifacts (such as helm charts). Here, OCI stands for Open Container Initiative. It is an open industry standard for container formats and registries. ### Cordoning Temporarily marking a node as unschedulable, preventing new pods from being assigned to it. In Devtron, you can cordon a node by going to Resource Browser → (choose a cluster) → Nodes → (click on a node) → Cordon (available in blue). [Read More...](../user-guide/resource-browser.md#cordon-a-node) ### CronJob CronJob is used to create Jobs on a repeating schedule. It is commonly used for running periodic tasks with no manual intervention. In Devtron, you can view a list of cronjobs by going to Resource Browser → (choose a cluster) → Workloads → CronJob. [Read More...](../user-guide/creating-application/deployment-template/job-and-cronjob.md#2.-cronjob) ### Deployment Charts Devtron offers a variety of ready-made Helm charts for common tasks and functions. If you have a specific need that isn't met by these preconfigured charts, super-admins have the permission to upload their own charts. Once uploaded, these charts become accessible for use by all users on the Devtron platform. [Read More...](../user-guide/global-configurations/deployment-charts.md) ### DaemonSet A Kubernetes object that ensures a specific pod runs on all or certain nodes within a cluster, often used for tasks such as logging or monitoring. In Devtron, you can view a list of DaemonSets by going to Resource Browser → (choose a cluster) → Workloads → DaemonSet. ### Deployment Strategy A defined approach for deploying updates or changes to applications. Devtron supports rolling updates, blue-green deployments, canary releases, and recreate strategy. In Devtron, you can choose a deployment strategy by going to Applications (choose your app) → App Configuration (tab) → Workflow Editor → (edit deployment pipeline) → Deployment Strategy. [Read More...](../user-guide/creating-application/workflow/cd-pipeline.md#deployment-strategies) ### Devtron Agent Your Kubernetes cluster gets mapped with Devtron when you save the cluster configurations. Now, the Devtron agent (rollout controller) must be installed from the chart store on the added cluster so that you can deploy your applications on that cluster. [Read More...](../user-guide/global-configurations/cluster-and-environments.md#installing-devtron-agent) ### Devtron Apps Devtron Apps are the micro-services deployed using Kubernetes-native CI/CD with Devtron. To create one, go to Applications → Create (button) → Custom App. ### Dockerfile A script that defines how to build a Docker [container image](#image). It includes instructions to assemble the image's base, dependencies, and application code. It's recommended that you include a Dockerfile with your source code. However, in case you don't have a Dockerfile, Devtron helps you create one. Go to Applications (choose your app) → App Configuration (tab) → Build Configuration. [Read More...](../user-guide/creating-application/docker-build-configuration.md#build-docker-image-by-creating-dockerfile) ### Draining Evacuating pods from a node before cordoning it, ensuring that running pods are gracefully rescheduled on other nodes. In Devtron, you can drain a node by going to Resource Browser → (choose a cluster) → Nodes → (click on a node) → Drain (available in blue). [Read More...](../user-guide/resource-browser.md#drain-a-node) ### Environment You can deploy your application to one or more environments (e.g., development, testing, production). In Devtron, Environment = [Cluster](#cluster) + [Namespace](#namespace). For a given application, you cannot have multiple CD pipelines for an environment. For e.g., if an application named 'test-app' is deployed on an environment named 'test-environment', you cannot create another deployment (CD) pipeline for the same app and environment. Your application can have different deployment configurations for respective environments. For e.g., the number of [ReplicaSet](#replicaset) could be 2 for staging environment, whereas it could be 5 for production. Similarly, the CPU and memory resources can be different for each environment. This is possible through Environment Overrides. [Read More...](../user-guide/creating-application/environment-overrides.md) ### External Links You can add external links related to the application. For e.g., you can add Prometheus, Grafana, and many more to your application by going to Global Configurations → External Links. [Read More...](../user-guide/global-configurations/external-links.md) ### FluxCD Apps FluxCD Apps are the micro-services deployed using a [GitOps](#gitops) deployment tool named [Flux CD](https://fluxcd.io/). If FluxCD applications are present in your cluster, they will appear in the [FluxCD Apps listing](../user-guide/applications.md#view-fluxcd-app-listing). ### GitOps A methodology for managing and automating Kubernetes deployments using Git repositories as the source of truth. Changes to the desired state of the cluster are driven by Git commits. [Read More...](../user-guide/global-configurations/gitops.md) ### Helm Apps Apps deployed using Helm Chart from the `Chart Store` section of Devtron. In Devtron, you can view such apps under a tab named `Helm Apps` in the Applications section. To create one, go to Applications → Create (button) → From Chart store. ### Helm Charts/Packages Packages that contain pre-configured Kubernetes resources and configurations. Helm charts are used to define, install, and upgrade applications on Kubernetes clusters. Refer [chart store](#chart-store) to know more. ### Image A packaged and standalone software that contains the code and dependencies needed to run a containerized application. Using Devtron, you can build a container image of your application, push it to a container registry, and deploy it on your Kubernetes cluster. Since images are platform-agnostic, you don't have to worry about compiling your application to work on different systems. With Devtron, you can enable automatic image builds and vulnerability scanning whenever you make edits to your source code. [Read More...](../user-guide/creating-application/workflow/ci-pipeline.md) You can also view the list of image builds while preparing your deployment in the `Build & Deploy` tab of your application (provided the CI stage is successful). ### Job In Devtron, there is a job that is very similar to Kubernetes job. A Kubernetes job is an object used to create one or more pods to complete a specific task or job and then terminate. If you are a super-admin in Devtron, you can view Jobs in the sidebar. ### Load Balancer Distributes incoming network traffic across multiple instances or nodes to ensure efficient resource utilization and improved performance. In Kubernetes, Load Balancer is a service type. Behind the scenes, the managed Kubernetes service connects to the load balancer service of the respective cloud service provider and creates a load balancer, mapping it to the Kubernetes service. GKE and AKS provide the public IP of the Load Balancer as the service endpoint, while in the case of EKS, it provides a non-customizable DNS name. ### Manifest A manifest is a YAML file that describes each component or resource of your Kubernetes object and the state you want your cluster to be in once applied. A manifest specifies the desired state of an object that Kubernetes will maintain when you apply the manifest. In Devtron, you can view the manifest of K8s resources under `App Details` and also under `Resource Browser`. ### Material In Git Repo, the source code of your application in a given commit is referred as material. The option to choose a Git material will be available in the CI stage under the `Build & Deploy` tab of your application. [Read More...](../user-guide/jobs/triggering-job.md#triggering-job-pipeline.md) ### Namespace A namespace is a way to organize and isolate resources within a Kubernetes cluster. It provides a logical separation between different applications or environments within a cluster. In Devtron, you can view a list of namespaces by going to Resource Browser → (choose a cluster) → Namespaces. ### Node Taint A setting applied to a node that influences the scheduling of pods. Taints can restrict which pods are allowed to run on the node. In Devtron, you can edit the taints of a node by going to Resource Browser → (choose a cluster) → Nodes → (click on a node) → Edit taints (available in blue). [Read More...](../user-guide/resource-browser.md#taint-a-node) ### NodePort A Kubernetes service type that exposes a port on each node in the cluster, making a service accessible externally. ### Nodes The physical or virtual machines that make up a Kubernetes cluster, where containers are scheduled to run. In Devtron, you can view nodes by going to Resource Browser → (choose a cluster) → Nodes. [Read More...](../user-guide/resource-browser.md#nodes) ### Objects Kubernetes objects are the building blocks that define and manage your applications running on the platform. They are also known as 'Resources' or 'Kinds'. This includes nodes, pods, deployment, cronjob, configmap, and many more. Devtron's [Resource Browser](../user-guide/resource-browser.md) helps you manage all such objects present in your clusters. ### Pod The smallest deployable unit in Kubernetes, consisting of one or more containers that share storage and network resources within the same context. In Devtron, you can view a list of Pods by going to Resource Browser → (choose a cluster) → Workloads → Pod. In Devtron, you can create a pod by going to Resource Browser → Create Resource (button). ### Pre-build Actions or processes performed before the actual image-building process in a containerized application's deployment pipeline, e.g., Jira Issue Validator. In Devtron, you can configure pre-build actions by going to Applications (choose your app) → App Configuration (tab) → Workflow Editor → (edit build pipeline) → Pre-build stage (tab) → Add task (button). [Read More...](../user-guide/creating-application/workflow/ci-build-pre-post-plugins.md#configuring-pre-post-build-tasks) ### Post-build Actions or processes performed after the [image](#image) building process in a containerized application's deployment pipeline, e.g., email notification about build status. In Devtron, you can configure post-build actions by going to Applications (choose your app) → App Configuration (tab) → Workflow Editor → (edit build pipeline) → Post-build stage (tab) → Add task (button). [Read More...](../user-guide/creating-application/workflow/ci-build-pre-post-plugins.md#configuring-pre-post-build-tasks) ### Pre-deployment Steps, scripts, or configurations executed before deploying a new version of an application to a Kubernetes cluster. In Devtron, you can configure pre-deployment actions by going to Applications (choose your app) → App Configuration (tab) → Workflow Editor → (edit deployment pipeline) → Pre-deployment stage (tab) → Add task (button). [Read More...](../user-guide/creating-application/workflow/cd-pipeline.md#3.-pre-deployment-stage) ### Post-deployment Actions, checks, or processes carried out after a new version of an application is successfully deployed to a Kubernetes cluster, e.g., Jira Issue Updater. In Devtron, you can configure post-deployment actions by going to Applications (choose your app) → App Configuration (tab) → Workflow Editor → (edit deployment pipeline) → Post-deployment stage (tab) → Add task (button). [Read More...](../user-guide/creating-application/workflow/cd-pipeline.md#post-deployment-stage) ### ReplicaSet A Kubernetes object responsible for maintaining a specified number of replica pods, ensuring high availability and desired scaling. In Devtron, you can view the deployed ReplicaSet by going to Applications (choose your app) → App Details (tab) → K8s Resources (under Application Metrics section). ### Repo Abbreviation for "repository". It could either signify a Git repo, container repo, or helm repo. **Git repo** - A version control system (like Git) that stores and manages source code and other project assets. Once you create a git repo, you can add it in Applications (choose your app) → App Configuration (tab) → Git Repository → Add Git Repository. **Container repo** - A collection of [container images](#image), e.g., Docker repository. **Helm repo** - Also known as chart repo. You can add it in Global Configurations. ### Rollback The process of reverting a deployment to a previously known working version in case of errors or issues with the current version. In Devtron, you can rollback a deployment by going to Applications (choose your app) → Build & Deploy (tab) → (click the rollback icon in the deployment pipeline). [Read More...](../user-guide/deploying-application/rollback-deployment.md) ### Secrets Kubernetes objects used to store sensitive information, such as passwords and API keys. Secrets are encoded and can be mounted as files or environment variables in pods. In Devtron, you get the option to add secrets in the `App Configuration` tab of your application. You can use different secrets for respective environments too. [Read More...](../user-guide/creating-application/secrets.md) ### Security Context A Kubernetes resource configuration that defines security settings and permissions for pods and containers. A security context defines privilege and access control settings for a pod or container. [Read More...](../user-guide/creating-application/deployment-template/deployment.md#security-context) ### StatefulSet A Kubernetes object designed for managing stateful applications, maintaining stable network identities and storage across pod rescheduling. In Devtron, view the list of StatefulSets by going to Resource Browser → (choose a cluster) → Workloads → StatefulSet. [Read More...](../user-guide/creating-application/deployment-template/statefulset.md) ### Target Platform The operating system and architecture for which the [container image](#image) will be built, e.g., ubuntu/arm64, linux/amd64. The image will only be compatible to run only on the target platform chosen in the build configuration. In Devtron, you can choose the target platform by going to Applications (choose your app) → App Configuration (tab) → Build Configuration → (create build pipeline) → (click `Allow Override` button) → Target platform for the build (section). [Read More...](../user-guide/creating-application/docker-build-configuration.md) --- ### Reference Graviton (`docs/reference/graviton.md`) # Devtron On Graviton In cloud computing, optimizing performance, efficiency, and cost-effectiveness is an endless pursuit. As technology evolves, new opportunities arise to achieve these goals. One such advancement is the introduction of AWS Graviton instances, which are rapidly gaining prominence as a game-changer in cloud architecture. AWS Graviton instances are a family of Arm-based processors developed by Amazon Web Services (AWS). These processors are designed to deliver high performance while maintaining energy efficiency. We are thrilled to announce that Devtron seamlessly supports Graviton instances, and it's fantastic to note the substantial benefits we've experienced in terms of resource utilization. With 5% less memory utilization and 2% less CPU utilization compared to AMD instances, underscore the advantages of leveraging Graviton architecture. This not only translates into cost savings but also contributes to a more environmentally sustainable cloud infrastructure. ## Installation To install Devtron on graviton-cluster, refer this [link](../setup/install/install-devtron-with-cicd.md#install-multi-architecture-nodes-arm-and-amd) ## Inferences ### 1. Reduced Build Time The utilization of Graviton machines for building Graviton architecture has led to reduction in build time by approximately 30% and less CPU/Memory utilization within Devtron. **AMD Build** **ARM Build**
### 2. Similar Performance Experience Devtron's equivalent performance to that of other architectures, all while exhibiting slightly lower resource utilization.
### 3. Less Resource Utilization Notably, Graviton instances exhibit slightly lower resource utilization compared to AMD Nodes, users can take the opportunity for cost savings in cloud operations. We have attached some snapshots of the resource utilization for the critical micro-services on Devtron having the GitOps option enabled and more than 115 applications deployed. For an accurate performance comparison, We have used a single-node cluster for both architectures (AMD and ARM). #### 1. orchestrator **AMD-Based** **ARM-Based** #### 2. argocd-server **AMD-Based** **ARM-Based** #### 3. argocd-application-controller **AMD-Based** **ARM-Based** #### 4. argocd-repo-server **AMD-Based** **ARM-Based** --- ### Setup Start Using (`docs/setup/start-using.md`) # Start Using devtron #### configure docker registry Please [setup docker registry](../user-guide/global-configurations/docker-registries.md) before deploying application. ## Deploying Applications ### deploy spring boot app Please use [this spring boot app](https://github.com/nishant-d/demo.git) repo for reference and follow steps described in the video {% embed url="https://www.youtube.com/watch?v=Tz01aKDqBAI&feature" caption="" %} ### deploy helm chart for deploying helm chart follow [helm chart installation guide](../user-guide/deploy-chart/) --- ### User Guide App Labels (`docs/user-guide/app-labels.md`) # App Labels Tagging Overview ============ This feature helps you to tag labels on applications, this will help you to filter out and categories your applications. labels are combinations of key value pairs, each application may have multiple labels. every app must have unique key. ### 1. Add labels on creation of application Login with valid credentials and go to `Applications` and click on right top button `Add New App` and fill the required values. Labels are optionals and can be entered `key:values` format. multiple labels can be added without repeating `key` name. ### 2. Application meta info Login with valid credentials and go to `Applications` and click on any application and go to detail page, click on top left button next to application name `?`. This will open show you the applications meta details like project, labels associated with it. ### 3. Edit Labels to existing apps We also add or remove labels for app from here. ### 3. Label Payload * `id` : integer unique label id * `appId` : integer application id * `key` : string key is the part of label stored individually in db. * `value` : string value is the part of label stored individually in db. --- ### User Guide Application Groups (`docs/user-guide/application-groups.md`) # Application Groups ## Introduction Application groups in Devtron streamline the deployment of microservices by enabling you to build and deploy multiple applications simultaneously. This feature is particularly beneficial when your microservices are interdependent, as a change in one service often triggers the need to redeploy others. {% hint style="info" %} Only one application group would exist for each [environment](../reference/glossary.md#environment). You cannot group applications belonging to different environments. {% endhint %} --- ## Accessing Application Groups 1. From the left sidebar, go to **Application Groups** 2. You will see a list of environments. Select the environment to view the application group. 3. The application group would contain the applications meant for deployment in the chosen environment. As you can see, it has similar options as available under [Applications](./applications.md): * Overview * Build & Deploy * Build history * Deployment history * Configurations {% hint style="info" %} Users need to have [View only permission](../user-guide/global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the environment and applications) to view all the applications within a group. {% endhint %} First, we will walk you through the [key features](#key-features) of Application Groups, followed by [additional features](#additional-features) that will help you perform bulk actions. --- ## Key Features ### Building Application Images The **Build & Deploy** tab of your application group enables you to trigger the [CI builds](../reference/glossary.md#image) of one or more applications in bulk. 1. Select the applications using the checkboxes and click the **Build Image** button present at the bottom. 2. The `Build image` screen opens. Select the application and the [commit](../reference/glossary.md#commit-hash) for which you want to trigger the CI build. {% hint style="info" %} ### Tip Adding [image labels](./deploying-application/image-labels-and-comments.md) can help you quickly locate the container image from the list of images shown in Application Groups. {% endhint %} 3. Similar to application, you can also [pass build parameters](./deploying-application/triggering-ci.md#passing-build-parameters) in application groups before triggering the build. {% hint style="info" %} Passing build parameters feature is only available in {% endhint %} * Go to the **Parameters** tab. * Click **+ Add parameter**. * Enter your key-value pair as shown below. * You may follow the above steps for other applications too, and then click **Start Build**. 4. The builds will initiate, following which, you can close the `Build image` screen. {% hint style="info" %} Users need to have [Build and deploy permission](../user-guide/global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the environment and applications) to trigger the build {% endhint %} ### Changing Configurations The **Configurations** tab of your application group allows you to configure the following: * [Deployment template](../reference/glossary.md#base-deployment-template) * [ConfigMaps](../reference/glossary.md#configmaps) * [Secrets](../reference/glossary.md#secrets) As shown below, you can handle the configurations of more than one application from a single screen. {% hint style="info" %} Users need to have [Admin role](../user-guide/global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the environment and applications) to change their configuration. Please note, you might not be able to change the values of locked keys in deployment template. Refer [Lock Deployment Configuration](./global-configurations/lock-deployment-config.md) to know more. {% endhint %} ### Deploying Applications The **Build & Deploy** tab of your application group helps you deploy one or more applications in bulk. 1. Select the applications using the checkboxes and click the **Deploy** button present at the bottom. 2. Select the desired container image that you want to deploy for respective application. Repeat the step for other applications too, and then click **Deploy**. 3. The deployment will be initiated, following which, you can close the screen as shown below. Once the deployment is successful, the pipelines will show `Succeeded`. {% hint style="info" %} Users need to have [Build and deploy permission](../user-guide/global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the environment and applications) to initiate the deployment {% endhint %} --- ## Additional Features ### Hibernating and Unhibernating Apps {% hint style="warning" %} ### Who Can Perform This Action? Users need to have [Build & deploy permission](./global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the environment and application) to hibernate or unhibernate applications. {% endhint %} Since every application comes with an option to hibernate, the same is true for application groups. Using application group, you can hibernate one or more applications belonging to the same environment if you do not want them to consume resources (replica count will be set to 0). In other words, you can hibernate running applications or unhibernate hibernated applications as per your requirement. #### Hibernation Process 1. In the `Overview` page of your application group, use the checkboxes to choose the applications you wish to hibernate, and click the **Hibernate** button. 2. Confirm the hibernation. 3. Hibernation will initiate as shown below. You may close the window. Your applications pods would be scaled down and would stop incurring costs. #### Unhibernation Process 1. In the same `Overview` page, you can use the checkboxes to choose the hibernated applications you wish to unhibernate, and click the **Unhibernate** button. 2. Confirm the unhibernation. 3. Unhibernation will initiate as shown below. You may close the window. Your applications would be up and running in some time. ### Restart Workloads {% hint style="warning" %} ### Who Can Perform This Action? Users need to have [Build & deploy permission](./global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the environment and application) to restart workloads in bulk. {% endhint %} Restarting workloads might be necessary if you want your new code or configuration to come into effect, or you are experiencing issues like crashing of pods. Using application group, you can select the workloads (i.e., Pod, Deployment, ReplicaSet, etc.) of specific applications and restart them. 1. Use the checkboxes to choose the applications whose workloads you wish to restart, and click the **Restart Workload** button. 2. Next to the application, click the workload dropdown to view all the individual workloads of an application. Choose only the ones you wish to restart. Moreover, you can easily select, deselect, or choose multiple workloads as shown below. 3. Click **Restart Workloads**. Restarting workloads might take time depending on the number of applications. ### Filtering Applications Assume you have multiple applications (maybe 10, 50, 100, or more) showing up in an application group. If you want to limit your operations (build/deploy/other) to a specific set of applications, the filter feature will help you narrow down the list. Thus, you will see only those applications you select from the filter (be it on the `Overview` page, `Build & Deploy` page, and so on.) 1. Click the filter next to the application group as shown below. 2. The filter will show all the applications present in the group. Click to select the relevant ones. 3. The filter narrows down the list of applications as shown below. 4. (Optional) If required, you can save the filter for future use by clicking **Save selection as filter**. 5. Add a name and description to the filter to help you know its purpose, and click **Save**. Now when you access the application group, your saved filter will be visible on top. {% hint style="info" %} ### Permissions #### 1. Creating a filter Users can create a filter if they have Admin/Manager access on all selected applications. * **Case 1**: User has Admin/Manager access on all selected applications User will be able to create a filter with all selected applications. * **Case 2**: User does not have Admin/Manager access on all selected applications User will not be able to create a filter. * **Case 3**: User selected 4 applications but has Admin/Manager access for only 2 of them User should be able to create filter with these 2 applications. #### 2. Editing a saved filter Users can edit a saved filter if they have Admin/Manager access on all applications in the saved filter. #### 3. Deleting a saved filter Users can delete a saved filter if they have Admin/Manager access on all applications in the saved filter. {% endhint %} ### Changing Branch {% hint style="warning" %} ### Who Can Perform This Action? Users need to have [Admin role](../user-guide/global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the environment and applications) to update their branch. {% endhint %} Assume you have a few applications whose [build pipelines](../reference/glossary.md#build-pipeline) fetch from the `main` branch of your code repository. However, you decided to maintain a `master` branch, and you want all the upcoming CI builds to consider the `master` branch as the source. Devtron provides you the option to change the branch at both levels—individual application as well as application group. 1. In the **Build & Deploy** tab of your application group, select the intended applications and click the **Change Branch** button present at the bottom. 2. Enter the new branch name. If your build pipeline has `Branch Regex` as the Source Type, you must ensure your new branch name matches the regex (regular expression) provided in that build pipeline. Once done, click **Update Branch**. --- ### User Guide Applications (`docs/user-guide/applications.md`) # Applications {% hint style="warning" %} Configure [Global Configurations](./global-configurations/README.md) first before creating an application or cloning an existing application. {% endhint %} ## Introduction The **Applications** page helps you create and manage your microservices, and it majorly consists of the following: * [Application Listing](#application-listing) * [Create Button](#create-button) * [Other Options](#other-options) ### Application Listing You can view the app name, its status, environment, namespace, and many more upfront. The apps are segregated into: [Devtron Apps](../reference/glossary.md#devtron-apps), [Helm Apps](../reference/glossary.md#helm-apps), [ArgoCD Apps](../reference/glossary.md#argocd-apps), and [FluxCD Apps](../reference/glossary.md#fluxcd-apps). ### Create Button You can use this to: * [Create a Devtron app](./create-application.md) * [Create a Helm app](./deploy-chart/deployment-of-charts.md) * [Create a Job](./jobs/create-job.md) ### Other Options There are additional options available for you: * **Search and filters** to make it easier for you to find applications. * **Export CSV** to download the data of Devtron apps (not supported for Helm apps and Argo CD apps). * **Sync button** to refresh the app listing. --- ## View ArgoCD App Listing {% hint style="warning" %} ### Who Can Perform This Action? Users need super-admin permission to view/enable/disable the ArgoCD listing. {% endhint %} ### Preface In Argo CD, a user manages one dashboard for one ArgoCD instance. Therefore, with multiple ArgoCD instances, the process becomes cumbersome for the user to manage several dashboards. With Devtron, you get an entire Argo CD app listing in one place. This listing includes: * Apps deployed using [GitOps](../reference/glossary.md#gitops) on Devtron * Other Argo CD apps present in your cluster ### Advantages Devtron also bridges the gap for ArgoCD users by providing additional features as follows: * **Resource Scanning**: You can scan for vulnerabilities using Devtron's [resource scanning](../user-guide/security-features.md#from-app-details) feature. [](https://devtron.ai/pricing) * **Single-pane View**: All Argo CD apps will show details such as their app status, environment, cluster, and namespace together in one dashboard. * **Feature-rich Options**: Clicking an Argo CD app will give you access to its logs, terminal, events, manifest, available resource kinds, pod restart log, and many more. {% hint style="info" %} ### Additional References [ArgoCD: Standalone Configuration vs Devtron Configuration](https://devtron.ai/blog/argocd-standalone-configuration-vs-devtron-configuration/#argocd-installation-and-configuration) {% endhint %} ### Prerequisite The cluster in which Argo CD apps exist should be added in **Global Configurations** → **Clusters and Environments** ### Feature Flag > **`ENABLE_EXTERNAL_ARGO_CD: "true"`** ### Enabling ArgoCD App Listing {% embed url="https://www.youtube.com/watch?v=4KyYnsAEpqo" caption="Enabling External ArgoCD Listing" %} 1. Go to the **Resource Browser** of Devtron. 2. Select the cluster (in which your Argo CD app exists). 3. Type `ConfigMap` in the 'Jump to Kind' field. 4. Search for `dashboard-cm` using the available search bar and click it. 5. Click **Edit Live Manifest**. 6. Set the feature flag **ENABLE_EXTERNAL_ARGO_CD** to **"true"** 7. Click **Apply Changes**. 8. Go back to the 'Jump to Kind' field and type `Pod`. 9. Search for `dashboard` pod and use the kebab menu (3 vertical dots) to delete the pod. 10. Go to **Applications** and refresh the page. A new tab named **ArgoCD Apps** will be visible. 11. Select the cluster(s) from the dropdown to view the Argo CD apps available in the chosen cluster(s). --- ## View FluxCD App Listing {% hint style="warning" %} ### Who Can Perform This Action? Users need super-admin permission to view/enable/disable the FluxCD listing. {% endhint %} ### Preface Flux CD doesn't have any official dashboard; however, Devtron supports the listing of your [Flux CD](https://fluxcd.io/) apps in one dashboard. Here, the [advantages](#advantages) are same as those of [ArgoCD app listing](#view-argocd-app-listing). ### Prerequisite The cluster in which Flux CD apps exist should be added in **Global Configurations** → **Clusters and Environments** ### Feature Flag > **`FEATURE_EXTERNAL_FLUX_CD_ENABLE: "true"`** ### Enabling FluxCD App Listing {% hint style="info" %} ### Tip You may refer the steps mentioned in the [Enabling ArgoCD App Listing](#enabling-argocd-app-listing) section since the procedure is similar. {% endhint %} Using Devtron's Resource Browser, add the [feature flag](#feature-flag-1) in the Dashboard ConfigMap as shown below. After successfully executing all the steps, a new tab named **FluxCD Apps** will be visible. Select the cluster(s) from the dropdown to view the Flux CD apps available in the chosen cluster(s). (Optional) Once you choose cluster(s), you may use the **Template Type** dropdown to further filter your Flux CD app listing based on its type, i.e., [Kustomization](https://fluxcd.io/flux/components/kustomize/kustomizations/) or [Helmrelease](https://fluxcd.io/flux/components/helm/helmreleases/). Click any Flux CD app to view its details as shown below. --- ### User Guide Bulk Update (`docs/user-guide/bulk-update.md`) # Bulk Updates This feature helps you to update Deployment Template, ConfigMaps & Secrets for multiple apps in one go! You can filter the apps on the basis of environments, global flag, and app names(we provide support for both substrings included and excluded in the app name). ## Overview Need to make some common changes across multiple devtron applications? **Bulk Edit** allows you to do that.
Eg. You can change the value for `MaxReplicas` in Deployment Templates of multiple Devtron applications or you can add key-value pairs in multiple ConfigMaps & Secrets. However, you might not be able to change the values of locked keys. Refer [Lock Deployment Configuration](./global-configurations/lock-deployment-config.md) to know more. ## Support Bulk edit is currently supported for: - Deployment Template - ConfigMaps - Secrets ## Steps: 1. Click on the `Bulk Edit` option in the main navigation. This is where you can write and execute scripts to perform bulk updates in Devtron objects. 2. To help you get started, a script template is provided under the `See Samples` section. 3. Copy and Paste the `Sample Script` in the code editor and make desired changes. Refer `Payload Configuration` in the Readme to understand the parameters. ### Example Example below will select all applications having `abc and xyz` present in their name and out of those will exclude applications having `abcd and xyza` in their name. Since global flag is false and envId 23 is provided, it will make changes in envId 23 and not in global deployment template for this application. If you want to update globally then please set `global: true`. If you have provided an envId but deployment template, configMap or secret is not overridden for that particular environment then it will not apply the changes. Also, of all the provided names of configMaps/secrets, for every app & environment override only the names that are present in them will be considered. ### Sample Script This is the piece of code which works as the input and has to be pasted in the code editor for achieving bulk updation task. ``` apiVersion: batch/v1beta1 kind: Application spec: includes: names: - "%abc%" - "%xyz%" excludes: names: - "%abcd%" - "%xyza%" envIds: - 23 global: false deploymentTemplate: spec: patchJson: '[{ "op": "add", "path": "/MaxSurge", "value": 1 },{"op": "replace","path":"/GracePeriod","value": "30"}]' configMap: spec: names: - "configmap1" - "configmap2" - "configmap3" patchJson: '[{ "op": "add", "path": "/{key}", "value": "{value}" },{"op": "replace","path":"/{key}","value": "{value}"}]' secret: spec: names: - "secret1" - "secret2" patchJson: '[{ "op": "add", "path": "/{key}", "value": "{value}" },{"op": "replace","path":"/{key}","value": "{value}"}]' ``` ### Payload Configuration The following tables list the configurable parameters of the Payload component in the Script and their description along with example. Also, if you do not need to apply updates on all the tasks, i.e. Deployment Template, ConfigMaps & Secrets, leave the Spec object empty for that respective task. | Parameter | Description | Example | | -------------------------- | ---------------------------------- | ---------------------------------------------------------- | |`includes.names ` | Will filter apps having exact string or similar substrings | `["app%","%abc", "xyz"]` (will include all apps having `"app%"` **OR** `"%abc"` as one of their substring, example - app1, app-test, test-abc etc. **OR** application with name xyz) | | `excludes.names` | Will filter apps not having exact string or similar substrings. | `["%z","%y", "abc"]` (will filter out all apps having `"%z"` **OR** `"%y"` as one of their substring, example - appz, test-app-y etc. **OR** application with name abc) | | `envIds` | List of envIds to be updated for the selected applications. | `[1,2,3]` | | `global` | Flag to update global deployment template of applications. | `true`,`false` | | `deploymentTemplate.spec.patchJson` | String having the update operation(you can apply more than one changes at a time). It supports [JSON patch ](http://jsonpatch.com/) specifications for update. | `'[ { "op": "add", "path": "/MaxSurge", "value": 1 }, { "op": "replace", "path": "/GracePeriod", "value": "30" }]'` | | `configMap.spec.names` | Names of all ConfigMaps to be updated. | `configmap1`,`configmap2`,`configmap3` | | `secret.spec.names` | Names of all Secrets to be updated. | `secret1`,`secret2`| | `configMap.spec.patchJson` / `secret.spec.patchJson` | String having the update operation for ConfigMaps/Secrets(you can apply more than one changes at a time). It supports [JSON patch ](http://jsonpatch.com/) specifications for update. | `'[{ "op": "add", "path": "/{key}", "value": "{value}" },{"op": "replace","path":"/{key}","value": "{value}"}]'`(Replace the `{key}` part to the key you want to perform operation on & the `{value}`is the key's corresponding value |
4. Once you have modified the script, you can click on the `Show Impacted Objects` button to see the names of all applications that will be modified when the script is `Run`. 5. Click on the `Run` button to execute the script. Status/Output of the script execution will be shown in the `Output` section of the bottom drawer. --- ### User Guide Cloning Application (`docs/user-guide/cloning-application.md`) # Cloning Application Click on `Create New` and the select `Custom app` to create a new application. As soon you click on `Custom app`, you will get a popup window on screen where you have to enter `app name` and `project` for the application. there are two radio buttons present on the popup window, one is for `Blank app` and another one is for `Clone an existing app`. For cloning an existing application, select the second one. After this, one more drop-down will appear on the window from which you can select the application that you want to clone. For this, you will have to type minimum three character to see the matching results in the drop-down. After typing the matching characters, select the application that you want to clone. You also can add additional information about the application (eg. `created by`, `Created on`) using `tags` (only key:value allowed). | Key | Description | | :--- | :--- | | `App Name` | Name of the new app you want to Create | | `Project` | Project name | | `Select an app to clone` | Select the application that you want to clone | | `Tags` | Additional information about the application | Now click on `Clone App` to clone the selected application. New application with a duplicate template is created. {% hint style="warning" %} When cloning an application with GitOps configuration, the configuration itself is not copied. To set up the configuration for your new application, refer [GitOps Configuration](./creating-application/gitops-config.md) guide. {% endhint %} --- ### User Guide Command Bar (`docs/user-guide/command-bar.md`) # Command bar ## Why command bar? The command bar is designed to enable you to navigate across the devtron dashboard without having to click around the screen. Top-level categories (eg. app, chart, security, global-config) are auto-filled depending upon your location on the Devtron dashboard. > You can clear the top-level category to navigate within other category locations. ### Shortcuts | Action | Keys | | :--- | :--- | | Open Command bar | `Cmd/Ctrl` + `/` | | Navigate | `↓` `↑`| | Explore nested options | `→` | | Navigate to a screen | `Enter` |
### How to use the command bar (Eg. Navigate to Workflow editor of an App.)

### Steps to use 1. Open command bar by clicking the 🔍 search icon on left navbar or pressing `Cmd/Ctrl` + `/` 2. Start typing the app name you're looking for. 3. Navigate using `↓` `↑` between the matching results and press `→` to view nested options. > Note: Pressing Enter on a highlighted option will navigate to the selected page location. 4. In this case, `app / dashboard / configure / workflow-editor` will navigate to the Workflow editor in dashboard application. Similarly, you can use the command bar to navigate around the Devtron dashboard without a click. We would love to know your experience with the command bar. Jump in to the [Devtron Discord Community](https://discord.gg/jsRG5qx2gp) --- ### User Guide Create Application (`docs/user-guide/create-application.md`) # Create a New Application * On the Devtron dashboard, select **Applications**. * On the upper-right corner of the screen, click **Create**. * Select **Custom app** from the drop-down list. A new application can be created from one of the following options: * Custom App * [From Chart Store](../user-guide/deploy-chart/README.md) ## Create Custom App To create a new application from the custom app, select **Custom app**. * In the **Create application** window, enter an **App Name** and select a **Project**. * Select either:
  • **Create from scratch** to create an application from scratch, or
  • **Clone existing application** to clone an existing application.
* If you select **Create from scratch**, select the project from the drop-down list.
`Note`: You have to add [project under Global Configurations](./global-configurations/projects.md). Only then, it will appear in the drop-down list here. * If you select **Clone existing application**, select an app you want to clone from and the project from the drop-down list.
`Note`: You have to add [project under Global Configurations](./global-configurations/projects.md). Only then, it will appear in the drop-down list here.
## Tags `Tags` are key-value pairs. You can add one or multiple tags in your application. **Propagate Tags** When tags are propagated, they are considered as labels to Kubernetes resources. Kubernetes offers integrated support for using these labels to query objects and perform bulk operations e.g., consolidated billing using labels. You can use these tags to filter/identify resources via CLI or in other Kubernetes tools. * Click `+ Add tag` to add a new tag. * Click the symbol on the left side of your tag to propagate a tag.
`Note`: Dark grey colour in symbol specifies that the tags are propagated. * To remove the tags from propagation, click the symbol again. * Click `Save`. --- ### User Guide Debugging Deployment And Monitoring (`docs/user-guide/debugging-deployment-and-monitoring.md`) # Debugging Deployment And Monitoring If the deployment of your application is not successful, then debugging needs to be done to check the cause of the error. This can be done through `App Details` section which you can access in the following way:- Applications->AppName->App Details Over here, you can see the status of the app as Healthy. If there are some errors with deployment then the status would not be in a Healthy state. ### Events Events of the application are accessible from the bottom left corner. Events section displays you the events that took place during the deployment of an app. These events are available until 15 minutes of deployment of the application. ### Logs Logs contain the logs of the Pods and Containers deployed which you can use for the process of debugging. ### Manifest The Manifest shows the critical information such as Container-image, restartCount, state, phase, podIP, startTime etc. and status of the pods deployed. ### Deleting Pods You might run into a situation where you need to delete Pods. You may need to bounce or restart a pod. Deleting a Pod is not an irksome task, it can simply be deleted by Clicking on `Delete Pod`. Suppose you want to setup a new environment, you can delete a pod and thereafter a new pod will be created automatically depending upon the replica count. ### Application Objects You can view `Application Objects` in this section of `App Details`, such as: | Key | Description | | :--- | :--- | | `Workloads` | _ReplicaSet_\(ensures how many replica of pod should be running\), _Status of Pod_\(status of the Pod\) | | `Networking` | _Service_\(an abstraction which defines a logical set of Pods\), _Endpoints_\(names of the endpoints that implement a Service\), _Ingress_\(API object that manages external access to the services in a cluster\) | | `Config & Storage` | _ConfigMap_\( API object used to store non-confidential data in key-value pairs\) | | `Custom Resource` | _Rollout_\(new Pods will be scheduled on Nodes with available resources\), _ServiceMonitor_\(specifies how groups of services should be monitored\) | ## Monitoring You can monitor the application in the `App Details` section. Metrics like `CPU Usage`, `Memory Usage`, `Throughput` and `Latency` can be viewed here. | Key | Description | | :--- | :--- | | `CPU Usage` | Percentage of CPU's cycles used by the app. | | `Memory Usage` | Amount of memory used by app. | | `Throughput` | Performance of the app. | | `Latency` | Delay caused while transmitting the data. | --- ### User Guide Deleting Application (`docs/user-guide/deleting-application.md`) # Deleting Application Delete the Application, when you are sure you no longer need it. Clicking on `Delete Application` will not delete your application if you have workflows in the application. If your Application contains workflows in the Workflow Editor. So, when you click on `Delete Application`, you will see the following prompt. Click on `View Workflows` to view and delete your workflows in the application. To delete the workflows in your application, you must first delete all the pipelines \(CD Pipeline, CI Pipeline or Linked CI Pipeline or External CI Pipeline if there are any\). After you have deleted all the pipelines in the workflow, you can delete that particular workflow. Similarly, delete all the workflows in the application. Now, Click on `Delete Application` to delete the application. --- ### User Guide Namespaces And Environments (`docs/user-guide/namespaces-and-environments.md`) # Namespaces And Environments ## Namespaces Kubernetes namespaces can be seen as a logical entity used to represent cluster resources for usage of a particular set of users. This logical entity can also be termed as a virtual cluster. One physical cluster can be represented as a set of multiple such virtual clusters \(namespaces\). ### Multiple Namespaces Namespaces are intended for use in environments with many users spread across multiple teams, or projects. Names of resources need to be unique within a namespace, but not across namespaces. Namespaces can not be nested inside one another and each Kubernetes resource can only be in one namespace ## Environments One of the advantages that Kubernetes provides is the ability to manage various environments easier and better than traditional deployment strategies. For most nontrivial applications, you have test, staging, and production environments. You can spin up a separate cluster of resources, such as VMs, with the same configuration in staging and production, but that can be costly and managing the differences between the environments can be difficult. Kubernetes includes a cool feature called namespaces, which enables you to manage different environments within the same cluster. For example, you can have different test and staging environments in the same cluster of machines, potentially saving resources. Environments in Devtron can be accessed from `Global Configurations->Clusters & Environments` --- ### User Guide Resource Browser (`docs/user-guide/resource-browser.md`) # Resource Browser ## Introduction The Devtron Resource Browser provides you a central interface to view and manage all your [Kubernetes objects](../reference/glossary.md#objects) across clusters. It helps you perform key actions like viewing logs, editing live manifests, and even creating/deleting resources directly from the user interface. This is especially useful for troubleshooting purposes as it supports multi-cluster too. {% hint style="info" %} ### Additional References * [Resource browser versus traditional tools like kubectl](https://devtron.ai/blog/managing-kubernetes-resources-across-multiple-clusters) * [Why you should use Devtron's Resource Browser](https://devtron.ai/blog/what-is-the-kubernetes-resource-browser-in-devtron) {% endhint %} First, the Resource Browser shows you a list of clusters added to your Devtron setup. By default, it displays a cluster named '*default_cluster*' after the [initial setup](../setup/install/README.md) is successful. You can easily connect more clusters by clicking the **Add Cluster** button located at the top of the browser. This will take you to the [Cluster & Environments](./global-configurations/cluster-and-environments.md) configuration within [Global Configurations](./global-configurations/README.md). You may click a cluster to view and manage all its resources as shown below. --- ## Overview ### Resource Utilization This shows the combined CPU and memory consumption of all running pods in the cluster. | Parameter | Description | | --------------- | ------------------------------------------------------------------------------------------------------------| | CPU Usage | Percentage of CPU resources currently being used across all the pods in the cluster. | | CPU Capacity | Total amount of CPU resources available across all the nodes in the cluster. Measured in millicores (m). | | CPU Requests | Total amount of CPU resources requested by all the pods in the cluster. | | CPU Limits | Maximum amount of CPU resources that a total number of pods can use in the cluster. | | Memory Usage | Percentage of memory resources currently being used across all the pods in the cluster. | | Memory Capacity | Total amount of memory resources available across all the nodes in the cluster. Measured in Megabytes (Mi). | | Memory Requests | Total amount of memory resources requested by all the pods in the cluster. | | Memory Limits | Maximum amount of memory resources that a total number of pods can use in the cluster. | ### Errors This shows errors in the cluster. If no error is present in the cluster, Resource Browser will not display this section. ### Catalog Framework [](https://devtron.ai/pricing) {% hint style="warning" %} ### Who Can Perform This Action? Users need to have super-admin permission to edit the catalog framework. {% endhint %} Based on the schema provided in the catalog framework, you can add relevant details for each cluster. Refer [Catalog Framework](./global-configurations/catalog-framework.md) for more details. ### Readme {% hint style="warning" %} ### Who Can Perform This Action? Users need to have super-admin permission to edit the readme file. {% endhint %} You can also include additional information about your cluster using the Markdown editor. --- ## Discovering Resources {% hint style="warning" %} ### Who Can Perform This Action? Users need to have [access to the cluster](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to discover resources. {% endhint %} ### Search Resources You can use the searchbox to browse the resources. ### Filter Resources [](https://devtron.ai/pricing) Moreover, you can use filters that allow you to quickly filter your workload as per labels, field selectors, or [CEL expression](https://kubernetes.io/docs/reference/using-api/cel/) as shown below. {% embed url="https://www.youtube.com/watch?v=E-V-ELCXtfs" caption="Filtering Workloads in Devtron" %} ### Edit Manifest {% hint style="warning" %} ### Who Can Perform This Action? User needs to be an [admin of the Kubernetes resource](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to edit its manifest. {% endhint %} You can edit the [manifest](../reference/glossary.md#manifest) of a Kubernetes object. This can be for fixing errors, scaling resources, or changing configuration. ### View Events You can monitor activities like creation, deletion, updation, scaling, or errors in the resources involved. Refer [Events](https://kubernetes.io/docs/reference/kubernetes-api/cluster-resources/event-v1/) to learn more. ### Delete {% hint style="warning" %} ### Who Can Perform This Action? User needs to be an [admin of the Kubernetes resource](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to delete it. {% endhint %} You can delete an unwanted resource if it is orphaned and no longer required by your applications. --- ## Nodes You can see the list of nodes available in your cluster. Typically you have several nodes in a cluster; in a learning or resource-limited environment, you might have only one node. The components on a typical node include the `kubelet`, a `container runtime`, and the `kube-proxy`. If you have multiple nodes, you can search a node by name or label in the search bar. The search result will display the following information about the node. To display a parameter of a node, use `Columns` on the right side, select the parameter to display from the drop-down list, and click **Apply**. | Fields | Description | | --- | --- | | Node | Alphanumeric name of the node | | Status | Status of a node. It can be either `Ready` or `Not Ready`. | | Roles | Shows the roles of a node, e.g., agent | | Errors | Shows the number of errors in nodes (if any) | | K8s Version | Shows the version of Kubernetes cluster | | Node Group | Shows which collection of worker nodes it belongs to | | No. of Pods | Shows the total number of pods present in the node | Clicking on a node shows you a number of details such as: * CPU Usage and Memory Usage of Node * CPU Usage and Memory Usage of Each Pod * Number of Pods in the Node * List of Pods * Age of Pods * Labels, Annotations, and Taints * Node IP Further using the Devtron UI, you will be able to: * [Debug a Node](#debug-a-node) * [Cordon a Node](#cordon-a-node) * [Drain a Node](#drain-a-node) * [Taint a Node](#taint-a-node) * [Edit a Node Config](#edit-a-node-config) * [Delete a Node](#delete-a-node) {% hint style="info" %} ### Why Are Node Operations Required? Your applications run on pods, and pods run on nodes. But sometimes, Kubernetes scheduler cannot deploy a pod on a node for several reasons, e.g., node is not ready, node is not reachable, network is unavailable, etc. In such cases, node operations help you manage the nodes better. {% endhint %} {% hint style="warning" %} ### Who Can Perform These Actions? Users need to have super-admin permission to perform node operations. {% endhint %} ### Debug a Node You can debug a node via [Cluster Terminal](#cluster-terminal) by selecting your namespace and image from the list that has all CLI utilities like kubectl, helm, netshoot etc. or can use a custom image, which is publicly available. * Click **Debug**. * Debug a node by selecting the terminal shell, i.e., `bash` or `sh`. ### Cordon a Node Cordoning a node means making the node unschedulable. After [cordoning a node](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_cordon/), new pods cannot be scheduled on this node. * Click **Cordon**. * A confirmation dialog box will appear, click **Cordon Node** to proceed. The status of the node shows `SchedulingDisabled` with `Unschedulable` parameter set as `true`. Similarly, you can uncordon a node by clicking `Uncordon`. After a node is uncordoned, new pods can be scheduled on the node. ### Drain a Node Before performing maintenance on a node, [draining a node](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/) evicts all of your pods safely from a node. Safe evictions allow the pod’s containers to gracefully terminate and honour the `PodDisruptionBudgets` you have specified (if relevant). After the node is drained, all pods (including those managed by DaemonSets) in the node will be automatically drained to other nodes in the cluster, and the drained node will be set to cordoned status. * Click **Drain**. * A confirmation dialog box will appear, click **Drain Node** to proceed. You can also select from the following conditions before draining a node: | Name | Usage | | --- | --- | | Grace Period | Period of time in seconds given to each pod to terminate gracefully. If negative, the default value specified in the pod will be used. | | Delete empty directory data | Enabling this field will delete the pods using empty directory data when the node is drained. | | Disable eviction (use with caution) | Enabling this field will force drain to use delete, even if eviction is supported. This will bypass checking `PodDisruptionBudgets`.
Note: Make sure to use with caution.
| | Force drain | Enabling this field will force drain a node even if there are pods that do not declare a controller. | | Ignore DaemonSets | Enabling this field will ignore DaemonSet-managed pods. | ### Taint a Node Taints are `key:value` pairs associated with effect. After you add taints to nodes, you can set tolerations on a pod to allow the pod to be scheduled to nodes with certain taints. When you taint a node, it will repel all the pods except those that have a toleration for that taint. A node can have one or many taints associated with it. **Note**: Make sure to check taint validations before you add a taint. * Click **Edit taints**. * Enter the `key:value` pairs and select the [taint effect](#taint-effects) from the drop-down list. * Click **Save**. You can also add more taints using **+ Add taint button**, or delete the existing taint by using the delete icon. {% hint style="info" %} ### Additional Reference [Click here](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/#concepts) to read about taint effects. {% endhint %} ### Edit a Node Config This allows you to directly edit any node. It will open the editor which contains all the configuration settings in which the default format is YAML. You can edit multiple objects, although changes are applied one at a time. * Go to the `YAML` tab and click **Edit YAML**. * Make the changes using the editor. * Click **Review & Save changes** to compare the changes in the YAML file. * Click **Apply changes** to confirm. ### Delete a Node You can also delete a node by clicking the **Delete** button present on the right-hand side. The node will be deleted from the cluster. {% hint style="info" %} You can also access [Cluster Terminal](#cluster-terminal) from your node. {% endhint %} --- ## Pods {% hint style="warning" %} ### Who Can Perform This Action? Users need to have [access to the cluster](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to view its pods and its data. {% endhint %} ### Manifest Shows you the [configuration](../reference/glossary.md#manifest) of the selected pod and allows you to edit it. Refer [Edit Manifest](#edit-manifest) to learn more. ### Events Shows you all the activities (create/update/delete) of the selected pod. Refer [View Events](#view-events) to know more. ### Logs Examining your cluster's pods helps you understand the health of your application. By inspecting pod logs, you can check the performance and identify if there are any failures. This is especially useful for debugging any issues effectively. Moreover, you can download the pod logs for ease of sharing and troubleshooting as shown in the below video. {% embed url="https://www.youtube.com/watch?v=PP0ZKAZCT58" caption="Downloading Pod Logs" %} #### Pod Last Restart Snapshot [](https://devtron.ai/pricing) Frequent pod restarts can impact your application as it might lead to unexpected downtimes. In such cases, it is important to determine the root cause and take actions (both preventive and corrective) if needed. In case any of your pod restarts, you can view its details from the pod listing screen: * Last pod restart event, along with the timestamp and message * Reason behind restart * Container log before restart * Node status and events ### Terminal {% hint style="warning" %} ### Who Can Perform This Action? User needs to be an [admin of the Kubernetes resource](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to access pod terminal. {% endhint %} You can access the terminal within a running container of a pod to view its logs, troubleshoot issues, or execute commands directly. This is different from the [cluster terminal](#cluster-terminal) you get at node level. #### Launching Ephemeral Container This is a part of [Pod Terminal](#pod-terminal). It is especially useful when `kubectl exec` is insufficient because a container has crashed or a container image doesn't include debugging utilities. {% embed url="https://www.youtube.com/watch?v=Ml19i29Ivc4" caption="Launching Ephemeral Containers from Resource Browser" %} 1. In the Resource Browser, select **Pod** within `Workloads`. 2. Use the searchbar to find and locate the pod you wish to debug. Click the pod. 3. Go to the **Terminal** tab 4. Click **Launch Ephemeral Container** as shown below. You get 2 tabs: 1. **Basic** - It provides the bare minimum configurations required to launch an ephemeral container. It contains 3 mandatory fields: * **Container name prefix** - Type a prefix to give to your ephemeral container, for e.g., *debug*. Your container name would look like `debug-jndvs`. * **Image** - Choose an image to run from the dropdown. Ephemeral containers need an image to run and provide the capability to debug, such as `curl`. You can use a custom image too. * **Target Container name** - Since a pod can have one or more containers, choose a target container you wish to debug, from the dropdown. 2. **Advanced** - It is particularly useful for advanced users that wish to use labels or annotations since it provides additional key-value options. Refer [Ephemeral Container Spec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#ephemeralcontainer-v1-core) to view the supported options. {% hint style="info" %} Devtron ignores the 'command' field while launching an ephemeral container {% endhint %} --- ## Other Resource Kinds Other resources in the cluster are grouped under the following categories: * Namespace * Workloads * Config & Storage * Networking * RBAC * Administration * Other Resources * Custom Resource --- ## Cluster Terminal User with [super-admin](./global-configurations/authorization/user-access.md#assign-super-admin-permission) access can now troubleshoot cluster issues by accessing the cluster terminal from Devtron. You can select an image from the list that has all CLI utilities like kubectl, helm, netshoot etc. or can use a custom image, which is publicly available. To troubleshoot a cluster or a specific node in a cluster, click the terminal icon on the right side. * You will see the user-defined name for the cluster in Devtron. E.g. `default-cluster`. * Select the node you wish to troubleshoot from the `Node` drop-down. E.g. `demo-new`. * Select the namespace from the drop-down list which you have added in the [Environment](./global-configurations/cluster-and-environments.md#add-environment) section. * Select the image from the drop-down list which includes all CLI utilities or you can use a custom image, which is publicly available. * Select the terminal shell from the drop-down list (e.g. `sh`, `bash`) to troubleshoot a node. ### Use Case - Debugging Pods You can also create a pod for debugging which will connect to the pod terminal. To find out why a particular pod is not running, you can check `Pod Events` and `Pod Manifest` for details. The **Auto select** option automatically selects a node from a list of nodes and then creates a pod. Alternatively, you can choose a node of your choice from the same dropdown for debugging. The **Debug Mode** is helpful in scenarios where you can't access your node by using an SSH connection. Enabling this feature opens an interactive shell directly on the node. This shell provides unrestricted access to the node, giving you enhanced debugging capabilities. * Check the current state of the pod and recent events with the following command: ```bash kubectl get pods ``` * To know more information about each of these pods and to debug a pod depending on the state of the pods, run the following command: ```bash kubectl describe pod ``` Here, you can see configuration information about the container(s) and pod (labels, resource requirements, etc.), as well as status information about the container(s) and pod (state, readiness, restart count, events, etc.). [Click here](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/) to know more about pod lifecycle. {% hint style="info" %} A container can have no shells or multiple shells running in it. If you are unable to create a successful connection, try changing the shell, as the container may not have that shell running. {% endhint %} --- ## Creating Resources {% hint style="warning" %} ### Who Can Perform This Action? User needs to be an [admin of the Kubernetes resources](./global-configurations/authorization/user-access.md#kubernetes-resources-permissions) to create resources. {% endhint %} You can create one or more [Kubernetes objects](../reference/glossary.md#objects) in your cluster using YAML. In case you wish to create multiple objects, separate each resource definition by three dashes (---). Once you select a cluster in Resource Browser, click **+ Create Resource**, and add the resource definition. In the below example, we have created a simple pod named `nginx`: Here's one more example that shows the required fields and object specifications for a Kubernetes Deployment: {% code title="Spec File" overflow="wrap" lineNumbers="true" %} ```yml apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment labels: app: nginx spec: replicas: 2 selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx:1.14.2 ports: - containerPort: 80 ``` {% endcode %} --- ## Running Kubectl Commands Locally [](https://devtron.ai/pricing) ### Introduction If you wish to run kubectl commands from your local system, you need to have access to your cluster. Traditionally, the kubeconfig file (`./kube/config`) helps you connect with the cluster from your local system. ### Challenges in Kubeconfig Kubeconfig becomes painstakingly difficult to maintain especially when it comes to: * Granting or revoking access to the cluster for multiple people * Changing the permissions and subsequently the access token * Adding/Updating/Deleting the entries of cluster URLs and tokens * Keeping a record of multiple kubeconfig files ### Our Solution Devtron helps in reducing the challenges and simplifying the maintenance of kubeconfig file through: * **Devtron's Proxy URL for Cluster** - A standardized URL that you can use in place of your Kubernetes cluster URL. * **Devtron's Access Token** - A kubectl-compatible token which can be generated and centrally maintained from [Global Configurations → Authorization → API tokens](./global-configurations/authorization/api-tokens.md). ### Steps **Prerequisite**: An [API token with necessary permissions](./global-configurations/authorization/api-tokens.md) for the user(s) to access the cluster. If you are not a super-admin and can't generate a token yourself, you can find the session token (argocd.token) using the Developer Tools available in your web browser as shown below. 1. Go to `~/.kube` folder on your local machine and open the `config` file. Or you may create one with the following content: {% code title="kubeconfig" overflow="wrap" lineNumbers="true" %} ```yml apiVersion: v1 kind: Config clusters: - cluster: insecure-skip-tls-verify: true server: https:///orchestrator/k8s/proxy/cluster/ name: devtron-cluster contexts: - context: cluster: devtron-cluster user: admin name: devtron-cluster current-context: devtron-cluster users: - name: admin user: token: ``` {% endcode %} 2. Edit the following placeholders in the `server` field and the `token` field: | Placeholder | Description | Example | Where to Find | | ------------------- | ----------------------------------- | ---------------- | ------------------ | | | Hostname of the Devtron server | demo.devtron.ai | [Host URL Page](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/hostname-page.jpg) | | | Name of the cluster (or cluster ID) | devtron-cluster | [Applications Page](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/applications-page.jpg) | | | API token or session token | \- | [Authorization Page](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/kubernetes-resource-browser/authorization-page.jpg) | 3. Test the connection to the cluster by running any kubectl command, e.g., `kubectl get ns` or `kubectl get po -A` {% hint style="info" %} ### Additional References Once the connection is successful, you may run any [kubectl operations](https://kubernetes.io/docs/reference/kubectl/#operations) from your system. {% endhint %} ### Use Case - Port Forwarding [](https://devtron.ai/pricing) Assume your applications are running in a Kubernetes cluster on cloud. Now, if you wish to test or debug them on your local machine, you can perform [port forwarding](https://kubernetes.io/docs/tasks/access-application-cluster/port-forward-access-application-cluster/). It creates a tunnel between a port on your machine and a port on a resource within your cluster. Therefore, you can access applications running inside the cluster as though they are running locally on your machine. Once you have successfully connected to the cluster, you may run the port-forward command. Refer [kubectl port-forward](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_port-forward/) to see a few examples. --- ### User Guide Resource Watcher (`docs/user-guide/resource-watcher.md`) # Resource Watcher ## Introduction [](https://devtron.ai/pricing) An incident response if delayed can impact businesses, revenue, and waste valuable engineering time. Devtron's Resource Watcher enables you to perform automated actions upon the occurrence of events: * **Create Event** - Occurs when a new Kubernetes resource is created, for e.g., a new pod spun up to handle increased traffic. * **Update Event** - Occurs when an existing Kubernetes resource is modified, for e.g., deployment configuration tweaked to increase the replica count. * **Delete Event** - Occurs when an existing Kubernetes resource is deleted, for e.g., deletion of an orphaned pod. You can make the Resource Watcher listen to the above events and accordingly run a job you wish to get done, for e.g., increasing memory, executing a script, raising Jira ticket, emailing your stakeholders, sending Slack notifications, and many more. Since manual intervention is absent, the timely response of this auto-remediation system improves your operational efficiency. --- ## Creating a Watcher {% hint style="warning" %} ### Who Can Perform This Action? Users need to have super-admin permission to create a watcher. {% endhint %} This page allows you to create a watcher to track events and run a job. It also shows the existing list of watchers (if any). 1. Click **+ Create Watcher**. 2. Creating a watcher consists of 4 parts, fill all the sections one by one: * [Basic Details](#basic-details) * [Namespaces to Watch](#namespaces-to-watch) * [Intercept Change in Resources](#intercept-change-in-resources) * [Execute Runbook](#execute-runbook) ### Basic Details Here, you can give a name and description to your watcher. ### Namespaces to Watch Here, you can select the [namespaces](../reference/glossary.md#namespace) whose [Kubernetes resource](../reference/glossary.md#objects) you wish to monitor for changes. * You can watch the namespace(s) across **All Clusters** (existing and future). * Or you can watch namespace(s) of **Specific Clusters**. {% hint style="info" %} In both the above options, if you choose 'Specific Namespaces', you can further decide whether to track the namespaces you enter (by clicking 'Include selections') or to track the namespaces except the ones you enter (by clicking 'Exclude selections'). {% endhint %} ### Intercept Change in Resources Here, you can select the exact Kubernetes resource(s) you wish to track for changes (in the namespace(s) you selected in the previous step). * You can choose the resource from the **Resource kind(s) to watch** dropdown. Enter the Group/Version/Kind (GVK) if it's a custom resource definition (CRD), for e.g., `install.istio.io/v1apha1/IstioOperator` * Choose the event type your watcher should listen to: `Created`, `Updated`, `Deleted`. | Event Type | Description | | ---------- | ----------------------------------------------------------------------- | | Created | Triggers the watcher when your Kubernetes resource is created | | Updated | Triggers the watcher when your existing Kubernetes resource is modified | | Deleted | Triggers the watcher when your existing Kubernetes resource is deleted | * Enter a [CEL expression](https://github.com/google/cel-spec/blob/master/doc/langdef.md) to catch a specific change in the resource's manifest. {% hint style="info" %} * **If resource is created** - Use 'DEVTRON_FINAL_MANIFEST' * **If resource is updated** - Both 'DEVTRON_INITIAL_MANIFEST' and 'DEVTRON_FINAL_MANIFEST' can exist * **If resource is deleted** - Use 'DEVTRON_INITIAL_MANIFEST' {% endhint %} **Example**: `DEVTRON_FINAL_MANIFEST.status.currentReplicas == DEVTRON_FINAL_MANIFEST.spec.maxReplicas` ### Execute Runbook Here, you can choose a job that should trigger if your watcher intercepts any changes. * Choose a job pipeline from the **Run Devtron Job pipeline** dropdown. If a pipeline is not selected, the watcher won't intercept matching resource changes even if your defined conditions are met. * Select the environment in which the job should run. It can either be `devtron-ci` or the source environment (the intercepted namespace where the event has occurred). * If the job expects input parameters, you may add its key and value under **Runtime input parameters**. During a job's execution, its container can access the initial and final resource manifest through special environment variables. These variables are: * `DEVTRON_INITIAL_MANIFEST` * `DEVTRON_FINAL_MANIFEST` * Click **Create Watcher**. Your watcher is now ready to intercept the changes to the selected resources. --- ## Viewing Intercepted Changes {% hint style="warning" %} ### Who Can Perform This Action? Users need to have super-admin permission to view intercepted changes. {% endhint %} ### Details This page allows you to view the changes to Kubernetes resources that you have selected for tracking changes. It comes with the following items to help you locate the resource, where the event has been intercepted: * Searchbox * Cluster filter * Namespace filter * Action filter (event type, i.e., `Created`, `Updated`, `Deleted`) * Watcher filter (to check the intercepted changes of a specific watcher) You get the following details in the results shown on the page. |Field | Description | |-------|-------------| |[Change In Resource](#change-in-resource)|Describes the type of change to the Kubernetes resource along with a link to its manifest| |[Cluster/Namespace](#namespaces-to-watch) |Shows the cluster and namespace where the tracked Kubernetes resource belongs to| |Intercepted By |Shows the name of the watcher that intercepted the change| |Intercepted At |Shows the date and time when the event occurred | |[Job Execution](#execute-runbook) |Shows the status of the execution of job, e.g., `In Progress`, `Succeeded`, `Failed`| |[Logs](#job-execution-log) |Links to the job log, i.e, the `Run history` page of the job| ### Change in Resource You can check the changes in manifest by clicking **View Manifest** in `Change In Resource` column. ### Job Execution Log You can check the logs of the job executed when the Resource Watcher intercepts any change by clicking **logs**. --- ## Use Cases ### Live Stream Traffic Surge A live streaming sports application experiences a surge in viewers during a major game. The Horizontal Pod Autoscaler (HPA) might not be able to handle the unexpected traffic if it's capped at a low max replica count. 1. Create a watcher named 'Live Stream Scaling Alert'. 2. Monitor updates to HPA resource in the application's namespace. 3. When `currentReplicas` count reaches `maxReplicas`, trigger a job that contains the script to increase the replica count. ### Pod Health Monitoring A stock trading application constantly updates stock prices for its traders. If the pods become unhealthy, traders might see incorrect stock prices leading to bad investments. 1. Create a watcher named 'Pod Health Monitor'. 2. Track the pod workload of your application, if `DEVTRON_FINAL_MANIFEST.status.phase != 'Running'`, trigger a job that sends an Email/Slack alert with pod details. --- ### User Guide Security Features (`docs/user-guide/security-features.md`) # Security Features ## Introduction Devtron provides [DevSecOps](https://devtron.ai/product/devsecops) capabilities across your software development life cycle for both: the default CI/CD solution by Devtron as well as your existing CI/CD Tools. One of the key components of DevSecOps is the detection of security risks. Currently, Devtron supports the following types of scanning: * Image Scan * Code Scan * Kubernetes Manifest Scan You can integrate a scanning tool of your choice. By default, Devtron integrates with Trivy using which you can scan for the following issues: * Vulnerability * License Risks * Misconfigurations * Exposed Secrets --- ## Where to Initiate the Scan ### Before Building Artifact When you commit the code, it's essential to scan it before building a [container image](../reference/glossary.md#image). By scanning early, you can catch and fix problems before they become expensive or time-consuming to remediate later. 1. In your application, go to **App Configuration** → **Workflow Editor**. 2. Click the CI pipeline of your preferred workflow. 3. Go to the **Pre-build stage** (tab). 4. Click **+ Add Task**. 5. Choose **Vulnerability_Scanner v1.0.0** plugin from the list. 6. Click **Update Pipeline**. Based on the results of the scanner, you can also decide whether your CI should proceed further or not. This is possible through **Pass/Failure Condition** setting in the plugin. In the below example, we are allowing image build only if the no. of high vulnerability is zero. Results of Pre-CI scan will be visible under `Code Scan` in the **App Details** page as shown below. ### After Building Container Image Once a container image is ready, you can scan its base image libraries, stale files, compromised licenses, and many more. There are 2 options available: * Image scan in the Build stage (refer [Security Scans](./security-features/security-scans.md)) * Comprehensive scan in Post-Build stage This section contains the steps for comprehensive scan. 1. Go to the **Post-build stage** (tab) of your CI pipeline. 2. Click **+ Add Task** and choose **Vulnerability_Scanner v1.0.0**. 3. Click **Update Pipeline**. Results of Post-CI scan will be visible under `Image Scan` in the **App Details** page as shown below. ### Before Triggering Deployment There can be a loophole where the original image built in the CI stage gets compromised later (say, in publicly accessible repository). Therefore, you can scan the image and catch issues before deploying it. On top of that, you can also scan manifests to detect misconfigurations and exposed secrets. 1. Go to the **Pre-Deployment stage** (tab) of your CD pipeline. 2. Click **+ Add Task** and choose **Vulnerability_Scanner v1.0.0**. 3. Click **Update Pipeline**. Results of Pre-CD scan will be visible under `Image Scan` and `Kubernetes Manifest` in the **App Details** page as shown below. ### During Helm App Deployment When you [deploy a helm chart](../user-guide/deploy-chart/deployment-of-charts.md), Devtron will scan the image associated with that helm chart and also the manifests, but unlike Devtron Apps, there is no code scan involved. Results of helm app scan will be visible under `Image Scan` and `Kubernetes Manifest` in the **App Details** page as shown below. ### Extras You can also check for vulnerabilities within a specific workload such as job, pod, deployment, etc. There are two ways to perform it: #### From App Details * Go to **App Details** (Devtron App/Helm App) → **Workloads** (under `K8 Resources` tab). * Click a workload, e.g., Pod. * On the right-hand side, click the kebab menu (3 vertical dots). * Click **Check Vulnerabilities**. #### From Resource Browser * Go to Resource Browser. * Select a cluster. * Click a workload within the **Workloads** dropdown. * Access the **Check Vulnerabilities** option from the kebab menu present to your selected workload. --- ## Scans and Policies {% hint style="warning" %} ### Who Can Perform This Action? Users need to have super-admin permission to enable vulnerability scanning and to define security policies in Devtron. {% endhint %} Devtron's Security feature has two primary sections: 1. [**Security Scans**](./security-features/security-scans.md) - You can view the vulnerabilities detected across your applications. 2. [**Security Policies**](./security-features/security-policies.md) - This allows you to define guardrails to block or allow the deployment of container images depending on the vulnerabilities detected. --- ### User Guide Stack Manager (`docs/user-guide/stack-manager.md`) # Devtron Integrations Devtron integrations extend the functionality of your Devtron stack. ## Discover and install integrations The current release of Devtron supports the Build and Deploy (CI/CD) integration. More integrations will be available soon; to request one, please [submit a ticket](https://github.com/devtron-labs/devtron/issues/new/choose) > Integrations can be installed by super admins; However other user roles can browse and request super admins to install the required integrations. > Integrations are updated along with [Devtron updates](setup/../../setup/upgrade-devtron.md). Select **Devtron Stack Manager** from the left navigation bar. Under **INTEGRATIONS**, select **Discover**. > Although the integrations are installed separately, they cannot be upgraded separately. Integrations update happens automatically with [Devtron upgrade](#upgrade-devtron). ### Build and Deploy (CI/CD) integration Devtron CI/CD integration enables software development teams to automate the build and deployment process, allowing them to focus on meeting the business requirements, maintaining code quality, and ensuring security. **Features** * Leverages Kubernetes auto-scaling and centralized caching to give you unlimited cost-efficient CI workers. * Supports pre-CI and post-CI integrations for code quality monitoring. * Seamlessly integrates with Clair for image vulnerability scanning. * Supports different deployment strategies: Blue/Green, Rolling, Canary, and Recreate. * Implements GitOps to manage the state of Kubernetes applications. * Integrates with ArgoCD for continuous deployment. * Check logs, events, and manifests or exec inside containers for debugging. * Provides deployment metrics like; deployment frequency, lead time, change failure rate, and mean-time recovery. * Seamless integration with Grafana for continuous application metrics like CPU and memory usage, status code, throughput, and latency on the dashboard. #### Installation 1. On the **Devtron Stack Manager > Discover** page, select the **Build and Deploy (CI/CD) integration**. 2. On the **Discover integrations/Build and Deploy (CI/CD) page**, select **Install**. The installation status may be one of the following: | Installation status | Description | | --- | --- | | Install | The integration is not yet installed. | | Initializing | The installation is being initialized. | | Installing | The installation is in progress. The logs are available to track the progress. | | Failed | Installation failed and the logs are available to troubleshoot. You could retry the installation or [contact support](https://discord.devtron.ai/). | | Installed | The integration is successfully installed and available on the **Installed page**. | | Request timed out | The request to install has hit the maximum number of retries. You may retry the installation or [contact support](https://discord.devtron.ai/) for further assistance. | > A list of installed integrations can be viewed on the **Devtron Stack Manager > Installed** page. To update an installed integration, please [update Devtron](../setup/upgrade/upgrade-devtron-ui.md). --- ### User Guide Telemetry (`docs/user-guide/telemetry.md`) # Telemetry Guide * [Introduction](#introduction) * [What data is collected](#what-data-is-collected) * [Where data is sent](#where-data-is-sent) Introduction ============ Devtron collects anonymous telemetry data that helps the Devtron team in understanding how the product is being used and in deciding what to focus on next. The data collected is minimal, **non PII**, statistical in nature and **cannot be used to uniquely identify an user**. Please see the next section to see what data is collected and sent. Access to collected data is strictly limited to the Devtron team. As a growing community, it is very valuable in helping us make the Devtron a better product for everyone! What data is collected ====================== Here is a sample event JSON which is collected and sent: ```json { "id": "017ah6af-8h60-0000-abfc-a0a25hd823d6", "timestamp": "2021-06-29T07:33:02.001000+00:00", "event": "Heartbeat", "distinct_id": "qadgrtuxogziz8ak", "properties": { "$geoip_city_name": "Columbus", "$geoip_continent_code": "NA", "$geoip_continent_name": "North America", "$geoip_country_code": "US", "$geoip_country_name": "United States", "$geoip_latitude": 39.9625, "$geoip_longitude": -83.0061, "$geoip_postal_code": "43215", "$geoip_subdivision_1_code": "OH", "$geoip_subdivision_1_name": "Ohio", "$geoip_time_zone": "America/New_York", "$ip": "18.117.165.2", "$lib": "posthog-go", "$lib_version": "1.0.2", "devtronVersion": "v1", "eventType": 0, "serverVersion": "v1.17.17", "timestamp": "2021-06-29T07:33:02.001372393Z", "ucid": "qadgrtuxogziz8ak" } } ``` | Key | Description | | :--- | :--- | | `event` | Name of the event | | `distinct_id` | Unique user id or client id| | `devtronVersion` | devtron version | | `serverVersion` | kubernetes cluster version | | `eventType` | event type | | `ucid` | Unique client id | ### Inception (operator) Inception sends the installation and upgradation events of the Devtron tool to measure the churn rate. Events which are sent by Inception : * `InstallationStart` * `InstallationInProgress` * `InstallationSuccess` * `UpgradeStart` * `UpgradeInProgress` * `UpgradeSuccess` Event is same as sample json with event name mentioned above. ### Devtron (orchestrator) Orchestrator sends the summary events of the Devtron tool to measure the daily usage. Events which are sent by Orchestrator : * `Heartbeat` * `Summary` Orchestrator sends the `Summary` event once in 24 hours with the daily operation done by user. Here is a sample summary JSON which is available under properties: ```json { "summary": { "cdCountPerDay": 1, "ciCountPerDay": 1, "clusterCount": 1, "environmentCount": 1, "nonProdAppCount": 1, "userCount": 2 } } ``` | Key | Description | | :--- | :--- | | `cdCountPerDay` | cd pipeline created in last 24 hour | | `ciCountPerDay` | ci pipeline created in last 24 hour | | `clusterCount` | total cluster in the system | | `environmentCount` | total environment in the system | | `nonProdAppCount` | total non prod apps created | | `userCount` | total user created in the system | ### Dashboard(Not Collected Anymore) Dashboard sends the events to measure dashboard visit of the Devtron tool. Events which are sent by Orchestrator : * `identify` Dashboard sends the `identify` event when user visits the Dashboard for the first time. Where data is sent ====================== The data is sent to Posthog server. --- ### User Guide User Guide (`docs/user-guide/user-guide.md`) # Introduction Devtron is an open source software delivery workflow for kubernetes written in go. [Website](https://devtron.ai/) · [Blog](https://devtron.ai/blog/) · [Join Discord](https://discord.gg/jsRG5qx2gp) · [Twitter](https://twitter.com/DevtronL) ## Why Devtron? It is designed as a self-serve platform for operationalizing and maintaining applications \(AppOps\) on kubernetes in a developer friendly way. ### Some of the benefits provided by devtron are: #### Zero code software delivery workflow * Workflow which understands the domain of **kubernetes, testing, CD, SecOps** so that you don't have to write scripts * Reusable and composable components so that workflows are easy to construct and reason through #### Multi cloud deployment * deploy to multiple kubernetes cluster * test on aws cloud > coming soon: support for GCP and microsoft azure #### Easy dev-sec-ops integration * Multi level security policy at global, cluster, environment and application for efficient hierarchical policy management * Behavior driven security policy * Define policies and exception for kubernetes resources * Define policies for events for faster resolution #### Application debugging dashboard * One place for all historical kubernetes events * Access all manifests securely for eg secret obfuscation * _**Application metrics**_ for cpu, ram, http status code and latency with comparison between new and old * _**Advanced logging**_ with grep and json search * Intelligent _**correlation between events, logs**_ for faster triangulation of issue * Auto issue identification #### Enterprise Grade security and compliances * Fine grained access control; control who can edit configuration and who can deploy. * Audit log to know who did what and when * History of all CI and CD events * Kubernetes events impacting application * Relevant cloud events and their impact on applications * Advanced workflow policies like blackout window, branch environment relationship to secure build and deployment pipelines #### Gitops aware * Gitops exposed through API and UI so that you don't have to interact with git cli * Gitops backed by postgres for easier analysis * Enforce finer access control than git #### Operational insights * Deployment metrics to measure success of agile process. It captures mttr, change failure rate, deployment frequency, deployment size out of the box. * Audit log to understand the failure causes * Monitor changes across deployments and revert easily ## Compatibility notes * Only AWS kubernetes cluster is supported as of now * It uses modified version of [argo rollout](https://argoproj.github.io/argo-rollouts/). * application metrics only works for k8s 1.16+ ## Community Get updates on Devtron's development and chat with the project maintainers, contributors and community members. * Join the [Discord Community](https://discord.gg/jsRG5qx2gp) * Follow [@DevtronL on Twitter](https://twitter.com/DevtronL) * Raise feature requests, suggest enhancements, report bugs at [GitHub issues](https://github.com/devtron-labs/devtron/issues) * Read the [Devtron blog](https://devtron.ai/blog/) ## Contribute Check out our [contributing guidelines](https://github.com/devtron-labs/devtron-documentation/tree/1c2b95254995286ac0c3e8379117eb82a7ed8407/CONTRIBUTING.md). Included are directions for opening issues, coding standards, and notes on our development processes. ## Vulnerability Reporting We at Devtron take security and our users' trust very seriously. If you believe you have found a security issue in Devtron, please responsibly disclose by contacting us at security@devtron.ai. --- ### Hyperion FAQs Hyperion Troubleshoot (`docs/hyperion/FAQs/hyperion-troubleshoot.md`) ## Troubleshooting Guide We always try to make your experience of using hyperion as smooth as possible but still if you face any issues, follow the troubleshooting guide given below or join our [discord channel](https://discord.gg/jsRG5qx2gp) if you couldn't find the solution for the issue you are facing. #### 1. Hyperion Installed but still helm apps are not visible on dashboard To get helm apps on dashboard, it's important for migration jobs to be completed. To resolve this, check if Jobs are in `1/1 Completed` state by running the command: ``` kubectl get jobs -n devtroncd ``` If you see any of the jobs in `0/1 Completed` state then check if it's pod is still running using the following command: ``` kubectl get pods -n devtroncd ``` If the pods are in running state, then wait for them to complete and your helm apps should be visible on dashboard after that and if any of job's pod is in `CrashloopBackOff` state, then check the logs of that pod using: ``` kubectl logs -f -n devtroncd -c ``` Now, if you get something like `dirty db found` in the logs, then follow the steps given below and if not dirty db, then wait for the pod to automatically restart and complete the job so that helm apps are visible on dashboard. #### Steps to follow in case you get dirty db found 1. Run this command to get postgresql password - `kubectl -n devtroncd get secret devtron-secret -o jsonpath='{.data.PG_PASSWORD}' | base64 -d` 2. Copy the password you get and exec inside postgresql pod using `kubectl exec -it postgresql-postgresql-0 -n devtroncd -- sh` 3. Now when you are inside postgres, run the command to authenticate postgres user - `psql -U postgres` and enter the password that you got in step 1. 4. Terminate the connections to databases, delete them and then re-create using the commands given below ``` SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = 'orchestrator'; SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = 'casbin'; DROP database orchestrator; DROP database casbin; CREATE database orchestrator; CREATE database casbin; ``` 5. Download the migrator file and re-apply using the following commands: ``` kubectl delete -f https://raw.githubusercontent.com/devtron-labs/devtron/main/manifests/hyperion/migrator.yaml -n devtroncd kubectl apply -f https://raw.githubusercontent.com/devtron-labs/devtron/main/manifests/hyperion/migrator.yaml -n devtroncd ``` After completing all the steps, you should see the helm apps on dashboard. --- ### Hyperion Setup Install (`docs/hyperion/setup/install.md`) # Install Hyperion using Helm3 (Deprecated) > **Note**: Hyperion is now Devtron Before you begin, install [Helm3](https://helm.sh/docs/intro/install/) {% tabs %} {% tab title="Install with default configurations" %} ```bash helm repo add devtron https://helm.devtron.ai helm install devtron devtron/devtron-operator --create-namespace --namespace devtroncd --set installer.mode=hyperion ``` {% endtab %} {% endtabs %} For those countries/users where Github is blocked, you can download the [Hyperion Helm chart](https://s3-ap-southeast-1.amazonaws.com/devtron.ai/devtron-operator-latest.tgz) ```bash wget https://s3-ap-southeast-1.amazonaws.com/devtron.ai/devtron-operator-latest.tgz helm install devtron devtron-operator-latest.tgz --create-namespace --namespace devtroncd --set installer.mode=hyperion ``` [//]: # (If you are planning to use Hyperion for `production deployments`, please refer to our recommended overrides for [Devtron Installation](override-default-devtron-installation-configs.md).) [//]: # (## Installation status) [//]: # () [//]: # (Run following command) [//]: # () [//]: # (```bash) [//]: # (kubectl -n devtroncd get installers installer-devtron -o jsonpath='{.status.sync.status}') [//]: # (```) ## Access Hyperion dashboard If you did not provide a **BASE\_URL** during install or have used the default installation, Devtron creates a loadbalancer for you on its own. Use the following command to get the dashboard url. ```text kubectl get svc -n devtroncd devtron-service -o jsonpath='{.status.loadBalancer.ingress}' ``` You will get result something like below ```text [test2@server ~]$ kubectl get svc -n devtroncd devtron-service -o jsonpath='{.status.loadBalancer.ingress}' [map[hostname:aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com]] ``` The hostname mentioned here \( aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com \) is the Loadbalancer URL where you can access the Devtron dashboard. **PS:** You can also do a CNAME entry corresponding to your domain/subdomain to point to this Loadbalancer URL to access it at a custom domain. | Host | Type | Points to | | ---: | :--- | :--- | | devtron.yourdomain.com | CNAME | aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com | ### Hyperion Admin credentials For admin login use username:`admin` and for password run the following command. ```bash kubectl -n devtroncd get secret devtron-secret -o jsonpath='{.data.ACD_PASSWORD}' | base64 -d ``` ### Cleaning Hyperion Helm3 Please make sure that you do not have anything inside namespaces devtroncd, devtron-cd devtron-ci and devtron-demo as the below steps will clean everything inside these namespaces ``` helm uninstall devtron --namespace devtroncd kubectl delete -n devtroncd -f https://raw.githubusercontent.com/devtron-labs/charts/main/charts/devtron/crds/crd-devtron.yaml kubectl delete ns devtroncd ``` --- ### Hyperion Setup Upgrade To Devtron (`docs/hyperion/setup/upgrade-to-devtron.md`) # Upgrade Hyperion to Devtron Full mode To install Helm3, please check [Installing Helm3](https://helm.sh/docs/intro/install/) {% tabs %} {% tab title="Upgrade with default configurations" %} This installation will use Minio for storing build logs and cache. ```bash helm upgrade devtron devtron/devtron-operator --namespace devtroncd --set installer.mode=full ``` {% endtab %} {% tab title="Upgrade with AWS S3" %} This installation will use AWS s3 buckets for storing build logs and cache ```bash helm upgrade devtron devtron/devtron-operator --create-namespace --namespace devtroncd \ --set installer.mode=full \ --set configs.BLOB_STORAGE_PROVIDER=S3 \ --set configs.DEFAULT_CACHE_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CACHE_BUCKET_REGION=us-east-1 \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CD_LOGS_BUCKET_REGION=us-east-1 ``` {% endtab %} {% tab title="Upgrade with Azure Blob Storage" %} This installation will use Azure Blob Storage for storing build logs and cache ```bash helm upgrade devtron devtron/devtron-operator --create-namespace --namespace devtroncd \ --set installer.mode=full \ --set secrets.AZURE_ACCOUNT_KEY=xxxxxxxxxx \ --set configs.BLOB_STORAGE_PROVIDER=AZURE \ --set configs.AZURE_ACCOUNT_NAME=test-account \ --set configs.AZURE_BLOB_CONTAINER_CI_LOG=ci-log-container \ --set configs.AZURE_BLOB_CONTAINER_CI_CACHE=ci-cache-container ``` {% endtab %} {% endtabs %} If you are planning to use Devtron for `production deployments`, please refer to our recommended overrides for [Devtron Installation](override-default-devtron-installation-configs.md). ## Installation status Run following command ```bash kubectl -n devtroncd get installers installer-devtron -o jsonpath='{.status.sync.status}' ``` The install commands initiates Devtron-operator which spins up all the Devtron micro-services one by one in about 20 mins. You can use the above command to check the status of the installation if the installation is still in progress, it will print `Downloaded`. When the installation is complete, it prints `Applied`. ## Access Devtron dashboard If you did not provide a **BASE\_URL** during install or have used the default installation, Devtron creates a loadbalancer for you on its own. Use the following command to get the dashboard url. ```text kubectl get svc -n devtroncd devtron-service -o jsonpath='{.status.loadBalancer.ingress}' ``` You will get result something like below ```text [test2@server ~]$ kubectl get svc -n devtroncd devtron-service -o jsonpath='{.status.loadBalancer.ingress}' [map[hostname:aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com]] ``` The hostname mentioned here \( aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com \) is the Loadbalancer URL where you can access the Devtron dashboard. **PS:** You can also do a CNAME entry corresponding to your domain/subdomain to point to this Loadbalancer URL to access it at a custom domain. | Host | Type | Points to | | ---: | :--- | :--- | | devtron.yourdomain.com | CNAME | aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com | ### Devtron Admin credentials If you are upgrading from Hyperion to Devtron full mode, the admin password does NOT change. For admin login use username:`admin` and for password run the following command. ```bash kubectl -n devtroncd get secret devtron-secret -o jsonpath='{.data.ACD_PASSWORD}' | base64 -d ``` ### Cleaning Devtron Installer Helm3 Please make sure that you do not have anything inside namespaces devtroncd, devtron-cd devtron-ci and devtron-demo as the below steps will clean everything inside these namespaces ``` helm uninstall devtron --namespace devtroncd kubectl delete -n devtroncd -f https://raw.githubusercontent.com/devtron-labs/charts/main/charts/devtron/crds/crd-devtron.yaml kubectl delete -n argo -f https://raw.githubusercontent.com/devtron-labs/devtron/main/manifests/yamls/workflow.yaml kubectl delete ns devtroncd devtron-cd devtron-ci devtron-demo ``` --- ### Setup Getting Started Why Devtron (`docs/setup/getting-started/why-devtron.md`) # Why Devtron? Kubernetes is an open-source container orchestration tool that enables administrators to seamlessly deploy, manage and scale containerized apps in a wide variety of production environments. It works on a wide variety of platforms and cloud deployment models. By organizing apps into a cluster of containers that run on virtualized host operating systems, Kubernetes enables businesses to manage IT workloads efficiently. In the process, however, Kubernetes has also introduced a lot of new complexities for developers and systems administrators alike. To improve the usage of Kubernetes, several tools are needed to be integrated. But using these tools at the same time, however, is cumbersome and complex. These tools do not communicate with one another to manage different aspects of the application lifecycle, such as CI/CD, security, cost, observability, and stabilization. This is where **Devtron** comes into the picture!

The need to declaratively manage Kubernetes clusters and application delivery is what is driving **Devtron** on Kubernetes. Devtron is an open-source modular product that provides a `seamless` and `implementation-agnostic uniform interface`, that can be integrated with both open-source and commercial tools across the entire application lifecycle. With Devtron, you can efficiently handle security, stability, cost, and more in a unified experience. --- ### Setup Install Install Devtron On Minikube Microk8s K3s Kind (`docs/setup/install/Install-devtron-on-Minikube-Microk8s-K3s-Kind.md`) # Install Devtron on Minikube, Microk8s, K3s, Kind, Cloud VMs You can install and try Devtron on a high-end machine or a Cloud VM. If you install it on a laptop/PC, it may start to respond slowly, so it is recommended to uninstall Devtron from your system before shutting it down. ## Prerequisites 1. 2 vCPUs 2. 4GB+ of free memory 3. 20GB+ free disk space Before you get started, you must set up a cluster in your server and finish the following actions: * Create a cluster using [Minikube](https://minikube.sigs.k8s.io/docs/start/) or [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/) or [K3s](https://rancher.com/docs/k3s/latest/en/installation/). * Install [Helm3](https://helm.sh/docs/intro/install/). * Install [kubectl](https://kubernetes.io/docs/tasks/tools/). --- ## Tutorial {% embed url="https://www.youtube.com/watch?v=rKUymNJqcjA" caption="Installing Devtron on Minikube" %} --- ## For Minikube, Microk8s, K3s, Kind {% tabs %} {% tab title=" Minikube/Kind Cluster" %} To install devtron on ``Minikube/kind`` cluster, run the following command: ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set components.devtron.service.type=NodePort --set installer.arch=multi-arch ``` {% endtab %} {% tab title="k3s Cluster" %} To install devtron on ``k3s`` cluster, run the following command: ```bash kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/master/deploy/local-path-storage.yaml helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set components.devtron.service.type=NodePort ``` {% endtab %} {% endtabs %} ### Access Devtron Dashboard To access Devtron dashboard when using ``Minikube`` as cluster, run the following command: ```bash minikube service devtron-service --namespace devtroncd ``` To access Devtron dashboard when using ``Kind/k3s`` as cluster, run the following command to port forward the devtron service to port 8000: ```bash kubectl -n devtroncd port-forward service/devtron-service 8000:80 ``` **Dashboard**: [http://127.0.0.1:8000](http://127.0.0.1:8000). ### Get Admin Credentials When you install Devtron for the first time, it creates a default admin user and password (with unrestricted access to Devtron). You can use that credentials to log in as an administrator. After the initial login, we recommend you set up any SSO service like Google, GitHub, etc., and then add other users (including yourself). Subsequently, all the users can use the same SSO (let's say, GitHub) to log in to Devtron's dashboard. The section below will help you understand the process of getting the administrator credentials. #### For Devtron version v0.6.0 and higher **Username**: `admin`
**Password**: Run the following command to get the admin password: ```bash kubectl -n devtroncd get secret devtron-secret \ -o jsonpath='{.data.ADMIN_PASSWORD}' | base64 -d ```
For Devtron version less than v0.6.0 **Username**: `admin`
**Password**: Run the following command to get the admin password: ```bash kubectl -n devtroncd get secret devtron-secret \ -o jsonpath='{.data.ACD_PASSWORD}' | base64 -d ```
--- ## For Cloud VM (AWS EC2, Azure VM, GCP VM) It is recommended to use Cloud VM with 2vCPU+, 4GB+ free memory, 20GB+ storage, Compute Optimized VM type & Ubuntu Flavoured OS. ### Create Microk8s Cluster ```bash sudo snap install microk8s --classic --channel=1.22 sudo usermod -a -G microk8s $USER sudo chown -f -R $USER ~/.kube newgrp microk8s microk8s enable dns storage helm3 echo "alias kubectl='microk8s kubectl '" >> .bashrc echo "alias helm='microk8s helm3 '" >> .bashrc source .bashrc ``` ### Install Devtron ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set components.devtron.service.type=NodePort ``` ### Get devtron-service Port Number ```bash kubectl get svc -n devtroncd devtron-service -o jsonpath='{.spec.ports[0].nodePort}' ``` Make sure that the port on which the devtron-service runs remain open in the VM's security group or network security group. {% hint style="info" %} If you want to uninstall Devtron or clean Devtron helm installer, refer our [uninstall Devtron](./uninstall-devtron.md). {% endhint %} If you have questions, please let us know on our discord channel. [](https://discord.gg/jsRG5qx2gp) --- ### Setup Install Demo Tutorials (`docs/setup/install/demo-tutorials.md`) # Demo Tutorials Here we have demonstrated the installation of Devtron on popular cloud providers. The videos are easy to follow and provide step-by-step instructions. ## Installing on EKS Cluster **Cloud Provider**: [Amazon Web Services (AWS)](https://aws.amazon.com/) {% embed url="https://www.youtube.com/watch?v=eY2vudE5jFM" caption="Installing Devtron on AWS" %} --- ## Installing on AKS Cluster **Cloud Provider**: [Microsoft Azure](https://azure.microsoft.com/) {% embed url="https://www.youtube.com/watch?v=8ZdhwJQ-IU4" caption="Installing Devtron on Azure" %} --- ## Installing on GKE Cluster **Cloud Provider**: [Google Cloud Platform (GCP)](https://console.cloud.google.com/) {% embed url="https://www.youtube.com/watch?v=7UN_Fbo3VMM" caption="Installing Devtron on Google Cloud" %} --- ### Setup Install Devtron Backup (`docs/setup/install/devtron-backup.md`) ## Devtron Backup Regular backups for Devtron PostgreSQL and ArgoCD are crucial components of a disaster recovery plan, as they protect against potential data loss due to unforeseen circumstances. This documentation provides instructions on how to take backups of Devtron and store them either on AWS S3 or Azure containers. 1. Go to the devtron chart store and search for `devtron-backups` chart. 2. Select the `devtron-backups` and click `Configure & Deploy`. 3. Now follow either of the options described below according to your Cloud provider. ### AWS S3 Backup To store Devtron backups on AWS S3, please follow these steps: 1. Create an S3 bucket to store the Devtron backup, you can configure the bucket to delete all the objects older than 15/30 days. 2. Create a user with sufficient permissions to push to the S3 bucket created in step 1. 3. Obtain the access key and secret access key for the created user. 4. Configure the `devtron-backups` chart for AWS S3 by selecting the appropriate options: 5. Deploy the chart, and the Devtron backup will be automatically uploaded to the AWS S3 bucket at the scheduled intervals. ### Azure Containers Backup To store Devtron backups on Azure Containers, please follow these steps: 1. Create a storage account in Azure. 2. Within the storage account, create two containers for the Devtron backup. 3. Navigate to Security + Networking > Access Key section in Azure and copy the Access Key: 4. Configure the `devtron-backups` chart for Azure Containers by providing the Access Key: 5. Before deploying the backup chart, ensure that `AWS.enabled` is set to `false`. This will ensure that Devtron backup will be automatically uploaded to the configured Azure containers on the scheduled intervals. By following these steps, you can ensure that your Devtron data is securely backed up and protected against any potential data loss, enabling you to recover quickly in case of emergencies. --- ### Setup Install Faq On Installation (`docs/setup/install/faq-on-installation.md`) # FAQ
1. How will I know when the installation is finished? Run the following command to check the status of the installation: ```bash kubectl -n devtroncd get installers installer-devtron -o jsonpath='{.status.sync.status}' ``` The above command will print `Applied` once the installation process is complete. The installation process could take up to 30 minutes.
2. How do I track the progress of the installation? Run the following command to check the logs of the Pod: ```bash pod=$(kubectl -n devtroncd get po -l app=inception -o jsonpath='{.items[0].metadata.name}')&& kubectl -n devtroncd logs -f $pod ```
3. How can I restart the installation if the Devtron installer logs contain an error? First run the below command to clean up components installed by Devtron installer: ```bash cd devtron-installation-script/ kubectl delete -n devtroncd -f yamls/ kubectl -n devtroncd patch installer installer-devtron --type json -p '[{"op": "remove", "path": "/status"}]' ``` Next, [install Devtron](./install-devtron.md)
4. What's the purpose of 'Login as administrator' option on the login page? When you install Devtron for the first time, it creates a default admin user and password (with unrestricted access to Devtron). You can use that credentials to log in as an administrator. After the initial login, we recommend you set up any SSO service like Google, GitHub, etc., and then add other users (including yourself). Subsequently, all the users can use the same SSO (let's say, GitHub) to log in to Devtron's dashboard.
Still facing issues, please reach out to us on [Discord](https://discord.gg/jsRG5qx2gp). --- ### Setup Install Ingress Setup (`docs/setup/install/ingress-setup.md`) # Ingress Setup ## Introduction If you wish to use [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) as a means to access the Devtron services available in your cluster, you can configure it either during the installation or after the installation of Devtron. Refer the section relevant to you: * [During Devtron Installation](#enabling-ingress-during-devtron-installation) * [After Devtron Installation](#configuring-ingress-after-devtron-installation) If you have successfully configured Ingress, refer [Post Ingress Setup](#enable-https-for-devtron). --- ## Enabling Ingress during Devtron Installation If you are installing Devtron, you can enable Ingress either via [set flag](#using-set-flag) or by using [ingress-values.yaml](#using-ingress-values.yaml) to specify the desired Ingress settings. ### Using set flag You can use the `--set` flag to specify the desired Ingress settings. Here, we have added 5 configurations you can perform depending on your requirements: * [Only Basic Configuration](#only-basic-configuration) * [Configuration Including Labels](#configuration-including-labels) * [Configuration Including Annotations](#configuration-including-annotations) * [Configuration Including TLS Settings](#configuration-including-tls-settings) * [Comprehensive Configuration](#comprehensive-configuration) #### Only Basic Configuration To enable Ingress and set basic parameters, use the following command: ```bash helm install devtron devtron/devtron-operator -n devtroncd \ --set components.devtron.ingress.enabled=true \ --set components.devtron.ingress.className=nginx \ --set components.devtron.ingress.host=devtron.example.com ``` #### Configuration Including Labels To add labels to the Ingress resource, use the following command: ```bash helm install devtron devtron/devtron-operator -n devtroncd \ --set components.devtron.ingress.enabled=true \ --set components.devtron.ingress.className=nginx \ --set components.devtron.ingress.host=devtron.example.com \ --set components.devtron.ingress.labels.env=production ``` #### Configuration Including Annotations To add annotations to the Ingress resource, use the following command: ```bash helm install devtron devtron/devtron-operator -n devtroncd \ --set components.devtron.ingress.enabled=true \ --set components.devtron.ingress.className=nginx \ --set components.devtron.ingress.host=devtron.example.com \ --set components.devtron.ingress.annotations."kubernetes\.io/ingress\.class"=nginx \ --set components.devtron.ingress.annotations."nginx\.ingress\.kubernetes\.io\/app-root"="/dashboard" ``` #### Configuration Including TLS Settings To configure TLS settings, including `secretName` and `hosts`, use the following command: ```bash helm install devtron devtron/devtron-operator -n devtroncd \ --set components.devtron.ingress.enabled=true \ --set components.devtron.ingress.className=nginx \ --set components.devtron.ingress.host=devtron.example.com \ --set components.devtron.ingress.tls[0].secretName=devtron-tls \ --set components.devtron.ingress.tls[0].hosts[0]=devtron.example.com ``` #### Comprehensive Configuration To include all the above settings in a single command, use: ```bash helm install devtron devtron/devtron-operator -n devtroncd \ --set components.devtron.ingress.enabled=true \ --set components.devtron.ingress.className=nginx \ --set components.devtron.ingress.host=devtron.example.com \ --set components.devtron.ingress.annotations."kubernetes\.io/ingress\.class"=nginx \ --set components.devtron.ingress.annotations."nginx\.ingress\.kubernetes\.io\/app-root"="/dashboard" \ --set components.devtron.ingress.labels.env=production \ --set components.devtron.ingress.pathType=ImplementationSpecific \ --set components.devtron.ingress.tls[0].secretName=devtron-tls \ --set components.devtron.ingress.tls[0].hosts[0]=devtron.example.com ``` ### Using ingress-values.yaml As an alternative to the [set flag](#using-set-flag) method, you can enable Ingress using `ingress-values.yaml` instead. Create an `ingress-values.yaml` file. You may refer the below format for an advanced ingress configuration which includes labels, annotations, secrets, and many more. ```yml components: devtron: ingress: enabled: true className: nginx labels: {} # env: production annotations: {} # nginx.ingress.kubernetes.io/app-root: /dashboard pathType: ImplementationSpecific host: devtron.example.com tls: [] # - secretName: devtron-info-tls # hosts: # - devtron.example.com ``` Once you have the `ingress-values.yaml` file ready, run the following command: ```bash helm install devtron devtron/devtron-operator -n devtroncd --reuse-values -f ingress-values.yaml ``` --- ## Configuring Ingress after Devtron Installation After Devtron is installed, Devtron is accessible through `devtron-service`. If you wish to access Devtron through ingress, you'll need to modify this service to use a ClusterIP instead of a LoadBalancer. You can do this using the `kubectl patch` command: ```bash kubectl patch -n devtroncd svc devtron-service -p '{"spec": {"ports": [{"port": 80,"targetPort": "devtron","protocol": "TCP","name": "devtron"}],"type": "ClusterIP","selector": {"app": "devtron"}}}' ``` Next, create ingress to access Devtron by applying the `devtron-ingress.yaml` file. The file is also available on this [link](https://github.com/devtron-labs/devtron/blob/main/manifests/yamls/devtron-ingress.yaml). You can access Devtron from any host after applying this yaml. ```yml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: nginx.ingress.kubernetes.io/app-root: /dashboard labels: app: devtron release: devtron name: devtron-ingress namespace: devtroncd spec: ingressClassName: nginx rules: - http: paths: - backend: service: name: devtron-service port: number: 80 path: /orchestrator pathType: ImplementationSpecific - backend: service: name: devtron-service port: number: 80 path: /dashboard pathType: ImplementationSpecific - backend: service: name: devtron-service port: number: 80 path: /grafana pathType: ImplementationSpecific ``` For k8s versions < 1.19, [apply this yaml](https://github.com/devtron-labs/devtron/blob/main/manifests/yamls/devtron-ingress-legacy.yaml): ```yml apiVersion: extensions/v1beta1 kind: Ingress metadata: annotations: nginx.ingress.kubernetes.io/app-root: /dashboard labels: app: devtron release: devtron name: devtron-ingress namespace: devtroncd spec: rules: - http: paths: - backend: serviceName: devtron-service servicePort: 80 path: /orchestrator - backend: serviceName: devtron-service servicePort: 80 path: /dashboard pathType: ImplementationSpecific ``` Optionally, you also can access Devtron through a specific host by running the following YAML file: ```yml apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: nginx.ingress.kubernetes.io/app-root: /dashboard labels: app: devtron release: devtron name: devtron-ingress namespace: devtroncd spec: ingressClassName: nginx rules: - host: devtron.example.com http: paths: - backend: service: name: devtron-service port: number: 80 path: /orchestrator pathType: ImplementationSpecific - backend: service: name: devtron-service port: number: 80 path: /dashboard pathType: ImplementationSpecific - backend: service: name: devtron-service port: number: 80 path: /grafana pathType: ImplementationSpecific ``` --- ## Enable HTTPS For Devtron Once Ingress setup for Devtron is done and you want to run Devtron over `https`, you need to add different annotations for different ingress controllers and load balancers. ### 1. Nginx Ingress Controller In case of `nginx ingress controller`, add the following annotations under `service.annotations` under nginx ingress controller to run devtron over `https`. (i) Amazon Web Services (AWS) If you are using AWS cloud, add the following annotations under `service.annotations` under nginx ingress controller. ```bash annotations: service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "http" service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "443" nginx.ingress.kubernetes.io/force-ssl-redirect: "true" service.beta.kubernetes.io/aws-load-balancer-ssl-cert: "" ``` (ii) Digital Ocean If you are using Digital Ocean cloud, add the following annotations under `service.annotations` under nginx ingress controller. ```bash annotations: service.beta.kubernetes.io/do-loadbalancer-protocol: "http" service.beta.kubernetes.io/do-loadbalancer-tls-ports: "443" service.beta.kubernetes.io/do-loadbalancer-certificate-id: "" service.beta.kubernetes.io/do-loadbalancer-redirect-http-to-https: "true" ``` ### 2. AWS Application Load Balancer (AWS ALB) In case of AWS application load balancer, add following annotations under `ingress.annotations` to run devtron over `https`. ```bash annotations: kubernetes.io/ingress.class: alb alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS": 443}]' alb.ingress.kubernetes.io/certificate-arn: "" ``` ### 3. Azure Application Gateway In case of AWS application load balancer, the following annotations need to be added under `ingress.annotations` to run devtron over `https`. ```bash annotations: kubernetes.io/ingress.class: "azure/application-gateway" appgw.ingress.kubernetes.io/backend-protocol: "http" appgw.ingress.kubernetes.io/ssl-redirect: "true" appgw.ingress.kubernetes.io/appgw-ssl-certificate: "" ``` For an Ingress resource to be observed by AGIC (Application Gateway Ingress Controller) must be annotated with kubernetes.io/ingress.class: azure/application-gateway. Only then AGIC will work with the Ingress resource in question. > Note: Make sure NOT to use port 80 with HTTPS and port 443 with HTTP on the Pods. --- ### Setup Install Install Devtron Kubernetes Client (`docs/setup/install/install-devtron-Kubernetes-client.md`) # Devtron Kubernetes Client ## Overview The Kubernetes client by Devtron is a very lightweight dashboard that can be installed on arm64/amd64-based architectures. It comes with the features such as Kubernetes Resources Browser and Cluster Management that can provide control and observability for resources across clouds and clusters. Devtron Kubernetes client is an intuitive Kubernetes Dashboard or a command line utility installed outside a Kubernetes cluster. The client can be installed on a desktop running on any Operating Systems and interact with all your Kubernetes clusters and workloads through an API server. It is a binary, packaged in a bash script that you can download and install by using the following set of commands. By installing `Devtron Kubernetes Client`, you can access: * [Kubernetes Resource Browser](#kubernetes-resource-browser) * [Clusters Management Feature](#cluster-management) ## Here are a few advantages of using Devtron Kubernetes Client: * **Managing Kubernetes Resources at scale**: Clusters vary on business and architectural needs. Organizations tend to build smaller clusters for more decentralization. This practice leads to the creation of multiple clusters and more nodes. Managing them on a CLI requires multiple files, making it difficult to perform resource operations. But with the Devtron Kubernetes Client, you can gain more visibility into K8s resources easily. * **Unifying information in one place**: When information is scattered across clusters, and you have to type commands with arguments to fetch desired output, the process becomes slow and error-prone. Without a single point of configuration source, the configurations of different config. files diverge, making them even more challenging to restore and track. The Devtron Kubernetes Client unifies all the information and tools into one interface to perform various contextual tasks. * **Accessibility during an outage for troubleshooting**: As the Devtron Kubernetes Client runs outside a cluster, you can exercise basic control over their failed resources when there is a cluster-level outage. The Client helps to gather essential logs and data to pinpoint the root cause of the issue and reduce the time to restore service. * **Avoiding Kubeconfig version mismatch errors**: With the Devtron Kubernetes Client, you can be relieved from maintaining the Kubeconfig versions for the respective clusters (v1.16 - 1.26 i.e, current version) as the Devtron Kubernetes Client performs self kubeconfig version control. Instead of managing multiple kubectl versions manually, it eliminates the chances of errors occurring due to the mismatch in configuration. ## Install Devtron Kubernetes Client * Download the bash script using the below URL: https://cdn.devtron.ai/k8s-client/devtron-install.bash * To automatically download the executable file and to open the dashboard in the respective browser, run the following command: ```bash sh devtron-install.bash start ``` `Note`: Make sure you place `Devtron-install.bash` in your current directory before you execute the command. * Devtron Kubernetes Client opens in your browser automatically. * You must add your cluster to make your cluster visible on the `Kubernetes Resource Browser` and `Clusters` section. To add a cluster, go to the `Global Configurations` and click `Add Cluster`. [Refer documentation on how to add a cluster](../../user-guide/global-configurations/cluster-and-environments.md#add-cluster). `Note`: You do not need to have a `super admin` permission to add a cluster if you install `Devtron Kubernetes Client`. You can add more than one cluster. ### Kubernetes Resource Browser `Kubernetes Resource Browser` provides a graphical user interface for interacting and managing all your Kubernetes (k8s) resources across clusters. It also helps you to deploy and manage Kubernetes resources and allows pod operations such as: * View real-time logs * Check manifest and edit live manifests of k8s resources * Executable via terminal * View Events * Or, delete a resource With `Kubernetes Resource browser`, you can also perform the following: * Check the real-time health status * Search for any workloads * Manage multiple clusters and change cluster contexts * Deploy multiple K8s manifests through `Create` UI option. * Perform resource grouping at the cluster level. After your cluster is added via `Global Configurations`, go to the `Kubernetes Resource Browser` page and select your cluster. [Refer Resource Browser documentation for detail and its operations](../../user-guide/resource-browser.md). `Note`: You do not need to have a `super admin` permission to access `Kubernetes Resource Browser` if you install `Devtron Kubernetes Client`. ### Cluster Management With the `Devtron Kubernetes Client`, you can manage all your clusters running on-premises or on a cloud. It is a cluster and cloud agnostic platform where you can add as many clusters as you want, be it a lightweight cluster such as k3s/ microk8s or cloud managed clusters like Amazon EKS. It enables you to observe and monitor the cluster health and real-time node conditions. The Cluster management feature provides a summary of nodes with all available labels, annotations, taints, and other parameters such as resource usage. In addition to that, it helps you to perform node operations such as: * Debug a node * Cordon a node * Drain a node * Taint a node * Edit a node config * Delete a node With its rich features and intuitive interface, you can easily manage and [debug clusters through cluster terminal access](../../user-guide/clusters.md#access-cluster-via-terminal-for-troubleshooting) and use any CLI debugging tools like busybox, kubectl, netshoot or any custom CLI tools like k9s. After your cluster is added via `Global Configurations`, go to the `Clusters` page and search or select your cluster. [Refer Clusters documentation for detail and its operations](../../user-guide/clusters.md). ### Some Peripheral Commands * In case if you close the browser by mistake, you can open the dashboard by executing the following command. It will open the dashboard through a port in the available web browser and store the Kubernetes client's state. ```bash sh devtron-install.bash open ``` * To stop the dashboard, you can execute the following command: ```bash sh devtron-install.bash stop ``` * To update the `Devtron Kubernetes Client`, use the following command. It will stop the running dashboard and download the latest executable file and open it in the browser. ```bash sh devtron-install.bash upgrade ``` --- ### Setup Install Install Devtron Helm 3 (`docs/setup/install/install-devtron-helm-3.md`) # Install Devtron using Helm ## Before you begin Install [Helm3](https://helm.sh/docs/intro/install/). ## Installing Devtron using Helm 1. Add Devtron repository 2. Update Devtron repository 3. Install Devtron {% tabs %} {% tab title="Install with default configurations" %} This installation will use Minio for storing build logs and cache. ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator --create-namespace --namespace devtroncd \ --set installer.modules={cicd} ``` {% endtab %} {% tab title="Install with AWS S3 Buckets" %} This installation will use AWS s3 buckets for storing build logs and cache. Refer to the `AWS specific` parameters on the [Storage for Logs and Cache](./installation-configuration.md#storage-for-logs-and-cache) page. ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator --create-namespace --namespace devtroncd \ --set installer.modules={cicd} \ --set configs.BLOB_STORAGE_PROVIDER=S3 \ --set configs.DEFAULT_CACHE_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CACHE_BUCKET_REGION=us-east-1 \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CD_LOGS_BUCKET_REGION=us-east-1 ``` {% endtab %} {% tab title="Install with Azure Blob Storage" %} This installation will use Azure Blob Storage for storing build logs and cache. Refer to the `Azure specific` parameters on the [Storage for Logs and Cache](./installation-configuration.md#storage-for-logs-and-cache) page. ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator --create-namespace --namespace devtroncd \ --set installer.modules={cicd} \ --set secrets.AZURE_ACCOUNT_KEY=xxxxxxxxxx \ --set configs.BLOB_STORAGE_PROVIDER=AZURE \ --set configs.AZURE_ACCOUNT_NAME=test-account \ --set configs.AZURE_BLOB_CONTAINER_CI_LOG=ci-log-container \ --set configs.AZURE_BLOB_CONTAINER_CI_CACHE=ci-cache-container ``` {% endtab %} {% endtabs %} For those countries/users where Github is blocked, you can use Gitee as the installation source. {% tabs %} {% tab title="Install with Gitee" %} ```bash helm repo add devtron https://helm.devtron.ai helm install devtron devtron/devtron-operator --create-namespace --namespace devtroncd --set installer.source=gitee ``` {% endtab %} {% endtabs %} If you are planning to use Devtron for `production deployments`, please refer to our recommended overrides for [Devtron Installation](override-default-devtron-installation-configs.md). ## Installing Devtron (Beta) using Helm We also release beta versions of devtron every few days before the stable release for people who would like to explore and test beta features before everyone else. If you want to install a fresh devtron from beta release channel, use the chart in our official devtron repository. This chart is currently not available on the official helm repository therefore you need to download it to install it. 1. Clone Devtron Repository 2. Upgrade Helm Dependency 3. Install Devtron ```bash $ git clone [https://github.com/devtron-labs/devtron.git](https://github.com/devtron-labs/devtron.git) $ cd devtron/charts/devtron $ helm dependency up $ #modify values in values.yaml $ helm install devtron . --create-namespace --namespace devtroncd \ --set installer.modules={cicd} ``` {% tab title="Install with AWS S3 Buckets" %} This installation will use AWS s3 buckets for storing build logs and cache. Refer to the `AWS specific` parameters on the [Storage for Logs and Cache](./installation-configuration.md#storage-for-logs-and-cache) page. ```bash $ git clone [https://github.com/devtron-labs/devtron.git](https://github.com/devtron-labs/devtron.git) $ cd devtron/charts/devtron $ helm dependency up $ #modify values in values.yaml $ helm install devtron . --create-namespace --namespace devtroncd \ --set installer.modules={cicd}\ --set configs.BLOB_STORAGE_PROVIDER=S3 \ --set configs.DEFAULT_CACHE_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CACHE_BUCKET_REGION=us-east-1 \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CD_LOGS_BUCKET_REGION=us-east-1 ``` {% tab title="Install with Azure Blob Storage" %} This installation will use Azure Blob Storage for storing build logs and cache. Refer to the `Azure specific` parameters on the [Storage for Logs and Cache](./installation-configuration.md#storage-for-logs-and-cache) page. ```bash $ git clone [https://github.com/devtron-labs/devtron.git](https://github.com/devtron-labs/devtron.git) $ cd devtron/charts/devtron $ helm dependency up $ #modify values in values.yaml $ helm install devtron . --create-namespace --namespace devtroncd \ --set installer.modules={cicd}\ --set secrets.AZURE_ACCOUNT_KEY=xxxxxxxxxx \ --set configs.BLOB_STORAGE_PROVIDER=AZURE \ --set configs.AZURE_ACCOUNT_NAME=test-account \ --set configs.AZURE_BLOB_CONTAINER_CI_LOG=ci-log-container \ --set configs.AZURE_BLOB_CONTAINER_CI_CACHE=ci-cache-container ``` > Note: There is no option to upgrade to beta on stack manager UI as of now and you may always see upgrade available for latest stable version using which you'll be moved to latest stable version available. ## Check Devtron installation status The install commands start Devtron-operator, which takes about 20 minutes to spin up all of the Devtron microservices one by one. You can use the following command to check the status of the installation: ```bash kubectl -n devtroncd get installers installer-devtron -o jsonpath='{.status.sync.status}' ``` The command executes with one of the following output message, indicating the status of the installation: | Status | Description | | :--- | :--- | | `Downloaded` | Installer has downloaded all the manifests and installation is in progress. | | `Applied` | Installer has successfully applied all the manifests and installation is complete. | ## Check the installer logs To check the installer logs run the following command: ```bash kubectl logs -f -l app=inception -n devtroncd ``` ## Access Devtron dashboard If you did not provide a **BASE\_URL** during installation or have used the default installation, Devtron creates a load balancer for you on its own. Use the following command to get the dashboard URL. ```bash kubectl get svc -n devtroncd devtron-service -o jsonpath='{.status.loadBalancer.ingress}' ``` You will get an output similar to the one shown below: ```bash [test2@server ~]$ kubectl get svc -n devtroncd devtron-service -o jsonpath='{.status.loadBalancer.ingress}' [map[hostname:aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com]] ``` The hostname mentioned here `aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com` is the Loadbalancer URL where you can access the Devtron dashboard. If you don't see any results or receive a message that says "service doesn't exist," it means Devtron is still installing; please check back in 5 minutes. > Note: You can also do a `CNAME` entry corresponding to your domain/subdomain to point to this Loadbalancer URL to access it at a custom domain. | Host | Type | Points to | | ---: | :--- | :--- | | devtron.yourdomain.com | CNAME | aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com | ### Devtron Admin credentials When you install Devtron for the first time, it creates a default admin user and password (with unrestricted access to Devtron). You can use that credentials to log in as an administrator. After the initial login, we recommend you set up any SSO service like Google, GitHub, etc., and then add other users (including yourself). Subsequently, all the users can use the same SSO (let's say, GitHub) to log in to Devtron's dashboard. The section below will help you understand the process of getting the administrator credentials. #### For Devtron version v0.6.0 and higher Use username:`admin` and for password run command mentioned below. ```bash kubectl -n devtroncd get secret devtron-secret -o jsonpath='{.data.ADMIN_PASSWORD}' | base64 -d ``` #### For Devtron version less than v0.6.0 Use username:`admin` and for password run command mentioned below. ```bash kubectl -n devtroncd get secret devtron-secret -o jsonpath='{.data.ACD_PASSWORD}' | base64 -d ``` ## Cleaning Devtron Installer Helm3 Please make sure that you do not have anything inside namespaces devtroncd, devtron-cd, devtron-ci, and devtron-demo as the below steps will clean everything inside these namespaces: ```bash helm uninstall devtron --namespace devtroncd kubectl delete -n devtroncd -f https://raw.githubusercontent.com/devtron-labs/charts/main/charts/devtron/crds/crd-devtron.yaml kubectl delete -n argo -f https://raw.githubusercontent.com/devtron-labs/devtron/main/manifests/yamls/workflow.yaml kubectl delete ns devtroncd devtron-cd devtron-ci devtron-demo ``` ### Cleanup Run the following commands to delete all the components installed by Devtron: ```bash cd devtron-installation-script/ kubectl delete -n devtroncd -f yamls/ kubectl delete -n devtroncd -f charts/devtron/templates/devtron-installer.yaml kubectl delete -n devtroncd -f charts/devtron/templates/install.yaml kubectl delete -n devtroncd -f charts/devtron/crds kubectl delete ns devtroncd ``` ### FAQs
1. How will I know when the installation is finished? Run the following command to check the status of the installation: ```bash kubectl -n devtroncd get installers installer-devtron -o jsonpath='{.status.sync.status}' ``` The above command will print `Applied` once the installation process is complete. The installation process could take up to 30 minutes.
2. How do I track the progress of the installation? Run the following command to check the logs of the Pod: ```bash pod=$(kubectl -n devtroncd get po -l app=inception -o jsonpath='{.items[0].metadata.name}')&& kubectl -n devtroncd logs -f $pod ```
3. How can I restart the installation if the Devtron installer logs contain an error? First run the below command to clean up components installed by Devtron installer: ```bash cd devtron-installation-script/ kubectl delete -n devtroncd -f yamls/ kubectl -n devtroncd patch installer installer-devtron --type json -p '[{"op": "remove", "path": "/status"}]' ``` Next, [install Devtron using Helm3](./install-devtron-helm-3.md)
Still facing issues, please reach out to us on [discord](https://discord.gg/jsRG5qx2gp). --- ### Setup Install Install Devtron In Airgapped Environment (`docs/setup/install/install-devtron-in-airgapped-environment.md`) # Devtron Installation in an Airgapped Environment ## Introduction In certain scenarios, you may need to deploy Devtron to a Kubernetes cluster that isn’t connected to the internet. Such air-gapped environments are used for various reasons, particularly in industries with strict regulatory requirements like healthcare, banking, and finance. This is because air-gapped environments aren't exposed to the public internet; therefore, they create a controlled and secure space for handling sensitive data and operations. ### Prerequisites 1. Install `podman` or `docker` on the VM from where you're executing the installation commands. 2. Clone the Devtron Helm chart: ```bash git clone https://github.com/devtron-labs/devtron.git cd devtron ``` 3. Set the values of `TARGET_REGISTRY`, `TARGET_REGISTRY_USERNAME`, and `TARGET_REGISTRY_TOKEN`. This registry should be accessible from the VM where you are running the cloning script and the K8s cluster where you’re installing Devtron. {% hint style="warning" %} ### Note If you are using Docker, the TARGET_REGISTRY should be in the format `docker.io/` {% endhint %} --- ## Docker Instructions ### Platform Selection #### For Linux/amd64 ```bash export PLATFORM="linux/amd64" ``` #### For Linux/arm64 ```bash export PLATFORM="linux/arm64" ``` 1. Set the environment variables ```bash # Set the source registry URL export SOURCE_REGISTRY="quay.io/devtron" # Set the target registry URL, username, and token/password export TARGET_REGISTRY="" export TARGET_REGISTRY_USERNAME="" export TARGET_REGISTRY_TOKEN="" # Set the source and target image file names with default values if not already set SOURCE_IMAGES_LIST="${SOURCE_IMAGES_LIST:=devtron-images.txt.source}" TARGET_IMAGES_LIST="${TARGET_IMAGES_LIST:=devtron-images.txt.target}" ``` 2. Log in to the target Docker registry ```bash docker login -u $TARGET_REGISTRY_USERNAME -p $TARGET_REGISTRY_TOKEN $TARGET_REGISTRY ``` 3. Clone the images ```bash while IFS= read -r source_image; do # Check if the source image belongs to the quay.io/devtron registry if [[ "$source_image" == quay.io/devtron/* ]]; then # Replace the source registry with the target registry in the image name target_image="${source_image/quay.io\/devtron/$TARGET_REGISTRY}" # Check if the source image belongs to the quay.io/argoproj registry elif [[ "$source_image" == quay.io/argoproj/* ]]; then # Replace the source registry with the target registry in the image name target_image="${source_image/quay.io\/argoproj/$TARGET_REGISTRY}" # Check if the source image belongs to the public.ecr.aws/docker/library registry elif [[ "$source_image" == public.ecr.aws/docker/library/* ]]; then # Replace the source registry with the target registry in the image name target_image="${source_image/public.ecr.aws\/docker\/library/$TARGET_REGISTRY}" fi # Pull the image from the source registry docker pull --platform $PLATFORM $source_image # Tag the image with the new target registry name docker tag $source_image $target_image # Push the image to the target registry docker push $target_image # Output the updated image name echo "Updated image: $target_image" # Append the new image name to the target image file echo "$target_image" >> "$TARGET_IMAGES_LIST" done < "$SOURCE_IMAGES_LIST" ``` --- ## Podman Instructions ### For Multi-arch 1. Set the environment variables ```bash export SOURCE_REGISTRY="quay.io/devtron" export SOURCE_REGISTRY_TOKEN=#Enter token provided by Devtron team export TARGET_REGISTRY=#Enter target registry url export TARGET_REGISTRY_USERNAME=#Enter target registry username export TARGET_REGISTRY_TOKEN=#Enter target registry token/password ``` 2. Log in to the target Podman registry ```bash podman login -u $TARGET_REGISTRY_USERNAME -p $TARGET_REGISTRY_TOKEN $TARGET_REGISTRY ``` 3. Clone the images ```bash SOURCE_REGISTRY="quay.io/devtron" TARGET_REGISTRY=${TARGET_REGISTRY} SOURCE_IMAGES_FILE_NAME="${SOURCE_IMAGES_FILE_NAME:=devtron-images.txt.source}" TARGET_IMAGES_FILE_NAME="${TARGET_IMAGES_FILE_NAME:=devtron-images.txt.target}" cp $SOURCE_IMAGES_FILE_NAME $TARGET_IMAGES_FILE_NAME while read source_image; do if [[ "$source_image" == *"workflow-controller:"* || "$source_image" == *"argoexec:"* || "$source_image" == *"argocd:"* ]] then SOURCE_REGISTRY="quay.io/argoproj" sed -i "s|${SOURCE_REGISTRY}|${TARGET_REGISTRY}|g" $TARGET_IMAGES_FILE_NAME elif [[ "$source_image" == *"redis:"* ]] then SOURCE_REGISTRY="public.ecr.aws/docker/library" sed -i "s|${SOURCE_REGISTRY}|${TARGET_REGISTRY}|g" $TARGET_IMAGES_FILE_NAME else SOURCE_REGISTRY="quay.io/devtron" sed -i "s|${SOURCE_REGISTRY}|${TARGET_REGISTRY}|g" $TARGET_IMAGES_FILE_NAME fi done <$SOURCE_IMAGES_FILE_NAME echo "Target Images file finalized" while read -r -u 3 source_image && read -r -u 4 target_image ; do echo "Pushing $source_image $target_image" podman manifest create $source_image podman manifest add $source_image $source_image --all podman manifest push $source_image $target_image --all done 3<"$SOURCE_IMAGES_FILE_NAME" 4<"$TARGET_IMAGES_FILE_NAME" ``` --- ## Devtron Installation Before starting, ensure you have created an image pull secret for your registry if authentication is required. 1. Create the namespace (if not already created) ```bash kubectl create ns devtroncd ``` 2. Create the Docker registry secret ```bash kubectl create secret docker-registry devtron-imagepull \ --namespace devtroncd \ --docker-server=$TARGET_REGISTRY \ --docker-username=$TARGET_REGISTRY_USERNAME \ --docker-password=$TARGET_REGISTRY_TOKEN ``` If you are installing Devtron with the CI/CD module or using Argo CD, create the secret in the following namespaces else, you can skip this step-: ```bash kubectl create secret docker-registry devtron-imagepull \ --namespace devtron-cd \ --docker-server=$TARGET_REGISTRY \ --docker-username=$TARGET_REGISTRY_USERNAME \ --docker-password=$TARGET_REGISTRY_TOKEN kubectl create secret docker-registry devtron-imagepull \ --namespace devtron-ci \ --docker-server=$TARGET_REGISTRY \ --docker-username=$TARGET_REGISTRY_USERNAME \ --docker-password=$TARGET_REGISTRY_TOKEN kubectl create secret docker-registry devtron-imagepull \ --namespace argo \ --docker-server=$TARGET_REGISTRY \ --docker-username=$TARGET_REGISTRY_USERNAME \ --docker-password=$TARGET_REGISTRY_TOKEN ``` 3. Navigate to the Devtron Helm chart directory ```bash cd charts/devtron ``` ### Install Devtron without any Integration Use the below command to install Devtron without any Integrations 1. Without `imagePullSecrets`: ```bash helm install devtron . -n devtroncd --set global.containerRegistry="$TARGET_REGISTRY" ``` 2. With `imagePullSecrets`: ```bash helm install devtron . -n devtroncd --set global.containerRegistry="$TARGET_REGISTRY" --set global.imagePullSecrets[0].name=devtron-imagepull ``` ### Installing Devtron with CI/CD Mode Use the below command to install Devtron with only the CI/CD module 1. Without `imagePullSecrets`: ```bash helm install devtron . -n devtroncd --set installer.modules={cicd} --set global.containerRegistry="$TARGET_REGISTRY" ``` 2. With `imagePullSecrets`: ```bash helm install devtron . -n devtroncd --set installer.modules={cicd} --set global.containerRegistry="$TARGET_REGISTRY" --set global.imagePullSecrets[0].name=devtron-imagepull ``` ### Install Devtron with CICD Mode including Argocd Use the below command to install Devtron with the CI/CD module and Argo CD 1. Without `imagePullSecrets`: ```bash helm install devtron . --create-namespace -n devtroncd --set installer.modules={cicd} --set argo-cd.enabled=true --set global.containerRegistry="$TARGET_REGISTRY" --set argo-cd.global.image.repository="${TARGET_REGISTRY}/argocd" --set argo-cd.redis.image.repository="${TARGET_REGISTRY}/redis" ``` 2. With `imagePullSecrets`: ```bash helm install devtron . --create-namespace -n devtroncd --set installer.modules={cicd} --set argo-cd.enabled=true --set global.containerRegistry="$TARGET_REGISTRY" --set argo-cd.global.image.repository="${TARGET_REGISTRY}/argocd" --set argo-cd.redis.image.repository="${TARGET_REGISTRY}/redis" --set global.imagePullSecrets[0].name=devtron-imagepull ``` --- ## Next Steps After installation, refer [Devtron installation documentation](https://docs.devtron.ai/install/install-devtron-with-cicd-with-gitops#devtron-dashboard) for further steps, including obtaining the dashboard URL and the admin password. --- ### Setup Install Install Devtron With Cicd With Gitops (`docs/setup/install/install-devtron-with-cicd-with-gitops.md`) # Install Devtron with CI/CD along with GitOps (Argo CD) In this section, we describe the steps in detail on how you can install Devtron with CI/CD by enabling GitOps during the installation. ## Before you begin Install [Helm](https://helm.sh/docs/intro/install/) if you have not installed it. ## Install Devtron with CI/CD along with GitOps (Argo CD) Run the following command to install the latest version of Devtron with CI/CD along with GitOps (Argo CD) module: ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set installer.modules={cicd} \ --set argo-cd.enabled=true ``` **Note**: If you want to configure Blob Storage during the installation, refer [configure blob storage duing installation](#configure-blob-storage-during-installation). ## Install Multi-Architecture Nodes (ARM and AMD) To install Devtron on clusters with the multi-architecture nodes (ARM and AMD), append the Devtron installation command with `--set installer.arch=multi-arch`. **Note**: * If you want to install Devtron for `production deployments`, please refer to our recommended overrides for [Devtron Installation](override-default-devtron-installation-configs.md). ## Configure Blob Storage during Installation Configuring Blob Storage in your Devtron environment allows you to store build logs and cache. In case, if you do not configure the Blob Storage, then: - You will not be able to access the build and deployment logs after an hour. - Build time for commit hash takes longer as cache is not available. - Artifact reports cannot be generated in pre/post build and deployment stages. Choose one of the options to configure blob storage: {% tabs %} {% tab title="MinIO Storage" %} Run the following command to install Devtron along with MinIO for storing logs and cache. ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set installer.modules={cicd} \ --set minio.enabled=true \ --set argo-cd.enabled=true ``` **Note**: Unlike global cloud providers such as AWS S3 Bucket, Azure Blob Storage and Google Cloud Storage, MinIO can be hosted locally also. {% endtab %} {% tab title="AWS S3 Bucket" %} Refer to the `AWS specific` parameters on the [Storage for Logs and Cache](./installation-configuration.md#aws-specific) page. Run the following command to install Devtron along with AWS S3 buckets for storing build logs and cache: * Install using S3 IAM policy. >Note: Please ensure that S3 permission policy to the IAM role attached to the nodes of the cluster if you are using below command. ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set installer.modules={cicd} \ --set configs.BLOB_STORAGE_PROVIDER=S3 \ --set configs.DEFAULT_CACHE_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CACHE_BUCKET_REGION=us-east-1 \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CD_LOGS_BUCKET_REGION=us-east-1 \ --set argo-cd.enabled=true ``` * Install using access-key and secret-key for AWS S3 authentication: ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set installer.modules={cicd} \ --set configs.BLOB_STORAGE_PROVIDER=S3 \ --set configs.DEFAULT_CACHE_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CACHE_BUCKET_REGION=us-east-1 \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CD_LOGS_BUCKET_REGION=us-east-1 \ --set secrets.BLOB_STORAGE_S3_ACCESS_KEY= \ --set secrets.BLOB_STORAGE_S3_SECRET_KEY= \ --set argo-cd.enabled=true ``` * Install using S3 compatible storages: ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set installer.modules={cicd} \ --set configs.BLOB_STORAGE_PROVIDER=S3 \ --set configs.DEFAULT_CACHE_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CACHE_BUCKET_REGION=us-east-1 \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CD_LOGS_BUCKET_REGION=us-east-1 \ --set secrets.BLOB_STORAGE_S3_ACCESS_KEY= \ --set secrets.BLOB_STORAGE_S3_SECRET_KEY= \ --set configs.BLOB_STORAGE_S3_ENDPOINT= \ --set argo-cd.enabled=true ``` {% endtab %} {% tab title="Azure Blob Storage" %} Refer to the `Azure specific` parameters on the [Storage for Logs and Cache](./installation-configuration.md#azure-specific) page. Run the following command to install Devtron along with Azure Blob Storage for storing build logs and cache: ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set installer.modules={cicd} \ --set secrets.AZURE_ACCOUNT_KEY=xxxxxxxxxx \ --set configs.BLOB_STORAGE_PROVIDER=AZURE \ --set configs.AZURE_ACCOUNT_NAME=test-account \ --set configs.AZURE_BLOB_CONTAINER_CI_LOG=ci-log-container \ --set configs.AZURE_BLOB_CONTAINER_CI_CACHE=ci-cache-container \ --set argo-cd.enabled=true ``` {% endtab %} {% tab title="Google Cloud Storage" %} Refer to the `Google Cloud specific` parameters on the [Storage for Logs and Cache](./installation-configuration.md#google-cloud-storage-specific) page. Run the following command to install Devtron along with Google Cloud Storage for storing build logs and cache: ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set installer.modules={cicd} \ --set configs.BLOB_STORAGE_PROVIDER=GCP \ --set secrets.BLOB_STORAGE_GCP_CREDENTIALS_JSON=eyJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsInByb2plY3RfaWQiOiAiPHlvdXItcHJvamVjdC1pZD4iLCJwcml2YXRlX2tleV9pZCI6ICI8eW91ci1wcml2YXRlLWtleS1pZD4iLCJwcml2YXRlX2tleSI6ICI8eW91ci1wcml2YXRlLWtleT4iLCJjbGllbnRfZW1haWwiOiAiPHlvdXItY2xpZW50LWVtYWlsPiIsImNsaWVudF9pZCI6ICI8eW91ci1jbGllbnQtaWQ+IiwiYXV0aF91cmkiOiAiaHR0cHM6Ly9hY2NvdW50cy5nb29nbGUuY29tL28vb2F1dGgyL2F1dGgiLCJ0b2tlbl91cmkiOiAiaHR0cHM6Ly9vYXV0aDIuZ29vZ2xlYXBpcy5jb20vdG9rZW4iLCJhdXRoX3Byb3ZpZGVyX3g1MDlfY2VydF91cmwiOiAiaHR0cHM6Ly93d3cuZ29vZ2xlYXBpcy5jb20vb2F1dGgyL3YxL2NlcnRzIiwiY2xpZW50X3g1MDlfY2VydF91cmwiOiAiPHlvdXItY2xpZW50LWNlcnQtdXJsPiJ9Cg== \ --set configs.DEFAULT_CACHE_BUCKET=cache-bucket \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=log-bucket \ --set argo-cd.enabled=true ``` {% endtab %} {% endtabs %} ## Check Status of Devtron Installation **Note**: The installation takes about 15 to 20 minutes to spin up all of the Devtron microservices one by one. Run the following command to check the status of the installation: ```bash kubectl -n devtroncd get installers installer-devtron \ -o jsonpath='{.status.sync.status}' ``` The command executes with one of the following output messages, indicating the status of the installation: | Status | Description | | :--- | :--- | | `Downloaded` | The installer has downloaded all the manifests, and the installation is in progress. | | `Applied` | The installer has successfully applied all the manifests, and the installation is completed. | ## Check the installer logs Run the following command to check the installer logs: ```bash kubectl logs -f -l app=inception -n devtroncd ``` ## Devtron dashboard Run the following command to get the Devtron dashboard URL: ```bash kubectl get svc -n devtroncd devtron-service \ -o jsonpath='{.status.loadBalancer.ingress}' ``` You will get an output similar to the example shown below: ```bash [map[hostname:aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com]] ``` Use the hostname `aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com` (Loadbalancer URL) to access the Devtron dashboard. **Note**: If you do not get a hostname or receive a message that says "service doesn't exist," it means Devtron is still installing. Please wait until the installation is completed. **Note**: You can also use a `CNAME` entry corresponding to your domain/subdomain to point to the Loadbalancer URL to access at a customized domain. | Host | Type | Points to | | :--- | :--- | :--- | | devtron.yourdomain.com | CNAME | aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com | ## Devtron Admin credentials When you install Devtron for the first time, it creates a default admin user and password (with unrestricted access to Devtron). You can use that credentials to log in as an administrator. After the initial login, we recommend you set up any SSO service like Google, GitHub, etc., and then add other users (including yourself). Subsequently, all the users can use the same SSO (let's say, GitHub) to log in to Devtron's dashboard. The section below will help you understand the process of getting the administrator credentials. ### For Devtron version v0.6.0 and higher **Username**: `admin`
**Password**: Run the following command to get the admin password: ```bash kubectl -n devtroncd get secret devtron-secret \ -o jsonpath='{.data.ADMIN_PASSWORD}' | base64 -d ```
For Devtron version less than v0.6.0 **Username**: `admin`
**Password**: Run the following command to get the admin password: ```bash kubectl -n devtroncd get secret devtron-secret \ -o jsonpath='{.data.ACD_PASSWORD}' | base64 -d ```
* If you want to uninstall Devtron or clean Devtron helm installer, refer our [uninstall Devtron](../install/uninstall-devtron.md). * Related to installation, please also refer [FAQ](../install/faq-on-installation.md) section also. **Note**: If you have questions, please let us know on our discord channel. [](https://discord.gg/jsRG5qx2gp) --- ### Setup Install Install Devtron With Cicd (`docs/setup/install/install-devtron-with-cicd.md`) # Install Devtron with CI/CD In this section, we describe the steps in detail on how you can install Devtron with CI/CD integration. --- ## Prerequisites Install [Helm](https://helm.sh/docs/intro/install/), if you have not installed it already. {% hint style="info" %} If you are using EKS version 1.23 or above, you must also install [aws-ebs-csi-driver](https://docs.aws.amazon.com/eks/latest/userguide/ebs-csi.html). Run the following command to install AWS EBS CSI driver using Helm: ```bash helm repo add aws-ebs-csi-driver \ https://kubernetes-sigs.github.io/aws-ebs-csi-driver \ helm repo update \ helm upgrade --install aws-ebs-csi-driver \ --namespace kube-system aws-ebs-csi-driver/aws-ebs-csi-driver ``` {% endhint %} --- ## Command Run the following command to install the latest version of Devtron along with the CI/CD module: ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set installer.modules={cicd} ``` {% hint style="info" %} If you want to configure Blob Storage during the installation, refer [configure blob storage duing installation](#configure-blob-storage-during-installation). {% endhint %} --- ## Install Multi-Architecture Nodes (ARM and AMD) To install Devtron on clusters with the multi-architecture nodes (ARM and AMD), append the Devtron installation command with `--set installer.arch=multi-arch`. {% hint style="info" %} If you want to install Devtron for `production deployments`, please refer our [recommended overrides](override-default-devtron-installation-configs.md) for Devtron Installation. {% endhint %} --- ## Configure Blob Storage during Installation Configuring Blob Storage in your Devtron environment allows you to store build logs and cache. In case, if you do not configure the Blob Storage, then: - You will not be able to access the build and deployment logs after an hour. - Build time for commit hash takes longer as cache is not available. - Artifact reports cannot be generated in pre/post build and deployment stages. Choose one of the options to configure blob storage: {% tabs %} {% tab title="MinIO Storage" %} Run the following command to install Devtron along with MinIO for storing logs and cache. ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set installer.modules={cicd} \ --set minio.enabled=true ``` **Note**: Unlike global cloud providers such as AWS S3 Bucket, Azure Blob Storage and Google Cloud Storage, MinIO can be hosted locally also. {% endtab %} {% tab title="AWS S3 Bucket" %} Refer to the `AWS specific` parameters on the [Storage for Logs and Cache](./installation-configuration.md#aws-specific) page. Run the following command to install Devtron along with AWS S3 buckets for storing build logs and cache: * Install using S3 IAM policy. >Note: Please ensure that S3 permission policy to the IAM role attached to the nodes of the cluster if you are using below command. ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set installer.modules={cicd} \ --set configs.BLOB_STORAGE_PROVIDER=S3 \ --set configs.DEFAULT_CACHE_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CACHE_BUCKET_REGION=us-east-1 \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CD_LOGS_BUCKET_REGION=us-east-1 ``` * Install using access-key and secret-key for AWS S3 authentication: ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set installer.modules={cicd} \ --set configs.BLOB_STORAGE_PROVIDER=S3 \ --set configs.DEFAULT_CACHE_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CACHE_BUCKET_REGION=us-east-1 \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CD_LOGS_BUCKET_REGION=us-east-1 \ --set secrets.BLOB_STORAGE_S3_ACCESS_KEY= \ --set secrets.BLOB_STORAGE_S3_SECRET_KEY= ``` * Install using S3 compatible storages: ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set installer.modules={cicd} \ --set configs.BLOB_STORAGE_PROVIDER=S3 \ --set configs.DEFAULT_CACHE_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CACHE_BUCKET_REGION=us-east-1 \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CD_LOGS_BUCKET_REGION=us-east-1 \ --set secrets.BLOB_STORAGE_S3_ACCESS_KEY= \ --set secrets.BLOB_STORAGE_S3_SECRET_KEY= \ --set configs.BLOB_STORAGE_S3_ENDPOINT= ``` {% endtab %} {% tab title="Azure Blob Storage" %} Refer to the `Azure specific` parameters on the [Storage for Logs and Cache](./installation-configuration.md#azure-specific) page. Run the following command to install Devtron along with Azure Blob Storage for storing build logs and cache: ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set installer.modules={cicd} \ --set secrets.AZURE_ACCOUNT_KEY=xxxxxxxxxx \ --set configs.BLOB_STORAGE_PROVIDER=AZURE \ --set configs.AZURE_ACCOUNT_NAME=test-account \ --set configs.AZURE_BLOB_CONTAINER_CI_LOG=ci-log-container \ --set configs.AZURE_BLOB_CONTAINER_CI_CACHE=ci-cache-container ``` {% endtab %} {% tab title="Google Cloud Storage" %} Refer to the `Google Cloud specific` parameters on the [Storage for Logs and Cache](./installation-configuration.md#google-cloud-storage-specific) page. Run the following command to install Devtron along with Google Cloud Storage for storing build logs and cache: ```bash helm repo add devtron https://helm.devtron.ai helm repo update devtron helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd \ --set installer.modules={cicd} \ --set configs.BLOB_STORAGE_PROVIDER=GCP \ --set secrets.BLOB_STORAGE_GCP_CREDENTIALS_JSON=eyJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsInByb2plY3RfaWQiOiAiPHlvdXItcHJvamVjdC1pZD4iLCJwcml2YXRlX2tleV9pZCI6ICI8eW91ci1wcml2YXRlLWtleS1pZD4iLCJwcml2YXRlX2tleSI6ICI8eW91ci1wcml2YXRlLWtleT4iLCJjbGllbnRfZW1haWwiOiAiPHlvdXItY2xpZW50LWVtYWlsPiIsImNsaWVudF9pZCI6ICI8eW91ci1jbGllbnQtaWQ+IiwiYXV0aF91cmkiOiAiaHR0cHM6Ly9hY2NvdW50cy5nb29nbGUuY29tL28vb2F1dGgyL2F1dGgiLCJ0b2tlbl91cmkiOiAiaHR0cHM6Ly9vYXV0aDIuZ29vZ2xlYXBpcy5jb20vdG9rZW4iLCJhdXRoX3Byb3ZpZGVyX3g1MDlfY2VydF91cmwiOiAiaHR0cHM6Ly93d3cuZ29vZ2xlYXBpcy5jb20vb2F1dGgyL3YxL2NlcnRzIiwiY2xpZW50X3g1MDlfY2VydF91cmwiOiAiPHlvdXItY2xpZW50LWNlcnQtdXJsPiJ9Cg== \ --set configs.DEFAULT_CACHE_BUCKET=cache-bucket \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=log-bucket ``` {% endtab %} {% endtabs %} --- ## Check Status of Devtron Installation {% hint style="info" %} The installation takes about 15 to 20 minutes to spin up all of the Devtron microservices one by one {% endhint %} Run the following command to check the status of the installation: ```bash kubectl -n devtroncd get installers installer-devtron \ -o jsonpath='{.status.sync.status}' ``` The command executes with one of the following output messages, indicating the status of the installation: | Status | Description | | :--- | :--- | | `Downloaded` | The installer has downloaded all the manifests, and the installation is in progress. | | `Applied` | The installer has successfully applied all the manifests, and the installation is completed. | --- ## Check the Installer Logs Run the following command to check the installer logs: ```bash kubectl logs -f -l app=inception -n devtroncd ``` --- ## Devtron Dashboard Run the following command to get the Devtron dashboard URL: ```bash kubectl get svc -n devtroncd devtron-service \ -o jsonpath='{.status.loadBalancer.ingress}' ``` You will get an output similar to the example shown below: ```bash [map[hostname:aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com]] ``` Use the hostname `aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com` (Loadbalancer URL) to access the Devtron dashboard. {% hint style="info" %} If you do not get a hostname or receive a message that says "service doesn't exist," it means Devtron is still installing. Please wait until the installation is completed. {% endhint %} {% hint style="info" %} You can also use a `CNAME` entry corresponding to your domain/subdomain to point to the Loadbalancer URL to access at a customized domain. {% endhint %} | Host | Type | Points to | | :--- | :--- | :--- | | devtron.yourdomain.com | CNAME | aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com | --- ## Devtron Admin Credentials When you install Devtron for the first time, it creates a default admin user and password (with unrestricted access to Devtron). You can use that credentials to log in as an administrator. After the initial login, we recommend you set up any SSO service like Google, GitHub, etc., and then add other users (including yourself). Subsequently, all the users can use the same SSO (let's say, GitHub) to log in to Devtron's dashboard. The sections below will help you understand the process of getting the administrator password. ### For Devtron version v0.6.0 and higher **Username**: `admin`
**Password**: Run the following command to get the admin password: ```bash kubectl -n devtroncd get secret devtron-secret \ -o jsonpath='{.data.ADMIN_PASSWORD}' | base64 -d ```
For Devtron version less than v0.6.0 **Username**: `admin`
**Password**: Run the following command to get the admin password: ```bash kubectl -n devtroncd get secret devtron-secret \ -o jsonpath='{.data.ACD_PASSWORD}' | base64 -d ```
* If you want to uninstall Devtron or clean Devtron helm installer, refer our [uninstall Devtron](../install/uninstall-devtron.md). * Related to installaltion, please also refer [FAQ](../install/faq-on-installation.md) section also. {% hint style="info" %} If you have any questions, please let us know on our Discord channel. [](https://discord.gg/jsRG5qx2gp) {% endhint %} --- ### Setup Install Install Devtron (`docs/setup/install/install-devtron.md`) # Install Devtron In this section, we describe on how you can install Helm Dashboard by Devtron without any integrations. Integrations can be added later using [Devtron Stack Manager](../../user-guide/stack-manager.md). If you want to install Devtron on Minikube, Microk8s, K3s, Kind, refer this [section](./Install-devtron-on-Minikube-Microk8s-K3s-Kind.md). ## Before you begin Install [Helm](https://helm.sh/docs/intro/install/) if you have not installed it. ## Add Helm Repo ```bash helm repo add devtron https://helm.devtron.ai ``` ## Update Helm Repo ```bash helm repo update devtron ``` ## Install Helm Dashboard by Devtron **Note**: This installation command will not install CI/CD integration. For CI/CD, refer [install Devtron with CI/CD](../install/install-devtron-with-cicd.md) section. Run the following command to install Helm Dashboard by Devtron: ```bash helm install devtron devtron/devtron-operator \ --create-namespace --namespace devtroncd ``` ## Install Multi-Architecture Nodes (ARM and AMD) To install Devtron on clusters with the multi-architecture nodes (ARM and AMD), append the Devtron installation command with `--set installer.arch=multi-arch`. [//]: # (If you are planning to use Hyperion for `production deployments`, please refer to our recommended overrides for [Devtron Installation](override-default-devtron-installation-configs.md).) [//]: # (## Installation status) [//]: # () [//]: # (Run following command) [//]: # () [//]: # (```bash) [//]: # (kubectl -n devtroncd get installers installer-devtron -o jsonpath='{.status.sync.status}') [//]: # (```) ## Devtron Dashboard Run the following command to get the dashboard URL: ```text kubectl get svc -n devtroncd devtron-service -o jsonpath='{.status.loadBalancer.ingress}' ``` You will get the result something as shown below: ```text [test2@server ~]$ kubectl get svc -n devtroncd devtron-service -o jsonpath='{.status.loadBalancer.ingress}' [map[hostname:aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com]] ``` The hostname `aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com` as mentioned above is the Loadbalancer URL where you can access the Devtron dashboard. > You can also do a CNAME entry corresponding to your domain/subdomain to point to this Loadbalancer URL to access it at a custom domain. | Host | Type | Points to | | :--- | :--- | :--- | | devtron.yourdomain.com | CNAME | aaff16e9760594a92afa0140dbfd99f7-305259315.us-east-1.elb.amazonaws.com | ## Devtron Admin credentials When you install Devtron for the first time, it creates a default admin user and password (with unrestricted access to Devtron). You can use that credentials to log in as an administrator. After the initial login, we recommend you set up any SSO service like Google, GitHub, etc., and then add other users (including yourself). Subsequently, all the users can use the same SSO (let's say, GitHub) to log in to Devtron's dashboard. The section below will help you understand the process of getting the administrator credentials. ### For Devtron version v0.6.0 and higher **Username**: `admin`
**Password**: Run the following command to get the admin password: ```bash kubectl -n devtroncd get secret devtron-secret \ -o jsonpath='{.data.ADMIN_PASSWORD}' | base64 -d ```
For Devtron version less than v0.6.0 **Username**: `admin`
**Password**: Run the following command to get the admin password: ```bash kubectl -n devtroncd get secret devtron-secret \ -o jsonpath='{.data.ACD_PASSWORD}' | base64 -d ```
**Note**: If you want to uninstall Devtron or clean Devtron helm installer, refer our [uninstall Devtron](../install/uninstall-devtron.md). ## Upgrade To use the CI/CD capabilities with Devtron, you can Install the [Devtron with CI/CD](../install/install-devtron-with-cicd.md) or [Devtron with CI/CD along with GitOps (Argo CD)](../install/install-devtron-with-cicd-with-gitops.md). --- ### Setup Install Installation Configuration (`docs/setup/install/installation-configuration.md`) # Installation Configuration ## Configure Secrets For `Helm` installation this section refers to _**secrets**_ section of `values.yaml`. Configure the following properties: | Parameter | Description | Default | | :--- | :--- | :--- | | **POSTGRESQL\_PASSWORD** | Using this parameter the auto-generated password for Postgres can be edited as per requirement(Used by Devtron to store the app information) | NA | | **WEBHOOK\_TOKEN** | If you want to continue using Jenkins for CI then provide this for authentication of requests should be base64 encoded | NA | ## Configure ConfigMaps For `Helm` installation this section refers to _**configs**_ section of `values.yaml`. Configure the following properties: | Parameter | Description | Default | | :--- | :--- | :--- | | **BASE\_URL\_SCHEME** | Either of HTTP or HTTPS \(required\) | HTTP | | **BASE\_URL** | URL without scheme and trailing slash, this is the domain pointing to the cluster on which the Devtron platform is being installed. For example, if you have directed domain `devtron.example.com` to the cluster and the ingress controller is listening on port `32080` then URL will be `devtron.example.com:32080` \(required\) | `change-me` | | **DEX\_CONFIG** | dex config if you want to integrate login with SSO \(optional\) for more information check [Argocd documentation](https://argo-cd.readthedocs.io/en/stable/operator-manual/user-management/) | NA | | **EXTERNAL\_SECRET\_AMAZON\_REGION** | AWS region for the secret manager to pick \(required\) | NA | | **PROMETHEUS\_URL** | URL of Prometheus where all cluster data is stored; if this is wrong, you will not be able to see application metrics like CPU, RAM, HTTP status code, latency, and throughput \(required\) | NA | ## Configure Resources Devtron provides ways to control how much `memory` or `CPU` can be allocated to each Devtron microservice. You can adjust the resources that are allocated to these microservices based on your requirements. The resource configurations are available in following sizes: **`Small`**: To configure the small resources (e.g. to manage less than 10 apps on Devtron ) based on the requirements, append the Devtron installation command with `-f https://raw.githubusercontent.com/devtron-labs/devtron/main/charts/devtron/resources-small.yaml`. ## Configure Overrides For `Helm` installation this section refers to _**customOverrides**_ section of `values.yaml`. In this section you can override values of devtron-cm which you want to keep persistent. For example: You can configure the following properties: | Parameter | Description | Default | | :--- | :--- | :--- | | **CI\_NODE\_LABEL\_SELECTOR** | Labels for a particular nodegroup which you want to use for running CIs | NA | | **CI\_NODE\_TAINTS\_KEY** | Key for toleration if nodegroup chosen for CIs have some taints | NA | | **CI\_NODE\_TAINTS\_VALUE** | Value for toleration if nodegroup chosen for CIs have some taints | NA | ### Storage for Logs and Cache #### `AWS SPECIFIC` While installing Devtron and using the AWS-S3 bucket for storing the logs and caches, the below parameters are to be used in the ConfigMap. > NOTE: For using the S3 bucket it is important to add the S3 permission policy to the IAM role attached to the nodes of the cluster. | Parameter | Description | Default | | :--- | :--- | :--- | | **DEFAULT\_CACHE\_BUCKET** | AWS bucket to store docker cache, it should be created beforehand \(required\) | | | **DEFAULT\_BUILD\_LOGS\_BUCKET** | AWS bucket to store build logs, it should be created beforehand \(required\) | | | **DEFAULT\_CACHE\_BUCKET\_REGION** | AWS region of S3 bucket to store cache \(required\) | | | **DEFAULT\_CD\_LOGS\_BUCKET\_REGION** | AWS region of S3 bucket to store CD logs \(required\) | | | **BLOB_STORAGE_S3_ENDPOINT** | S3 compatible bucket endpoint. | | The below parameters are to be used in the Secrets : | Parameter | Description | | :--- | :--- | | **BLOB_STORAGE_S3_ACCESS_KEY** | AWS access key to access S3 bucket. Required if installing using AWS credentials. | | **BLOB_STORAGE_S3_SECRET_KEY** | AWS secret key to access S3 bucket. Required if installing using AWS credentials. | #### `AZURE SPECIFIC` While installing Devtron using Azure Blob Storage for storing logs and caches, the below parameters will be used in the ConfigMap. | Parameter | Description | | :--- | :--- | | **AZURE\_ACCOUNT\_NAME** | Account name for AZURE Blob Storage | | | **AZURE\_BLOB\_CONTAINER\_CI\_LOG** | AZURE Blob storage container for storing ci-logs after running the CI pipeline | | | **AZURE\_BLOB\_CONTAINER\_CI\_CACHE** | AZURE Blob storage container for storing ci-cache after running the CI pipeline | | #### `GOOGLE CLOUD STORAGE SPECIFIC` While installing Devtron using Google Cloud Storage for storing logs and caches, the below parameters will be used in the ConfigMap. | Parameter | Description | Default | | :--- | :--- | :--- | | **BLOB_STORAGE_GCP_CREDENTIALS_JSON** | Base-64 encoded GCP credentials json for accessing Google Cloud Storage | | | **DEFAULT_CACHE_BUCKET** | Google Cloud Storage bucket for storing ci-logs after running the CI pipeline | | | **DEFAULT_LOGS_BUCKET** | Google Cloud Storage bucket for storing ci-cache after running the CI pipeline | | To convert string to base64 use the following command: ```bash echo -n "string" | base64 ``` > **Note**: > 1. Ensure that the **cluster has read and write access** to the S3 buckets/Azure Blob storage container mentioned in DEFAULT\_CACHE\_BUCKET, DEFAULT\_BUILD\_LOGS\_BUCKET or AZURE\_BLOB\_CONTAINER\_CI\_LOG, or AZURE\_BLOB\_CONTAINER\_CI\_CACHE. > 2. Ensure that the cluster has **read access** to AWS secrets backends \(SSM & secrets manager\). --- The following tables contain parameters and their details for Secrets and ConfigMaps that are configured during the installation of Devtron. If the installation is done using `Helm`, the values can be tweaked in [values.yaml](https://github.com/devtron-labs/charts/blob/main/charts/devtron/values.yaml) file. We can use the `--set` flag to override the default values when installing with Helm. For example, to update POSTGRESQL_PASSWORD and BLOB_STORAGE_PROVIDER, use the install command as: ```bash helm install devtron devtron/devtron-operator --create-namespace --namespace devtroncd \ --set secrets.POSTGRESQL_PASSWORD=change-me \ --set configs.BLOB_STORAGE_PROVIDER=S3 ``` ## Configuration of Blob Storage Blob Storage allows users to store large amounts of unstructured data. Unstructured data is a data that does not adhere to a particular data model or definition, such as text or binary data. Configuring blob storage in your Devtron environment allows you to store build logs and cache. In case, if you do not configure the Blob Storage, then: - You will not be able to access the build and deployment logs after an hour. - Build time for commit hash takes longer as cache is not available. - Artifact reports cannot be generated in pre/post build and deployment stages. You can configure Blob Storage with one of the following Blob Storage providers given below: **Note**: You can also use the respective following command to switch to another Blob Storage provider. As an example, If you are using MinIO Storage and want to switch to Azure Blob Storage, use the command provided on the Azure Blob Storage tab to switch. {% tabs %} {% tab title="MinIO Storage" %} Use the following command to configure MinIO for storing logs and cache. **Note**: Unlike global cloud providers such as AWS S3 Bucket, Azure Blob Storage and Google Cloud Storage, MinIO can be hosted locally also. ```bash helm repo update helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ --reuse-values \ --set installer.modules={cicd} \ --set minio.enabled=true ``` {% endtab %} {% tab title="AWS S3 Bucket" %} Use the following command to configure AWS S3 bucket for storing build logs and cache. Refer to the `AWS specific` parameters on the [Storage for Logs and Cache](#aws-specific) page. * **Configure using S3 IAM policy:** >NOTE: Pleasee ensure that S3 permission policy to the IAM role attached to the nodes of the cluster if you are using the below command. ```bash helm repo update helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ --reuse-values \ --set installer.modules={cicd} \ --set configs.BLOB_STORAGE_PROVIDER=S3 \ --set configs.DEFAULT_CACHE_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CACHE_BUCKET_REGION=us-east-1 \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CD_LOGS_BUCKET_REGION=us-east-1 ``` * **Configure using access-key and secret-key for aws S3 authentication:** ```bash helm repo update helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ --reuse-values \ --set installer.modules={cicd} \ --set configs.BLOB_STORAGE_PROVIDER=S3 \ --set configs.DEFAULT_CACHE_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CACHE_BUCKET_REGION=us-east-1 \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CD_LOGS_BUCKET_REGION=us-east-1 \ --set secrets.BLOB_STORAGE_S3_ACCESS_KEY= \ --set secrets.BLOB_STORAGE_S3_SECRET_KEY= ``` * **Configure using S3 compatible storages:** ```bash helm repo update helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ --reuse-values \ --set installer.modules={cicd} \ --set configs.BLOB_STORAGE_PROVIDER=S3 \ --set configs.DEFAULT_CACHE_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CACHE_BUCKET_REGION=us-east-1 \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=demo-s3-bucket \ --set configs.DEFAULT_CD_LOGS_BUCKET_REGION=us-east-1 \ --set secrets.BLOB_STORAGE_S3_ACCESS_KEY= \ --set secrets.BLOB_STORAGE_S3_SECRET_KEY= \ --set configs.BLOB_STORAGE_S3_ENDPOINT= ``` {% endtab %} {% tab title="Azure Blob Storage" %} Use the following command to configure Azure Blob Storage for storing build logs and cache. Refer to the `Azure specific` parameters on the [Storage for Logs and Cache](#azure-specific) page. ```bash helm repo update helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ --reuse-values \ --set installer.modules={cicd} \ --set secrets.AZURE_ACCOUNT_KEY=xxxxxxxxxx \ --set configs.BLOB_STORAGE_PROVIDER=AZURE \ --set configs.AZURE_ACCOUNT_NAME=test-account \ --set configs.AZURE_BLOB_CONTAINER_CI_LOG=ci-log-container \ --set configs.AZURE_BLOB_CONTAINER_CI_CACHE=ci-cache-container ``` {% endtab %} {% tab title="Google Cloud Storage" %} Use the following command to configure Google Cloud Storage for storing build logs and cache. Refer to the `Google Cloud specific` parameters on the [Storage for Logs and Cache](#google-cloud-storage-specific) page. ```bash helm repo update helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ --reuse-values \ --set installer.modules={cicd} \ --set configs.BLOB_STORAGE_PROVIDER=GCP \ --set secrets.BLOB_STORAGE_GCP_CREDENTIALS_JSON=eyJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsInByb2plY3RfaWQiOiAiPHlvdXItcHJvamVjdC1pZD4iLCJwcml2YXRlX2tleV9pZCI6ICI8eW91ci1wcml2YXRlLWtleS1pZD4iLCJwcml2YXRlX2tleSI6ICI8eW91ci1wcml2YXRlLWtleT4iLCJjbGllbnRfZW1haWwiOiAiPHlvdXItY2xpZW50LWVtYWlsPiIsImNsaWVudF9pZCI6ICI8eW91ci1jbGllbnQtaWQ+IiwiYXV0aF91cmkiOiAiaHR0cHM6Ly9hY2NvdW50cy5nb29nbGUuY29tL28vb2F1dGgyL2F1dGgiLCJ0b2tlbl91cmkiOiAiaHR0cHM6Ly9vYXV0aDIuZ29vZ2xlYXBpcy5jb20vdG9rZW4iLCJhdXRoX3Byb3ZpZGVyX3g1MDlfY2VydF91cmwiOiAiaHR0cHM6Ly93d3cuZ29vZ2xlYXBpcy5jb20vb2F1dGgyL3YxL2NlcnRzIiwiY2xpZW50X3g1MDlfY2VydF91cmwiOiAiPHlvdXItY2xpZW50LWNlcnQtdXJsPiJ9Cg== \ --set configs.DEFAULT_CACHE_BUCKET=cache-bucket \ --set configs.DEFAULT_BUILD_LOGS_BUCKET=log-bucket ``` {% endtab %} {% endtabs %} ## Secrets |Parameter | Description| Default| Necessity| |-|-|-|-| |ACD_PASSWORD | ArgoCD Password for CD Workflow| Auto-Generated| Optional| |AZURE_ACCOUNT_KEY | Account key to access Azure objects such as BLOB_CONTAINER_CI_LOG or CI_CACHE| ""| Mandatory (If using Azure)| |GRAFANA_PASSWORD | Password for Grafana to display graphs| Auto-Generated| Optional| |POSTGRESQL_PASSWORD | Password for your Postgresql database that will be used to access the database| Auto-Generated| Optional| ## ConfigMaps |Parameter | Description| Default| Necessity| |-|-|-|-| |AZURE_ACCOUNT_NAME | Azure account name which you will use| ""| Mandatory (If using Azure)| |AZURE_BLOB_CONTAINER_CI_LOG | Name of container created for storing CI_LOG| ci-log-container| Optional| |AZURE_BLOB_CONTAINER_CI_CACHE | Name of container created for storing CI_CACHE| ci-cache-container| Optional| |BLOB_STORAGE_PROVIDER | Cloud provider name which you will use| MINIO| Mandatory (If using any cloud other than MINIO), MINIO/AZURE/S3| |DEFAULT_BUILD_LOGS_BUCKET | S3 Bucket name used for storing Build Logs| devtron-ci-log| Mandatory (If using AWS)| |DEFAULT_CD_LOGS_BUCKET_REGION | Region of S3 Bucket where CD Logs are being stored| us-east-1| Mandatory (If using AWS)| |DEFAULT_CACHE_BUCKET | S3 Bucket name used for storing CACHE (Do not include s3://)| devtron-ci-cache| Mandatory (If using AWS)| |DEFAULT_CACHE_BUCKET_REGION | S3 Bucket region where Cache is being stored| us-east-1| Mandatory (If using AWS)| |EXTERNAL_SECRET_AMAZON_REGION | Region where the cluster is setup for Devtron installation| ""| Mandatory (If using AWS)| |ENABLE_INGRESS | To enable Ingress (True/False)| False| Optional| |INGRESS_ANNOTATIONS | Annotations for ingress| ""| Optional| |PROMETHEUS_URL | Existing Prometheus URL if it is installed| ""| Optional| |CI_NODE_LABEL_SELECTOR | Label of CI worker node| "" | Optional| |CI_NODE_TAINTS_KEY | Taint key name of CI worker node | "" | Optional| |CI_NODE_TAINTS_VALUE | Value of taint key of CI node | "" | Optional| |CI_DEFAULT_ADDRESS_POOL_BASE_CIDR | CIDR ranges used to allocate subnets in each IP address pool for CI | "" | Optional| |CI_DEFAULT_ADDRESS_POOL_SIZE | The subnet size to allocate from the base pool for CI | "" | Optional| |CD_NODE_LABEL_SELECTOR | Label of CD node | kubernetes.io/os=linux| Optional| |CD_NODE_TAINTS_KEY| Taint key name of CD node| dedicated | Optional| |CD_NODE_TAINTS_VALUE| Value of taint key of CD node| ci | Optional| |CD_LIMIT_CI_CPU| CPU limit for pre and post CD Pod |0.5| Optional| |CD_LIMIT_CI_MEM| Memory limit for pre and post CD Pod|3G|Optional| |CD_REQ_CI_CPU| CPU request for CI Pod|0.5|Optional| |CD_REQ_CI_MEM|Memory request for CI Pod |1G|Optional| |CD_DEFAULT_ADDRESS_POOL_BASE_CIDR | CIDR ranges used to allocate subnets in each IP address pool for CD | "" | Optional| |CD_DEFAULT_ADDRESS_POOL_SIZE | The subnet size to allocate from the base pool for CD | "" | Optional| |GITOPS_REPO_PREFIX | Prefix for Gitops repository | devtron |Optional| ## Dashboard Configurations ```bash RECOMMEND_SECURITY_SCANNING=false FORCE_SECURITY_SCANNING=false HIDE_DISCORD=false ``` |Parameter | Description| |-|-| |RECOMMEND_SECURITY_SCANNING | If True, `security scanning` is `enabled` by default for a new build pipeline. Users can however turn it off in the new or existing pipelines.| |FORCE_SECURITY_SCANNING | If set to True, `security scanning` is forcefully `enabled` by default for a new build pipeline. Users can not turn it off for new as well as for existing build pipelines. Old pipelines that have security scanning disabled will remain unchanged and image scanning should be enabled manually for them.| |HIDE_DISCORD | Hides discord chatbot from the dashboard.| --- ### Setup Install Override Default Devtron Installation Configs (`docs/setup/install/override-default-devtron-installation-configs.md`) # Override Default Configurations of Devtron Installation In certain cases, you may want to override default configurations provided by Devtron. For example, for deployments or statefulsets you may want to change the memory or CPU requests or limit or add node affinity or taint tolerance. Say, for ingress, you may want to add annotations or host. Samples are available inside the [manifests/updates](https://github.com/devtron-labs/devtron/tree/main/manifests/updates) directory. To modify a particular object, it looks in namespace `devtroncd` for the corresponding configmap as mentioned in the mapping below: |component| configmap name| purpose| |-|-|-| |argocd| argocd-override-cm| GitOps | |clair|clair-override-cm| container vulnerability db| |clair| clair-config-override-cm| Clair configuration| |dashboard| dashboard-override-cm| UI for Devtron| |gitSensor| git-sensor-override-cm| microservice for Git interaction| |guard| guard-override-cm| validating webhook to block images with security violations| |postgresql| postgresql-override-cm| db store of Devtron| |imageScanner| image-scanner-override-cm| image scanner for vulnerability| |kubewatch| kubewatch-override-cm| watches changes in ci and cd running in different clusters| |lens| lens-override-cm| deployment metrics analysis| |natsOperator| nats-operator-override-cm| operator for nats| |natsServer| nats-server-override-cm| nats server| |natsStreaming| nats-streaming-override-cm| nats streaming server| |notifier| notifier-override-cm| sends notification related to CI and CD | |devtron| devtron-override-cm| core engine of Devtron| |devtronIngress| devtron-ingress-override-cm| ingress configuration to expose Devtron| |workflow| workflow-override-cm| component to run CI workload| |externalSecret| external-secret-override-cm| manage secret through external stores like vault/AWS secret store| |grafana| grafana-override-cm| Grafana config for dashboard| |rollout| rollout-override-cm| manages blue-green and canary deployments| |minio| minio-override-cm| default store for CI logs and image cache| |minioStorage| minio-storage-override-cm| db config for minio| Let's take an example to understand how to override specific values. Say, you want to override annotations and host in the ingress, i.e., you want to change devtronIngress, copy the file [devtron-ingress-override.yaml](https://github.com/devtron-labs/devtron/tree/main/manifests/updates/devtron-ingress-override.yaml). This file contains a configmap to modify devtronIngress as mentioned above. Please note the structure of this configmap, data should have the key `override` with a multiline string as a value. `apiVersion`, `kind`, `metadata.name` in the multiline string is used to match the object which needs to be modified. In this particular case it will look for `apiVersion: extensions/v1beta1`, `kind: Ingress` and `metadata.name: devtron-ingress` and will apply changes mentioned inside `update:` as per the example inside the `metadata:` it will add annotations `owner: app1` and inside `spec.rules.http.host` it will add `http://change-me`. In case you want to change multiple objects, for eg in `argocd` you want to change the config of `argocd-dex-server` as well as `argocd-redis` then follow the example in [devtron-argocd-override.yaml](https://github.com/devtron-labs/devtron/tree/main/manifests/updates/devtron-argocd-override.yaml). Once we have made these changes in our local system we need to apply them to a Kubernetes cluster on which Devtron is installed currently using the below command: ```bash kubectl apply -f file-name -n devtroncd ``` Run the following command to make these changes take effect: ```bash kubectl patch -n devtroncd installer installer-devtron --type='json' -p='[{"op": "add", "path": "/spec/reSync", "value": true }]' ``` Our changes would have been propagated to Devtron after 20-30 minutes. ## Recommended Resources for Production use To use Devtron for production deployments, use our recommended production overrides located in [manifests/updates/production](https://github.com/devtron-labs/devtron/tree/main/manifests/updates/production). This configuration should be enough for handling up to 200 microservices. The overall resources required for the recommended production overrides are: |Name| Value| |-|-| |cpu| 6| |memory|13GB| The production overrides can be applied as `pre-devtron installation` as well as `post-devtron installation` in the respective namespace. ### Pre-Devtron Installation If you want to install a new Devtron instance for production-ready deployments, this is the best option for you. Create the namespace and apply the overrides files as stated above: ```bash kubectl create ns devtroncd ``` After files are applied, you are ready to install your Devtron instance with production-ready resources. ### Post-Devtron Installation If you have an existing Devtron instance and want to migrate it for production-ready deployments, this is the right option for you. In the existing namespace, apply the production overrides as we do it above. ```bash kubectl apply -f prod-configs -n devtroncd ``` --- ### Setup Install Uninstall Devtron (`docs/setup/install/uninstall-devtron.md`) # Uninstall Devtron To uninstall Devtron, run the following command: This command will remove all the namespaces related to Devtron (`devtroncd`, `devtron-cd`, `devtron-ci` etc.). ```bash helm uninstall devtron --namespace devtroncd kubectl delete -n devtroncd -f https://raw.githubusercontent.com/devtron-labs/charts/main/charts/devtron/crds/crd-devtron.yaml kubectl delete -n argo -f https://raw.githubusercontent.com/devtron-labs/devtron/main/manifests/yamls/workflow.yaml kubectl delete ns devtroncd devtron-cd devtron-ci devtron-demo argo ``` **Note**: If you have questions, please let us know on our discord channel. [](https://discord.gg/jsRG5qx2gp) --- ### Setup Upgrade Devtron Upgrade 0.2.X 0.3.X (`docs/setup/upgrade/devtron-upgrade-0.2.x-0.3.x.md`) # Upgrading Devtron 0.2.x to 0.3.x ## Follow the required steps to update the Devtron version #### STEP 1 Delete the respective resources i.e, nats-operator , nats-streaming and nats-server using the following commands. ```bash kubectl delete -f https://raw.githubusercontent.com/devtron-labs/devtron/v0.2.37/manifests/yamls/nats-operator.yaml kubectl -n devtroncd delete -f https://raw.githubusercontent.com/devtron-labs/devtron/v0.2.37/manifests/yamls/nats-streaming.yaml kubectl -n devtroncd delete -f https://raw.githubusercontent.com/devtron-labs/devtron/v0.2.37/manifests/yamls/nats-server.yaml ``` #### STEP 2 Verify the deletion of resources using the following commands. ```bash kubectl -n devtroncd get pods kubectl -n devtroncd get serviceaccount kubectl -n devtroncd get clusterrole ``` #### STEP 3 Set `reSync: true` in the installer object, this will initiate upgrade of the entire Devtron stack, you can use the following command to do this. ```bash kubectl patch -n devtroncd installer installer-devtron --type='json' -p='[{"op": "add", "path": "/spec/reSync", "value": true }]' ``` --- ### Setup Upgrade Devtron Upgrade 0.3.X 0.3.X (`docs/setup/upgrade/devtron-upgrade-0.3.x-0.3.x.md`) # Upgrading Devtron 0.3.x to 0.3.x If you want to check the current version of Devtron you are using, please use the following command. ``` kubectl -n devtroncd get installers installer-devtron -o jsonpath='{.status.sync.data}' | grep "^LTAG=" | cut -d"=" -f2- ``` ## Follow the below mentioned steps to upgrade the Devtron version using Helm 1. Fetch the latest Devtron helm chart ```bash helm repo update ``` 2. Input the target Devtron version that you want to upgrade to. You can find the latest releases from Devtron on Github https://github.com/devtron-labs/devtron/releases ```bash DEVTRON_TARGET_VERSION=v0.3.x ``` 3. Upgrade Devtron ```bash helm upgrade devtron devtron/devtron-operator --namespace devtroncd --set installer.release=$DEVTRON_TARGET_VERSION ``` ## Follow the below mentioned steps to upgrade the Devtron version using Kubectl 1. Input the target Devtron version that you want to upgrade to. You can find the latest releases from Devtron on Github https://github.com/devtron-labs/devtron/releases ```bash DEVTRON_TARGET_VERSION=v0.3.x ``` 2. Patch Devtron Installer ```bash kubectl patch -n devtroncd installer installer-devtron --type='json' -p='[{"op": "add", "path": "/spec/reSync", "value": true },{"op": "replace", "path": "/spec/url", "value": "https://raw.githubusercontent.com/devtron-labs/devtron/'$DEVTRON_TARGET_VERSION'/manifests/installation-script"}]' ``` --- ### Setup Upgrade Devtron Upgrade 0.3.X 0.4.X (`docs/setup/upgrade/devtron-upgrade-0.3.x-0.4.x.md`) # Upgrading Devtron 0.3.x to 0.4.x If you want to check the current version of Devtron you are using, please use the following command. ``` kubectl -n devtroncd get installers installer-devtron -o jsonpath='{.status.sync.data}' | grep "^LTAG=" | cut -d"=" -f2- ``` ## Follow the below mentioned steps to upgrade the Devtron version using Helm ### 1. Check the devtron release name ```bash helm list --namespace devtroncd ``` ### 2. Set release name in the variable ```bash RELEASE_NAME=devtron ``` ### 3. Annotate and Label all the Devtron resources ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### 4. Fetch the latest Devtron helm chart ```bash helm repo update ``` ### 5. Upgrade Devtron 5.1 Upgrade Devtron to latest version ```bash helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ -f https://raw.githubusercontent.com/devtron-labs/devtron/main/charts/devtron/devtron-bom.yaml \ --set installer.modules={cicd} --reuse-values ``` OR 5.2 Upgrade Devtron to a custom version. You can find the latest releases from Devtron on Github https://github.com/devtron-labs/devtron/releases ```bash DEVTRON_TARGET_VERSION=v0.4.x helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ -f https://raw.githubusercontent.com/devtron-labs/devtron/$DEVTRON_TARGET_VERSION/charts/devtron/devtron-bom.yaml \ --set installer.modules={cicd} --reuse-values ``` --- ### Setup Upgrade Devtron Upgrade 0.4.X 0.4.X (`docs/setup/upgrade/devtron-upgrade-0.4.x-0.4.x.md`) # Upgrading Devtron 0.4.x to 0.4.x If you want to check the current version of Devtron you are using, please use the following command. ``` kubectl -n devtroncd get installers installer-devtron -o jsonpath='{.status.sync.data}' | grep "^LTAG=" | cut -d"=" -f2- ``` ## Follow the below mentioned steps to upgrade the Devtron version using Helm ### 1. Check the devtron release name ```bash helm list --namespace devtroncd ``` ### 2. Set release name in the variable ```bash RELEASE_NAME=devtron ``` ### 3. Fetch the latest Devtron helm chart ```bash helm repo update ``` ### 4. Upgrade Devtron 4.1 Upgrade Devtron to latest version ```bash helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ -f https://raw.githubusercontent.com/devtron-labs/devtron/main/charts/devtron/devtron-bom.yaml \ --set installer.modules={cicd} --reuse-values ``` OR 4.2 Upgrade Devtron to a custom version. You can find the latest releases from Devtron on Github https://github.com/devtron-labs/devtron/releases ```bash DEVTRON_TARGET_VERSION=v0.4.x helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ -f https://raw.githubusercontent.com/devtron-labs/devtron/$DEVTRON_TARGET_VERSION/charts/devtron/devtron-bom.yaml \ --set installer.modules={cicd} --reuse-values ``` --- ### Setup Upgrade Devtron Upgrade 0.4.X 0.5.X (`docs/setup/upgrade/devtron-upgrade-0.4.x-0.5.x.md`) # Upgrading Devtron 0.4.x to 0.5.x If you want to check the current version of Devtron you are using, please use the following command. ``` kubectl -n devtroncd get installers installer-devtron -o jsonpath='{.status.sync.data}' | grep "^LTAG=" | cut -d"=" -f2- ``` ## Follow the below mentioned steps to upgrade the Devtron version using Helm ### 1. Apply Prerequisites Patch Job If you are using rawYaml in deployment template, this update can introduce breaking changes. We recommend you to update the `Chart Version` of your app to `v4.13.0` to make rawYaml section compatible to new argocd version `v2.4.0`. Or We have released a argocd-v2.4.0 patch job to fix the compatibilities issues. Please apply this job in your cluster and wait for completion and then only upgrade to `Devtron v0.5.x`. ```bash kubectl apply -f https://raw.githubusercontent.com/devtron-labs/utilities/main/scripts/jobs/argocd-2.4.0-prerequisites-patch-job.yaml ``` ### 2. Check the devtron release name ```bash helm list --namespace devtroncd ``` ### 3. Set release name in the variable ```bash RELEASE_NAME=devtron ``` ### 4. Fetch the latest Devtron helm chart ```bash helm repo update ``` ### 5. Upgrade Devtron **`5.1` Upgrade Devtron to latest version** ```bash helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ -f https://raw.githubusercontent.com/devtron-labs/devtron/main/charts/devtron/devtron-bom.yaml \ --set installer.modules={cicd} --reuse-values ``` OR **`5.2` Upgrade Devtron to a custom version** You can find the latest releases from Devtron on Github https://github.com/devtron-labs/devtron/releases ```bash DEVTRON_TARGET_VERSION=v0.5.x helm upgrade devtron devtron/devtron-operator --namespace devtroncd \ -f https://raw.githubusercontent.com/devtron-labs/devtron/$DEVTRON_TARGET_VERSION/charts/devtron/devtron-bom.yaml \ --set installer.modules={cicd} --reuse-values ``` --- ### Setup Upgrade Devtron Upgrade 0.5.X 0.6.X (`docs/setup/upgrade/devtron-upgrade-0.5.x-0.6.x.md`) # Upgrading Devtron 0.5.x to 0.6.x If you want to check the current version of Devtron you are using, please use the following command. ``` kubectl -n devtroncd get installers installer-devtron -o jsonpath='{.status.sync.data}' | grep "^LTAG=" | cut -d"=" -f2- ``` ## Follow the below mentioned steps to upgrade the Devtron version using Helm ### 1. Check the devtron release name ```bash helm list --namespace devtroncd ``` ### 2. Set release name in the variable ```bash export RELEASE_NAME=devtron ``` ### 3. Run the following script to upgrade ```bash wget https://raw.githubusercontent.com/devtron-labs/utilities/main/scripts/shell/upgrade-devtron-v6.sh ``` ```bash sh upgrade-devtron-v6.sh ``` Please ignore any errors you encounter while running the upgrade script --- ### Setup Upgrade Devtron Upgrade 0.6.X 0.7.X (`docs/setup/upgrade/devtron-upgrade-0.6.x-0.7.x.md`) # Upgrading Devtron 0.6.x to 0.7.x To check the current version of your Devtron setup, use the following command ```bash kubectl -n devtroncd get installers installer-devtron -o jsonpath='{.status.sync.data}' | grep "^LTAG=" | cut -d"=" -f2- ``` Proceed with the following steps only if the version is `0.6.x` --- ## Prerequisites 1. Set the release name ```bash export RELEASE_NAME=devtron ``` 2. Label and annotate the service accounts in the `devtron-ci` namespace ```bash kubectl -n devtron-ci label sa --all "app.kubernetes.io/managed-by=Helm" --overwrite kubectl -n devtron-ci annotate sa --all "meta.helm.sh/release-name=$RELEASE_NAME" "meta.helm.sh/release-namespace=devtroncd" --overwrite ``` 3. Now, label and annotate the service accounts in the `devtron-cd` namespace ``` kubectl -n devtron-cd label sa --all "app.kubernetes.io/managed-by=Helm" --overwrite kubectl -n devtron-cd annotate sa --all "meta.helm.sh/release-name=$RELEASE_NAME" "meta.helm.sh/release-namespace=devtroncd" --overwrite ``` --- ## Upgrade Commands 1. Update the Helm repository ```bash helm repo update ``` 2. Run the upgrade command for Devtron ```bash helm upgrade devtron devtron/devtron-operator -n devtroncd --reuse-values -f https://raw.githubusercontent.com/devtron-labs/devtron/main/charts/devtron/devtron-bom.yaml ``` --- ## Expected Command Output --- ### Setup Upgrade Devtron Upgrade To Beta (`docs/setup/upgrade/devtron-upgrade-to-beta.md`) # Upgrading existing devtron to beta If you want to check the current version of Devtron you are using, please use the following command. ``` kubectl -n devtroncd get installers installer-devtron -o jsonpath='{.status.sync.data}' | grep "^LTAG=" | cut -d"=" -f2- ``` ### To upgrade your existing devtron installation to beta, use helm upgrade. ```bash $ git clone [https://github.com/devtron-labs/devtron.git](https://github.com/devtron-labs/devtron.git) $ cd devtron/charts/devtron $ helm dependency up $ #modify values in values.yaml $ helm upgrade devtron . --reuse-values --namespace devtroncd \ -f devtron-bom.yaml ``` > Note: There is no option to upgrade to beta on stack manager UI as of now and you may always see upgrade available for latest stable version using which you'll be moved to latest stable version available. --- ### Setup Upgrade Upgrade Devtron Ui (`docs/setup/upgrade/upgrade-devtron-ui.md`) # Update Devtron from Devtron UI Devtron can be updated from the **Devtron Stack Manager > About Devtron** section. * Select **Update to Devtron** The update process may show one of the following statuses, with details available for tracking, troubleshooting, and additional information: | Installation status | Description | | --- | --- | | Initializing | The update is being initialized. | | Updating | Devtron is being updated to the latest version. | | Failed | Update failed. You may retry the upgrade or [contact support](https://discord.devtron.ai/). | | Unknown | Status is unknown at the moment and will be updated shortly. | | Request timed out | The request to install has hit the maximum number of retries. You may retry the installation or [contact support](https://discord.devtron.ai/) for further assistance. | > Updating Devtron also updates the installed integrations. --- ### User Guide Deploy Sample App Nodejs App (`docs/user-guide/Deploy-sample-app/nodejs_app.md`) # Let's deploy a sample App Hurray! Your Devtron stack is completely setup. Let's get started by deploying a simple application on it. {% embed url="https://www.youtube.com/watch?v=9u-pKiWV-tM&t=2s" caption="Deploy a Kubernetes Node.js micro-service using Devtron" %} ## Find out the steps here This is a sample Nodejs application which we are going to deploy using Devtron. For a detailed step-wise procedure, please have a look at the link below - [Getting Started with Deploying application through devtron](https://github.com/devtron-labs/getting-started-nodejs#getting-started-with-deploying-application-through-devtron) --- ### User Guide App Details Ephemeral Containers (`docs/user-guide/app-details/ephemeral-containers.md`) # Using Ephemeral Containers in Devtron ## Introduction Ephemeral container is a special type of container that runs temporarily in an existing Pod to accomplish user-initiated actions such as troubleshooting. It is especially useful when `kubectl exec` is insufficient because a container has crashed or a container image doesn't include debugging utilities. For instance, ephemeral containers help you execute a `curl` request from within pods that typically lack this utility. {% hint style="info" %} Ephemeral containers are turned on by default in Kubernetes v1.23 and later {% endhint %}
## How to Launch an Ephemeral Container Wherever you can access pod resources in Devtron, you can launch an ephemeral container as shown below. ### From Devtron (App Details) {% embed url="https://www.youtube.com/watch?v=TnaHRugYvSI" caption="Launching Ephemeral Container from App Details" %} 1. In the left sidebar, go to **Applications**. 2. Search and click your application from the list of Devtron Apps. 3. Go to the **App Details** tab. 4. Under the **K8 Resources** tab, select **Pod** inside `Workloads`. 5. Locate the pod you wish to debug. Hover and choose click **Terminal**. 6. Click **Launch Ephemeral Container** as shown below. 7. You get 2 tabs: 1. **Basic** - It provides the bare minimum configurations required to launch an ephemeral container. It contains 3 mandatory fields: * **Container name prefix** - Type a prefix to give to your ephemeral container, for e.g., *debug*. Your container name would look like `debug-jndvs`. * **Image** - Choose an image to run from the dropdown. Ephemeral containers need an image to run and provide the capability to debug, such as `curl`. You can use a custom image too. * **Target Container name** - Since a pod can have one or more containers, choose a target container you wish to debug, from the dropdown. 2. **Advanced** - It is particularly useful for advanced users that wish to use labels or annotations since it provides additional key-value options. Refer [Ephemeral Container Spec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#ephemeralcontainer-v1-core) to view the supported options. {% hint style="info" %} Devtron ignores the `command` field while launching an ephemeral container {% endhint %} 8. Click **Launch Container**. ### From Devtron (Resource Browser) Click [here](../resource-browser.md#launching-ephemeral-container) to know more. ### From Devtron's Cluster Terminal (*This is not a recommended method. This option is available only if you are an admin.*) {% embed url="https://www.youtube.com/watch?v=PzB6dFRYe38" caption="Externally Created Ephemeral Container" %} You can launch an ephemeral container from Kubernetes CLI. For this, you need access to the cluster terminal on Devtron.
## Removing an Ephemeral Container {% embed url="https://www.youtube.com/watch?v=tZID0YU0YUU" caption="Deleting Ephemeral Containers" %} You can remove an ephemeral container using either **App Details** or **Resource Browser** (from the same screen you used to create the ephemeral container). {% hint style="info" %} You cannot use **App Details** or **Resource Browser** to remove an ephemeral container created using Kubernetes CLI {% endhint %} --- ### User Guide App Details Terminal (`docs/user-guide/app-details/terminal.md`) # Terminal A pod can have one or more containers running, and a container can have no or multiple shells running in it. If you are not able to create a successful connection, try changing the shell, as the container may not have that shell running. ### Connection Status - Connected: connection has established successfully - Connecting: trying to establish new connection - Disconnecting: trying to terminate current connection - Disconnected: connection has terminated --- ### User Guide Creating Application App Details (`docs/user-guide/creating-application/app-details.md`) # Application Details ## Access an External Link The users can access the [configured external links](../../user-guide/global-configurations/external-links.md) on the **App Details** page. 1. Select **Applications** from the left navigation pane. 2. After selecting a configured application, select the **App Details** tab. > **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. As shown in the screenshot, the external links appear on the `App-Details` level: 3. You can hover around an external link (e.g. Grafana) to view the description. The link opens in a new tab with the context you specified as env variables in the [Add an external link](./global-configurations/../../global-configurations/external-links.md) section. ## Manage External Links On the `App Configuration` page, select `External Links` from the navigation pane. You can see the configured external links which can be searched, edited or deleted. You can also `Add Link` to add a new external link. ## Ingress Host URL You can view the Ingress Host URL and the Load Balancer URL on the **URLs** section on the **App Details**. You can also copy the Ingress Host URL from the **URLs** instead of searching in the `Manifest`. 1. Select **Applications** from the left navigation pane. 2. After selecting your configured application, select the **App Details**. 3. Click **URLs**. 4. You can view or copy the **URL** of the Ingress Host. **Note**: * The Ingress Host URL will point to the load balancer of your application. * You can also view the `Service` name with the load balancer detail. --- ### User Guide Creating Application App Metrics (`docs/user-guide/creating-application/app-metrics.md`) # Application Metrics Application metrics can be enabled to see your application's metrics. ## Standard Metrics Devtron provides certain metrics (CPU and Memory utilization) for each application by default i.e. you do not need to enable “Application metrics”. However, prometheus needs to be present in the cluster and the endpoint of the same should be updated in Global Configurations --> Clusters & Environments section. ## Advanced Metrics There are certain advanced metrics (like Latency, Throughput, 4xx, 5xx, 2xx) which are only available when "Application metrics" is enabled from the Deployment Template. When you enable these advanced metrics, devtron attaches a envoy sidecar container to your main container which runs as a transparent proxy and passes each request through it to measure the advanced metrics. **Note: Since, all the requests are passed through envoy, any misconfiguration in envoy configs can bring your application down, so please test the configurations in a non-production environment extensively.** ```yaml envoyproxy: image: envoyproxy/envoy:v1.14.1 configMapName: "" resources: limits: cpu: "50m" memory: "50Mi" requests: cpu: "50m" memory: "50Mi" ``` ## CPU Usage Metrics CPU usage is a utilization metric that shows the overall utilization of cpu by an application. It is available as both, aggregated or per pod. ## Memory Usage Metrics Memory usage is a utilization metric that shows the overall utilization of memory by an application. It is available as both, aggregated or per pod. ## Throughput Metrics This application metrics indicates the number of request processed by an application per minute. ## Status Code Metrics This metrics indicates the application’s response to client’s request with a specific status code i.e 1xx(Communicate transfer protocol-level information), 2xx(Client’s request was accepted successfully), 3xx(Client must take some additional action to complete their request), 4xx(Client side error) or 5xx(Server side error). ## Latency Metrics Latency metrics shows the latency for an application. Latency measures the delay between an action and a response. **99.9th percentile latency**: The maximum latency, in seconds, for the fastest 99.9% of requests. **99th percentile latency**: The maximum latency, in seconds, for the fastest 99% of requests. **95th percentile latency**: The maximum latency, in seconds, for the fastest 95% of requests. **Note:** We also support custom percentile input inside the dropdown .A latency measurement based on a single request is not meaningful. ## Checklist for enabling Advanced Application metrics in Production * [ ] Have adjusted resources to the envoy sidecar container, by default Devtron allocates 50m CPU and 50Mi Memory as both limits as well as requests. This should be enough for handling traffic upto 3000rpm per pod, if each replica of your pod is expected to handle more than 3000rpm, please adjust the resources accordingly. * [ ] If you are not leveraging http2 / streaming protocols, make sure to set supportStreaming and useHTTP2 in ContainerPort as false. * [ ] Use envoy image as "quay.io/devtron/envoy:v1.14.1" instead of default "envoyproxy/envoy:v1.14.1" if your cluster occasionally hit dockerhub pull rate limit or if you are running too many replicas/micro-services in a cluster. * [ ] Enabled and tested extensively in non-production environment including load testing till highest rpm capacity per pod. --- ### User Guide Creating Application Config Approval (`docs/user-guide/creating-application/config-approval.md`) # Protect Configuration ## Introduction Since resources are created according to the configurations you enter, it's essential to restrict such configurations from direct modifications. For critical environments like production, it becomes necessary to introduce an approval flow for any edits made to the configuration files. In Devtron, these configurations are present in the **App Configuration** tab of your application. Any changes made to the following configurations will require approval if enabled: - Deployment Template - ConfigMaps - Secrets This stands true for both: base configuration and respective environment-level configuration. --- ## Tutorial {% embed url="https://www.youtube.com/watch?v=TVLEbY850hI" caption="Protect Configuration and Approval" %} --- ## Changing the Configuration Values {% hint style="info" %} Only a super-admin, manager, and admin can edit the configuration values. {% endhint %} Let's assume you are the application admin and you wish to edit the deployment template of your environment (as an override). 1. Go to the `App Configuration` tab. 2. In Environment Overrides → (choose your environment) → Deployment Template 3. You can change the value of a key to a desired value as shown below. Once done, click the **Save Changes…** button. {% hint style="info" %} If you are not a super-admin, you cannot modify the locked keys in deployment template. Refer [Lock Deployment Configuration](../global-configurations/lock-deployment-config.md) to know more. {% endhint %} 4. If the configuration is protected, your changes won't be published right away. You can do either of the following: * **Save as draft** : Selecting this option will save your file as a draft. You and other users can view and edit the saved draft and propose it further for approval. * **Save & Propose Changes** : Selecting this option will propose your changes to a configuration approver for a review. Since we are proposing the changes immediately, click **Propose Changes**. 5. You can also view the approver(s) if you wish. {% hint style="info" %} The one who performs the edits cannot approve their own changes. A different user has to review and approve. {% endhint %} Only one draft can exist at time and you cannot create multiple drafts. In the top-right corner, you have the option to discard the draft if you don't wish to proceed with the edits you made. --- ## Approving the Configuration {% hint style="info" %} Only a different super-admin user or someone (who is not amongst the editors of the draft), having `Configuration approver` access, can approve the changes made to the configuration files. {% endhint %} Go to the edited configuration file to review and approve the changes as shown below. A super-admin can check whether a user has approval rights by going to **Global Configurations** → **Authorization** (dropdown) → **User Permissions**. --- ## Deploying with New Configuration Values Once the approver validates and approves your configuration changes, you can proceed to deploy your application with the updated configuration. 1. Go to the **Build & Deploy** tab of your application. 2. Click **Select Image** in the deployment flow. 3. You can view an indicator at the bottom `Config Diff from Last Deployed`. Click **Review** to view the changes. {% hint style="info" %} If the new configuration is not yet approved, the changes made to the config would not be visible during deployment, it would show `No Config Diff from Last Deployed` at the bottom. In that case, check whether your changes are present in the live config or not. If your changes are absent, chances are your draft is either pending for approval or rejected (discarded). {% endhint %} 4. Once you have verified the changes, you can click **Deploy**. {% hint style="info" %} If you don't wish to deploy with the new changes, you can choose `Last deployed config` from the available drop-down. {% endhint %} --- ## Enabling/Disabling Config Protection {% hint style="info" %} Only a super-admin can enable or disable the config protection. {% endhint %} 1. Go to the `App Configuration` tab. 2. Click `Protect Configuration`. 3. Use the toggle button to enable the protection for the configuration of your choice (base/environment level). A protection badge would appear next to the chosen configuration. Alternatively, unprotecting the configuration will lead to the discarding of unapproved drafts (if any). --- ### User Guide Creating Application Config Maps (`docs/user-guide/creating-application/config-maps.md`) # Config Maps The ConfigMap API resource holds key-value pairs of the configuration data that can be consumed by pods or used to store configuration data for system components such as controllers. ConfigMap is similar to Secrets, but designed to more conveniently support working with strings that do not contain sensitive information. Click on `Add ConfigMap` to add a config map to your application. ## Configure the ConfigMap You can configure a configmap in two ways- \(a\) Using data type **Kubernetes ConfigMap** \(b\) Using data type **Kubernetes External ConfigMap** | Key | Description | | :--- | :--- | | `Data Type (Kubernetes ConfigMap)` | Select your preferred data type for Kubernetes ConfigMap or Kubernetes External ConfigMap | | `Name` | Provide a name to this ConfigMap. | | `Use configmap as Environment Variable` | Select this option if you want to inject Environment Variables in pods using ConfigMap. | | `Use configmap as Data Volume` | Select this option, if you want to configure a Data Volume that is accessible to Containers running in a pod and provide a Volume mount path. | | `Key-Value` | Provide the actual key-value configuration data here. Key and corresponding value to the provided key. | ### \(A\) Using Kubernetes ConfigMap **1. Data Type** Select the Data Type as `Kubernetes ConfigMap`, if you wish to use the ConfigMap created by Devtron. **2. Name** Provide a name to your configmap. **3. Use ConfigMap as** Here we are providing two options, one can select any of them as per your requirement -`Environment Variable` as part of your configMap or you want to add `Data Volume` to your container using Config Map. * Environment Variable Select this option if you want to add Environment Variables as a part of configMap. You can provide Environment Variables in key-value pairs, which can be seen and accessed inside a pod. * Data Volume Select this option if you want to add a `Data Volume` to your container using the Config Map. Key-value pairs that you provide here, are provided as a file to the mount path. Your application will read this file and collect the required data as configured. **4. Data** In the `Data` section, you provide your configmap in key-value pairs. You can provide one or more than one environment variable. You can provide variables in two ways- * YAML \(raw data\) * GUI \(more user friendly\) Once you have provided the config, You can click on any option-`YAML` or `GUI` to view the key and Value parameters of the ConfigMap. **Kubernetes ConfigMap using Environment Variable:** If you select `Environment Variable` in 3rd option, then you can provide your environment variables in key-value pairs in the `Data` section using `YAML` or `GUI`. `Data in YAML` \(please Check below screenshot\) Now, Click on `Save ConfigMap` to save your configmap configuration. **Kubernetes ConfigMap using Data Volume** ## Volume Mount Path Provide the Volume Mount folder path in Volume Mount Path, a path where the data volume needs to be mounted, which will be accessible to the Containers running in a pod. You can add Configuration data as in YAML or GUI format as explained above. You can click on `YAML` or `GUI` to view the key and Value parameters of the ConfigMap that you have created. You can click on `Save ConfigMap` to save the configMap. ## Sub Path For multiple files mount at the same location you need to check sub path bool field, it will use the file name (key) as sub path. Sub Path feature is not applicable in case of external configmap. ## File Permission File permission will be provide at the configmap level not on the each key of the configmap. It will take 3 digit standard permission for the file. ### \(B\) Kubernetes External ConfigMap You can select `Kubernetes External ConfigMap` in the `data type` field if you have created a ConfigMap using the kubectl command. By default, the data type is set to `Kubernetes ConfigMap`. Kubernetes External ConfigMap is created using the `kubectl create configmap` command. If you are using `Kubernetes External ConfigMap`, make sure you give the name of ConfigMap the same as the name that you have given using kubectl create `Configmap ` command, otherwise, it might result in an error during the built. You have to ensure that the External ConfigMap exists and is available to the pod. The config map is created. ## Update ConfigMap You can update your configmap anytime later but you cannot change the name of your configmap. If you want to change the name of the configmap then you have to create a new configmap. To update configmap, click on the configmap you have created make changes as required. Click on `Update Configmap` to update your configmap. ## Delete ConfigMap You can delete your configmap. Click on your configmap and click on the `delete sign` to delete your configmap. --- ### User Guide Creating Application Container Registry Override (`docs/user-guide/creating-application/container-registry-override.md`) # Override Build Configuration Within the same application, you can override a `container registry`, `container image` and `target platform` during the build pipeline, which means the images built for non-production environment can be included to the non-production registry and the images for production environment can be included to the production registry. To override a container registry, container image or target platform: * Go to **Applications** and select your application from the **Devtron Apps** tabs. * On the **App Configuration** tab, select **Workflow Editor**. * Open the build pipeline of your application. * Click **Allow Override** to: * Select the new container registry from the drop-down list. * Or, [create and build the new container image](../creating-application/docker-build-configuration.md#build-the-container-image) with different options. * Or, set a [new target platform](../creating-application/docker-build-configuration.md#set-target-platform-for-the-build) from the drop-down list or enter a new target platform. * Click **Update Pipeline**. The overridden container registry/container image location/target platform will be reflected on the [Build Configuration](docker-build-configuration.md) page. You can also see the number of build pipelines for which the container registry/container image location/target platform is overridden. --- ### User Guide Creating Application Deployment Template (`docs/user-guide/creating-application/deployment-template.md`) # Base Deployment Template A deployment configuration is a manifest of the application. It defines the runtime behavior of the application. You can select one of the default deployment charts or custom deployment charts which are created by super admin. To configure a deployment chart for your application, do the following steps: * Go to **Applications** and create a new application. * Go to **App Configuration** page and configure your application. * On the **Base Deployment Template** page, select the drop-down under **Chart type**. --- ## Selecting a Chart Type {% hint style="warning" %} ### Who Can Perform This Action? Users need to have [Admin role](../user-guide/global-configurations/authorization/user-access.md#role-based-access-levels) or above to select a chart. {% endhint %} {% hint style="warning" %} ### Note After you select and save a chart type for a given application, you won't be able to change it later. Make sure to choose the correct chart type before saving. You can select a chart from [Devtron Charts](#from-devtron-charts) or other [Deployment Charts](#from-deployment-charts). {% endhint %} ### From Devtron Charts You can select a default deployment chart from the following options: 1. [Deployment](deployment-template/deployment.md) (Recommended) 2. [Rollout Deployment](deployment-template/rollout-deployment.md) 3. [Job & CronJob](deployment-template/job-and-cronjob.md) 4. [StatefulSet](deployment-template/statefulset.md) ### From Deployment Charts {% hint style="warning" %} This option will be available only if a custom chart exists. If it doesn't, a user with `super admin` permission may upload one in [Global Configurations → Deployment Charts](../global-configurations/deployment-charts.md). {% endhint %} You can select an available custom chart as shown below. You can also view the description of the custom charts in the list. --- ## Selecting a Chart Version {% hint style="warning" %} ### Who Can Perform This Action? Users need to have [Admin role](../user-guide/global-configurations/authorization/user-access.md#role-based-access-levels) or above to select a chart version. {% endhint %} Once you select a chart type, choose a chart version using which you wish to deploy the application. Devtron uses helm charts for deployments and it maintains multiple chart versions based on the features it supports. One can see available chart versions in the drop-down. You can select any chart version as per your requirements. By default, the latest version of the helm chart is selected. Every chart version has its own YAML file that provides specifications for your application. To make it easy to use, we have created templates for the YAML file and have added some variables inside the YAML. You can provide or change the values of these variables as per your requirement. --- ## Configuring the Chart {% hint style="warning" %} ### Who Can Perform This Action? Users need to have [Admin role](../user-guide/global-configurations/authorization/user-access.md#role-based-access-levels) or above to configure a chart. However, super-admins can lock keys in base deployment template to prevent non-super-admins from modifying them. Refer [Lock Deployment Configuration](../global-configurations/lock-deployment-config.md) to know more. {% endhint %} ### Using Basic GUI If you are not an advanced user, you may use the **Basic (GUI)** section to configure your chosen chart. By default, the following fields are available for you to modify in the **Basic (GUI)** section: | Fields | Description | | :--- | :--- | | **Arguments** | Enable the `Arguments` to pass one or more argument values. By default, it is in the `disabled` state. | | **Command** | Enable the `Command` to pass one or more command values. By default, it is in the `disabled` state. | | **HTTP Request Routes** | Enable the `HTTP Request Routes` to define `Host`, and `Path`. By default, it is in the `disabled` state.
  • **Host**: Domain name of the server.
  • **Path**: Path of the specific component in the host that the HTTP wants to access.
You can define multiple paths as required by clicking **Add path**.| | **Resources** | Here, you can tweak the requests and limits of the CPU resource and RAM resource as per the application. | | **Autoscaling** | Define the autoscaling parameters to automatically scale your application's deployment based on resource utilization.
  • **Maximum Replicas**: The maximum number of replicas your application can scale up to.
  • **Minimum Replicas**: The minimum number of replicas your application should run at any time.
  • **Target CPU Utilization Percentage**: The average CPU utilization across all pods that will trigger scaling.
  • **Target Memory Utilization Percentage**: The average memory utilization across all pods that will trigger scaling.
| | **Environment Variables** (**Key/Value**) | Define `key/value` by clicking **Add variable**.
  • **Key**: Define the key of the environment.
  • **Value**: Define the value of the environment.
You can define multiple env variables by clicking **Add EnvironmentVariables**. | | **Container Port** | The internal port on which the container listens for HTTP requests. Specify the container port and optionally the service port that maps to it. | | **Service** | Configure the service that exposes your application to the network.
  • **Type**: Specify the type of service (e.g., ClusterIP, NodePort, LoadBalancer).
  • **Annotations**: Add custom annotations to the service for additional configuration.
| | **Readiness Probe** | Define the readiness probe to determine when a container is ready to start accepting traffic.
  • **Path**: The HTTP path that the readiness probe will access.
  • **Port**: The port on which the readiness probe will access the application.
| | **Liveness Probe** | Define the liveness probe to check if the container is still running and to restart it if it is not.
  • **Path**: The HTTP path that the liveness probe will access.
  • **Port**: The port on which the liveness probe will access the application.
| | **Tolerations** | Define tolerations to allow the pods to be scheduled on nodes with matching taints.
  • **Key**: The key of the taint to tolerate.
  • **Operator**: The relationship between the key and the value (e.g., Exists, Equal).
  • **Value**: The value of the taint to match.
  • **Effect**: The effect of the taint to tolerate (e.g., NoSchedule, NoExecute).
| | **ServiceAccount** | Specify the service account for the deployment to use, allowing it to access Kubernetes API resources.
  • **Create**: Toggle to create a new service account.
  • **Name**: The name of the service account to use.
| Click **Save Changes**. If you want to do additional configurations, then click the **Switch to Advanced** button or **Advanced (YAML)** button for modifications. {% hint style="warning" %} ### Note * If you change any values in the 'Basic (GUI)', then the corresponding values will change in 'Advanced (YAML)' too. * Users who are not super-admins will land on 'Basic (GUI)' section when they visit **Base Deployment Template** page; whereas super-admins will land on 'Advanced (YAML)' section. This is just a default behavior; therefore, they can still navigate to the other section if needed. {% endhint %} #### Customize Basic GUI [](https://devtron.ai/pricing) {% hint style="warning" %} ### Who Can Perform This Action? Superadmin can define and apply custom deployment schema. {% endhint %} By default, the `Basic (GUI)` section comes with multiple predefined fields as seen earlier [in the table](#2-basic-configuration). However, if you wish to display a different set of fields to your team, you can modify the whole section as per your requirement. This is useful in scenarios where: * Your team members find it difficult to understand and edit the [Advanced (YAML)](#3-advanced-yaml) section. * You frequently edit certain fields in Advanced (YAML), which you expect to remain easily accessible in Basic (GUI) section. * You don't require some fields in Basic (GUI) section. * You need the autonomy to keep the Basic (GUI) unique for applications/clusters/environments/charts, or display the same Basic (GUI) everywhere. {% hint style="info" %} There are two ways you can customize the Basic GUI, use any one of the following: 1. From [Deployment Charts](../global-configurations/deployment-charts.md#editing-gui-schema-of-deployment-charts) section 2. Using APIs (explained below) {% endhint %} {% embed url="https://www.youtube.com/watch?v=09VP1I-WvUs" caption="JSON-driven Deployment Schema" %} You can pass a custom JSON (deployment schema) of your choice through the following API. You may need to run the API with the `POST` method if you are doing it for the first time. ``` PUT {{DEVTRON_BASEURL}}/orchestrator/deployment/template/schema ``` {% code title="Sample API Request Body" overflow="wrap" lineNumbers="true" %} ``` /* Detailed source-code truncated for AI context efficiency. */ ``` {% endcode %} 1. In the `name` field, give a name to your schema, e.g., *schema-1* 2. Enter the `type` as JSON. 3. The `schema` field is for entering your custom deployment schema. Perform the following steps: * To create a custom schema of your choice, you may use [RJSF JSON Schema Tool](https://rjsf-team.github.io/react-jsonschema-form/). * Copy the final JSON and stringify it using any free online tool. * Paste the stringified JSON in the `schema` field of the API request body. * Send the API request. If your schema already exists, use the `PUT` method instead of `POST` in the API call. 4. The `attributeSelector` object helps you choose the scope at which your custom deployment schema will take effect. | Priority | Category Scope | Description | |----------|-----------------|----------------------------------------------------------------------------| | 1 (High) | APP_ENV | Specific to an application and its environment | | 2 | APP | Applies at the application level if no specific environment is defined | | 3 | ENV | Applies to specific deployment environment | | 4 | CHART_REF | Applies to all applications using a specific chart type and version | | 5 | CLUSTER | Applies across all applications and environments within a specific cluster | | 6 | GLOBAL | Universally applies if no other more specific schemas are defined | ### Using Advanced (YAML) If you are an advanced user wishing to perform additional configurations, you may switch to **Advanced (YAML)** for modifications. Refer the respective templates to view the YAML details. * [Deployment](deployment-template/deployment.md) * [Rollout Deployment](deployment-template/rollout-deployment.md) * [Job & CronJob](deployment-template/job-and-cronjob.md) * [StatefulSet](deployment-template/statefulset.md) --- ## Application Metrics Depending on the chart type and version you select, application metrics of your application may be viewed.
This includes: * Status codes 2xx, 3xx, 5xx * Throughput * Latency ...and many more Enable **Show application metrics** toggle to view the application metrics on the **App Details** page. > **IMPORTANT**: Enabling application metrics introduces a sidecar container to your main container which may require some additional configuration adjustments. We recommend you to do load test after enabling it in a non-production environment before enabling it in production environment. Select **Save & Next** to save your configurations. --- ### User Guide Creating Application Docker Build Configuration (`docs/user-guide/creating-application/docker-build-configuration.md`) # Build Configuration In this section, we will provide information on the `Build Configuration`. Build configuration is used to create and push docker images in the container registry of your application. You will provide all the docker related information to build and push docker images on the `Build Configuration` page. Only one docker image can be created for multi-git repository applications as explained in the [Git Repository](git-material.md) section. For **build configuration**, you must provide information in the sections as given below: * [Store Container Image](#store-container-image) * [Build the Container Image](#build-the-container-image) * [Advanced Options](#advanced-options) ## Store Container Image The following fields are provided on the **Store Container Image** section: | Field | Description | | --- | --- | | **Container Registry** | Select the container registry from the drop-down list or you can click **Add Container Registry**. This registry will be used to [store docker images](../global-configurations/container-registries.md). | | **Container Repository** | Enter the name of your container repository, preferably in the format `username/repo-name`. The repository that you specify here will store a collection of related docker images. Whenever an image is added here, it will be stored with a new tag version. | **If you are using docker hub account, you need to enter the repository name along with your username. For example - If my username is *kartik579* and repo name is *devtron-trial*, then enter kartik579/devtron-trial instead of only devtron-trial.** ## Build the Container Image In order to deploy the application, we must build the container images to configure a fully operational container environment. You can choose one of the following options to build your container image: * **I have a Dockerfile** * **Create Dockerfile** * **Build without Dockerfile** ### Build Docker Image when you have a Dockerfile A `Dockerfile` is a text document that contains all the commands which you can call on the command line to build an image. | Field | Description | | --- | --- | | **Select repository containing Dockerfile** | Select the Git checkout path of your repository. This repository is the same which you defined on the [Git Repository](../creating-application/git-material.md) section. | | **Dockerfile Path (Relative)** | Enter a relative file path where your docker file is located in Git repository. Ensure that the dockerfile is available on this path. This is a mandatory field. | ### Build Docker Image by creating Dockerfile With the option **Create Dockerfile**, you can create a `Dockerfile` from the available templates. You can edit any selected Dockerfile template as per your build configuration requirements. | Field | Description | | --- | --- | | **Language** | Select the programming language (e.g., `Java`, `Go`, `Python`, `Node` etc.) from the drop-down list you want to create a dockerfile as per compatibility to your system.
**Note** We will be adding other programming languages in the future releases.
| | **Framework** | Select the framework (e.g., `Maven`, `Gradle` etc.) of the selected programming language.
**Note** We will be adding other frameworks in the future releases.
| ### Build Docker Image without Dockerfile With the option **Build without Dockerfile**, you can use Buildpacks to automatically build the image for your preferred language and framework. | Field | Description | | --- | --- | | **Select repository containing code** | Select your code repository. This repository is the same which you defined on the [Git Repository](../creating-application/git-material.md) section.| | **Project Path (Relative)** | In case of monorepo, specify the path of the project from your Git repository.| | **Language** | Select the programming language (e.g., `Java`, `Go`, `Python`, `Node`, `Ruby`, `PHP` etc.) from the drop-down list you want to build your container image as per the compatibility to your system.
**Note**: We will be adding other programming languages in the future releases.
| | **Version** | Select a language version from the drop-down list. If you do not find the version you need, then you can update the language version in `Build Env Arguments`. You can also select **Autodetect** in case if you want `Builder` to detect version by itself or its default version.| | **Select a builder** | A builder is an image that contains a set of buildpacks which provide your app's dependencies, a stack, and the OS layer for your app image. Select a buildpack provider from the following options:
  • **Heroku**: It compiles your deployed code and creates a slug, which is a compressed and pre-packaged copy of your app and also the runtime which is optimized for distribution to the dyno (Linux containers) manager. [Learn more](https://devcenter.heroku.com/articles/buildpacks).
  • **GCR**: GCR builder is a general purpose builder that creates container images designed to run on most platforms (e.g. Kubernetes / Anthos, Knative / Cloud Run, Container OS, etc.). It auto-detects the language of your source code, and can also build functions compatible with the Google Cloud Function Framework. [Learn more](https://github.com/GoogleCloudPlatform/buildpacks).
  • **Paketo**: Paketo buildpacks provide production-ready buildpacks for the most popular languages and frameworks to easily build your apps. Based on your application needs, you can select from `Full`, `Base` and `Tiny`. [Learn more](https://paketo.io/docs/).
| #### Build Env Arguments You can add Key/Value pair by clicking **Add argument**. | Field | Description | | --- | --- | | **Key** | Define the key parameter as per your selected language and builder. E.g., By default `GOOGLE_RUNTIME_VERSION` for GCR buildpack.
**Note**: If you want to define `env arguments` for `PHP` and `Ruby` languages after selecting `Heroku` builder, please make sure to refer respective [Heroku Ruby Support](https://devcenter.heroku.com/articles/ruby-support) and [Heroku PHP Support](https://devcenter.heroku.com/articles/php-support) documentation for runtime information.
| | **Value** | Define the value for the specified key. E.g. Version no. | **Note** This fields are optional. If required, it can be overridden at [CI step](../deploying-application/triggering-ci.md). ## Advanced Options ### Set Target Platform for the build Using this option, you can build images for a specific or multiple **architectures and operating systems (target platforms)**. You can select the target platform from the drop-down list or can type to select a customized target platform. Before selecting a customized target platform, please ensure that the architecture and the operating system are supported by the `registry type` you are using, otherwise build will fail. Devtron uses BuildX to build images for multiple target Platforms, which requires higher CI worker resources. To allocate more resources, you can increase value of the following parameters in the `devtron-cm` configmap in `devtroncd` namespace. - LIMIT_CI_CPU - REQ_CI_CPU - REQ_CI_MEM - LIMIT_CI_MEM To edit the `devtron-cm` configmap in `devtroncd` namespace: ``` kubectl edit configmap devtron-cm -n devtroncd ``` If target platform is not set, Devtron will build image for architecture and operating system of the k8s node on which CI is running. The Target Platform feature might not work in minikube & microk8s clusters as of now. ### Docker Build Arguments It is is a collapsed view including the following parameters: * Key * Value These fields will contain the key parameter and the value for the specified key for your [docker build](https://docs.docker.com/engine/reference/commandline/build/#options). This field is Optional. If required, this can be overridden at [CI step](../deploying-application/triggering-ci.md). Click **Save Configuration**. --- ### User Guide Creating Application Environment Overrides (`docs/user-guide/creating-application/environment-overrides.md`) # Environment Overrides You will see all your environments associated with an application under the `Environment Overrides` section. You can customize your `Deployment template, ConfigMap, Secrets` in Environment Overrides section to add separate customizations for different environments such as dev, test, integration, prod, etc. --- ## Deployment template - Functionality If you want to deploy an application in a non-production environment and then in production environment, once testing is done in the non-production environment, then you do not need to create a new application for production environment. Your existing pipeline\(non-production env\) will work for both the environments with little customization in your deployment template under `Environment overrides`. ### Example customization: In a Non-production environment, you may have specified 100m CPU resources in the deployment template but in the Production environment, you may want to have 500m CPU resources as the traffic on Pods will be higher than traffic on non-production env. Configuring the Deployment template inside `Environment Overrides` for a specific environment will not affect the other environments because `Environment Overrides` will configure deployment templates on environment basis. And at the time of deployment, it will always pick the overridden deployment template if any. If there are no overrides specified for an environment in the `Environment Overrides` section, the deployment template will be the one you specified in the `deployment template section` of the app creation. *(Note: This example is meant only for a representational purpose. You can choose to add any customizations you want in your deployment templates in the `Environment Overrides` tab)* Any changes in the configuration will not be added to the template, instead, it will make a copy of the template and lets you customize it for each particular environment. And now this overridden template will be used only for the specified Environment. This will save you the trouble to manually create deployment files separately for each environment. Instead, all you have to do is to change the required variables in the deployment template. --- ## How to add Environment Overrides {% hint style="warning" %} ### Who Can Perform This Action? Users need to have [Admin role](../user-guide/global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the environment and applications) to change perform environment override. {% endhint %} Go to **App Configuration** → **Environment Overrides**. For each environment you can override the following configurations: * [Deployment Template](#deployment-template) * [ConfigMaps](#configmaps--secrets) * [Secrets](#configmaps--secrets) ### Deployment Template {% hint style="info" %} Users who are not super-admins will land on [Basic (GUI)](#basic-gui) section when they visit the **Deployment Template** page; whereas super-admins will land on [Advanced (YAML)](#advanced-yaml) section. This is just a default behavior, they can still navigate to the other section if needed. {% endhint %} #### Basic (GUI) If you have a [base deployment configuration](../creating-application/deployment-template/deployment.md#2.-basic-configuration) set up at application level, the environment(s) you define for your application will also inherit those values. However, you have the flexibility to use different values at the environment level by overriding the base configurations as shown below. Refer [basic configuration](../creating-application/deployment-template/deployment.md#2.-basic-configuration) to know more about each field within `Basic (GUI)` section. {% hint style="info" %} ### Want to customize the fields displayed on Basic (GUI)? [](https://devtron.ai/pricing) Refer [Customize Basic GUI](../creating-application/deployment-template.md#customize-basic-gui) to know the process of adding, removing, and customizing the Basic (GUI) section. {% endhint %} #### Advanced (YAML) Similarly, if you are an advanced user intending to tweak more values in deployment template, you may go to `Advanced (YAML)` section and edit them. [Click here](../creating-application/deployment-template/deployment.md#3-advanced-yaml) to know more about each key-value pair within the `Advanced (YAML)` section. {% hint style="warning" %} **Delete Override** will discard the current overrides and the base deployment configuration will be applicable again to the environment. {% endhint %} ### ConfigMaps & Secrets The same goes for `ConfigMap` and `Secrets`. You can also create an environment-specific configmap and Secrets inside the `Environment override` section. If you want to configure your ConfigMap and secrets at the application level then you can provide them in [ConfigMaps](config-maps.md) and [Secrets](secrets.md), but if you want to have environment-specific ConfigMap and secrets then provide them under the Environment override Section. At the time of deployment, it will pick both of them and provide them inside your cluster. To update a ConfigMap, follow the steps below: 1. In your environment, click **ConfigMaps**. 2. Click the ConfigMap you wish to update. 3. Click **Allow Override**. 4. Edit your ConfigMap. 5. Click **Save Changes**. Similarly, you can update Secrets too as shown below. --- ### User Guide Creating Application External Links (`docs/user-guide/creating-application/external-links.md`) # External Links This is similar to [External Links](../global-configurations/external-links.md) present under Global Configurations. The only difference is that in **App Configuration** → **External Links**, only the links editable by application admins and manager are displayed. You can also configure external links separately for your application. Whereas, in **Global Configurations** → **External Links**, you can configure the external links for all applications in a cluster or for specific applications. --- ### User Guide Creating Application Git Material (`docs/user-guide/creating-application/git-material.md`) # Git Repository ## Introduction During the [CI process](../deploying-application/triggering-ci.md), the application source code is pulled from your [git repository](../../reference/glossary.md#repo). Devtron also supports multiple Git repositories (be it from one Git account or multiple Git accounts) in a single deployment. Therefore, this doc is divided into 2 sections, read the one that caters to your application: * [Single Repo Application](#single-repo-application) * [Multi Repo Application](#multi-repo-application) --- ## Single Repo Application Follow the below steps if the source code of your application is hosted on a single Git repository. In your application, go to **App Configuration** → **Git Repository**. You will get the following fields and options: 1. [Git Account](#git-account) 2. [Git Repo URL](#git-repo-url) 3. (Checkboxes) * [Exclude specific file/folder in this repo](#exclude-specific-filefolder-in-this-repo) * [Set clone directory](#set-clone-directory) * [Pull submodules recursively](#pull-submodules-recursively) ### Git Account This is a dropdown that shows the list of Git accounts added to your organization on Devtron. If you haven't done already, we recommend you to first [add your Git account](../global-configurations/git-accounts.md) (especially when the repository is private). {% hint style="info" %} If the authentication type of your Git account is anonymous, only public Git repositories in that account will be accessible. Whereas, adding a user auth or SSH key will make both public and private repositories accessible. {% endhint %} ### Git Repo URL In this field, you have to provide your code repository’s URL, for e.g., `https://github.com/devtron-labs/django-repo`. You can find this URL by clicking on the **Code** button available on your repository page as shown below: {% hint style="info" %} * Copy the HTTPS/SSH portion of the URL too * Make sure you've added your [Dockerfile](https://docs.docker.com/engine/reference/builder/) in the repo {% endhint %} ### Exclude specific file/folder in this repo Not all repository changes are worth triggering a new [CI build](../deploying-application/triggering-ci.md). If you enable this checkbox, you can define the file(s) or folder(s) whose commits you wish to use in the CI build. In other words, if a given commit contains changes only in file(s) present in your exclusion rule, the commit won't show up while selecting the [Git material](../../reference/glossary.md#material), which means it will not be eligible for build. However, if a given commit contains changes in other files too (along with the excluded file), the commit won't be excluded and it will definitely show up in the list of commits. Devtron allows you to create either an exclusion rule, an inclusion rule, or a combination of both. In case of multiple files or folders, you can list them in new lines. To exclude a path, use **!** as the prefix, e.g. `!path/to/file`
To include a path, don't use any prefix, e.g. `path/to/file` #### Examples | Sample Values | Description | |---|---| | `!README.md` | **Exclusion of a single file in root folder:**
Commits containing changes made only in README.md file will not be shown | | `!README.md`
`!index.js` | **Exclusion of multiple files in root folder:**
Commits containing changes made only in README.md or/and index.js files will not be shown | | `README.md` | **Inclusion of a single file in root folder:**
Commits containing changes made only in README.md file will be shown. Rest all will be excluded. | | `!src/extensions/printer/code2.py` | **Exclusion of a single file in a folder tree:**
Commits containing changes made specifically to code2.py file will not be shown | | `!src/*` | **Exclusion of a single folder and all its files:**
Commits containing changes made specifically to files within src folder will not be shown | | `!README.md`
`index.js` | **Exclusion and inclusion of files:**
Commits containing changes made only in README.md will not be shown, but commits made in index.js file will be shown. All other commits apart from the aforementioned files will be excluded. | | `!README.md`
`README.md` | **Exclusion and inclusion of conflicting files:**
If conflicting paths are defined in the rule, the one defined later will be considered. In this case, commits containing changes made only in README.md will be shown. | You may use the **Learn how** link (as shown below) to understand the syntax of defining an exclusion or inclusion rule. Since file paths can be long, Devtron supports regex too for writing the paths. To understand it better, you may click the **How to use** link as shown below. #### How to view excluded commits? As we saw earlier in fig. 4 and 5, commits containing the changes of only `README.md` file were not displayed, since the file was in the exclusion list. However, Devtron gives you the option to view the excluded commits too. There's a döner menu at the top-right (beside the `Search by commit hash` search bar). The **EXCLUDED** label (in red) indicates that the commits contain changes made only to the excluded file, and hence they are unavailable for build. ### Set clone directory After clicking the checkbox, a field titled `clone directory path` appears. It is the directory where your code will be cloned for the repository you specified in the previous step. This field is optional for a single Git repository application and you can leave the path as default. Devtron assigns a directory by itself when the field is left blank. The default value of this field is `./` ### Pull submodules recursively This checkbox is optional and is used for pulling [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) present in a repo. The submodules will be pulled recursively, and the auth method used for the parent repo will be used for submodules too. --- ## Multi Repo Application As discussed earlier, Devtron also supports multiple git repositories in a single application. To add multiple repositories, click **Add Git Repository** and repeat all the steps as mentioned in [Single Repo Application](#single-repo-application). However, ensure that the clone directory paths are unique for each repo. Repeat the process for every new git repository you add. The clone directory path is used by Devtron to assign a directory to each of your Git repositories. Devtron will clone your code at those locations and those paths can be referenced in the Docker file to create a Docker image of the application. Whenever a change is pushed to any of the configured repositories, CI will be triggered and a new Docker image file will be built (based on the latest commits of the configured repositories). Next, the image will be pushed to the container registry you configured in Devtron. {% hint style="info" %} Even if you add multiple repositories, only one image will be created based on the Dockerfile as shown in the [docker build config](docker-build-configuration.md) {% endhint %} ### Why do you need Multi-Git support? Let’s look at this with an example: Due to security reasons, you want to keep sensitive configurations like third-party API keys in separate access-restricted git repositories, and the source code in a Git repository that every developer has access to. To deploy this application, code from both the repositories are required. A Multi-Git support helps you achieve it. Other examples where you might need Multi-Git support: * To make code modularized, where front-end and back-end code are in different repos * Common library extracted out in a different repo so that other projects can use it --- ### User Guide Creating Application Gitops Config (`docs/user-guide/creating-application/gitops-config.md`) # GitOps Configuration {% hint style="warning" %} The 'GitOps Configuration' page appears only if the super-admin has enabled 'Allow changing git repository for application' in [Global Configurations → GitOps](../global-configurations/gitops.md). {% endhint %} ## Introduction This configuration is an extension of the [GitOps](../global-configurations/gitops.md) settings present in [Global Configurations](../global-configurations/README.md) of Devtron. Therefore, make sure you read it before making any changes to your app configuration. The application-level GitOps configuration offers the flexibility to add a custom Git repo (as opposed to Devtron auto-creating a repo for your application). --- ## Adding Custom Git Repo for GitOps {% hint style="warning" %} ### Who Can Perform This Action? Users need to have [Admin permission](../../user-guide/global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the environment and application) to configure user-defined Git repo. {% endhint %} ### For Devtron Apps 1. Go to **Applications** → **Devtron Apps** (tab) → (choose your app) → **App Configuration** (tab) → **GitOps Configuration**. 2. Assuming a GitOps repo was not added to your application earlier, you get 2 options: * **Auto-create repository** - Select this option if you wish to proceed with the default behavior. It will create a repository automatically, named after your application with a prefix. Thus saving you the trouble of creating one manually. * **Commit manifests to a desired repository** - Select this option if you wish to add a custom repo that is already created with your [Git provider](../global-configurations/gitops.md#supported-git-providers). Enter its link in the `Git Repo URL` field. {% hint style="warning" %} GitOps repositories, whether auto-created by Devtron or added manually, are immutable. This means they cannot be modified after creation. The same is true if you have an existing CD pipeline that uses/used GitOps for deployment. {% endhint %} 3. Click **Save**. **Note**: In case you skipped the GitOps configuration for your application and proceeded towards the [creation of a new CD pipeline](../creating-application/workflow/cd-pipeline.md#creating-cd-pipeline) (that uses GitOps), you will be prompted to configure GitOps as shown below: ### For Helm Apps You can [deploy a helm chart](../deploy-chart/overview-of-charts.md#deploying-chart) using either Helm or GitOps. Let's assume you wish to deploy `airflow` chart. 1. Select the helm chart from the [Chart Store](../deploy-chart/README.md). 2. Click **Configure & Deploy**. 3. After you enter the `App Name`, `Project`, and `Environment`; an option to choose the deployment approach (i.e., Helm or GitOps) would appear. Select **GitOps**. {% hint style="info" %} The option to choose between 'Helm' or 'GitOps' is only available in {% endhint %} 4. A modal window will appear for you to enter a Git repository. Just like [Devtron Apps](#for-devtron-apps) (step 2), you get two options: * Auto-create repository * Commit manifests to a desired repository 5. Enter your custom Git Repo URL, and click **Save**. Next, you may proceed to deploy the chart. {% hint style="warning" %} Once you deploy a helm app with GitOps, you cannot change its GitOps repo. {% endhint %} --- ### User Guide Creating Application Secrets (`docs/user-guide/creating-application/secrets.md`) # Secrets Secrets and configmaps both are used to store environment variables but there is one major difference between them: Configmap stores key-values in normal text format while secrets store them in base64 encrypted form. Devtron hides the data of secrets for the normal users and it is only visible to the users having edit permission. Secret objects let you store and manage sensitive information, such as passwords, authentication tokens, and ssh keys. Embedding this information in secrets is safer and more flexible than putting it verbatim in a Pod definition or in a container image. ## Configure Secret Click `Add Secret` to add a new secret. | Key | Description | | :--- | :--- | | `Name` | Provide a name to your Secret | | `Data Type` | Provide the Data Type of your secret. To know about different Data Types available click on [Data Types](secrets.md#data-types) | | `Data Volume` | Specify if there is a need to add a volume that is accessible to the Containers running in a pod. | | `Use secrets as Environment Variable` | Select this option if you want to inject Environment Variables in your pods using Secrets. | | `Use secrets as Data Volume` | Select this option if you want to configure a Data Volume that is accessible to Containers running in a pod. Ensure that you provide a Volume mount path for the same. | | `Key-Value` | Provide a key and the corresponding value of the provided key. | ## Volume Mount Path Specify the volume mount folder path in `Volume Mount Path`, a path where the data volume needs to be mounted. This volume will be accessible to the containers running in a pod. ## Sub Path For multiple files mount at the same location you need to check sub path `bool` field, it will use the file name (key) as sub path. Sub Path feature is not applicable in case of external configmap except AWS Secret Manager, AWS System Manager and Hashi Corp Vault, for these cases `Name (Secret key)` as sub path will be picked up automatically. ## File Permission File permission will be provide at the configmap level not on the each key of the configmap. it will take 3 digit standard permission for the file. Click `Save Secret` to save the secret. You can see the Secret is added. ## Update Secrets You can update your secrets anytime later, but you cannot change the name of your secrets. If you want to change your name of secrets then you have to create a new secret. To update secrets, click the secret you wish to update. Click `Update Secret` to update your secret. ## Delete Secret You can delete your secret. Click your secret and click the `delete sign` to delete your secret. ## Data Types There are five Data types that you can use to save your secret. * **Kubernetes Secret**: The secret that you create using Devtron. * **Kubernetes External Secret**: The secret data of your application is fetched by Devtron externally. Then the Kubernetes External Secret is converted to Kubernetes Secret. * **AWS Secret Manager**: The secret data of your application is fetched from AWS Secret Manager and then converted to Kubernetes Secret from AWS Secret. * **AWS System Manager**: The secret data for your application is fetched from AWS System Secret Manager and all the secrets stored in AWS System Manager are converted to Kubernetes Secret. * **HashiCorp Vault**: The secret data for your application is fetched from HashiCorp Vault and the secrets stored in HashiCorp Vault are converted to Kubernetes Secret. *Note: The conversion of secrets from various data types to Kubernetes Secrets is done within Devtron and irrespective of the data type, after conversion, the Pods access `secrets` normally.* ## Mount Existing Kubernetes Secrets Use this option to mount an existing Kubernetes Secret in your application pods. A Secret will not be created by system so please ensure that the secret already exist within the namespace else the deployment will fail. ### Kubernetes External Secret (Deprecated) The secret that is already created and stored in the environment and being used by Devtron externally is referred here as `Kubernetes External Secret`. For this option, Devtron will not create any secret by itself but they can be used within the pods. Before adding secret from kubernetes external secret, please make sure that secret with the same name is present in the environment. To add secret from kubernetes external secret, follow the steps mentioned below: 1. Navigate to `Secrets` of the application. 2. Click `Add Secret` to add a new secret. 3. Select `Kubernetes External Secret` from dropdown of `Data type`. 4. Provide a name to your secret. Devtron will search secret in the environment with the same name that you mention here. ### AWS Secret Manager Before adding any external secrets on Devtron, `kubernetes-external-secrets` must be installed on the target cluster. Kubernetes External Secrets allows you to use external secret management systems (e.g., AWS Secrets Manager, Hashicorp Vault, etc) to securely add secrets in Kubernetes. #### Installing kubernetes-external-secrets Using Chart To install the chart with the release named my-release: ```bash $ helm install my-release external-secrets/kubernetes-external-secrets ``` To install the chart with AWS IAM Roles for Service Accounts: ```bash $ helm install my-release external-secrets/kubernetes-external-secrets --set securityContext.fsGroup=65534 --set serviceAccount.annotations."eks\.amazonaws\.com/role-arn"='arn:aws:iam::111111111111:role/ROLENAME' ``` #### Adding Secrets From AWS Secret Manager To add secrets from AWS secret manager, navigate to `Secrets` of the application and follow the steps mentioned below : 1. Click `Add Secret` to add a new secret. 2. Select `AWS Secret Manager` from dropdown of `Data type`. 3. Provide a name to your secret. 4. Select how you want to use the secret. You may leave it selected as environment variable and also you may leave `Role ARN` empty. 5. In `Data` section, you will have to provide data in key-value format. All the required field to pass your data to fetch secrets on Devtron are described below : | Key | Description | | :--- | :--- | |`key`| Secret key in backend | |`name`| Name for this key in the generated secret | |`property`| Property to extract if secret in backend is a JSON object | |`isBinary`| Set this to true if configuring an item for a binary file stored else set false | #### Adding Secrets in AWS Secret Manager To add secrets in AWS secret manager, do the following steps : 1. Go to AWS secret manager console. 2. Click `Store a new secret`. 3. Add and save your secret. --- ### User Guide Deploy Chart Chart Group (`docs/user-guide/deploy-chart/chart-group.md`) # Chart Group ## Introduction Using Devtron UI, one or more Helm charts can be grouped and deployed together with a single click. ## 1. Create Group 1. In the left pane, select `Charts`. 2. On the `Chart Store` page, select `Create Group` from the upper-right corner. 3. In the `Create Chart Group` screen, enter `name` and `description`(optional) for the chart group, and then select `Create Group`. Once you create the group, you can now select and add the charts to this chart group. ## 2. Add Charts To Group 1. To add a chart to the group, click the `+` sign at the top-right corner of a chart, and then select `Save`. 2. Click on `Group Detail` to see all the running instances and group details. You can also edit the chart group from here. ## 3.Bulk Deploy and Edit Option for Charts You can see all the charts in the chart group in the right panel. 1. Select `Deploy to..`. 2. In the `Deploy Selected Charts`, select the `Project` and `Deploy to Environment` values where you want to deploy the chart group. 3. Select `Advanced Options` for more deploy options, such as editing the `values.yaml` or changing the `Environment` and `Project` for each chart. --- ### User Guide Deploy Chart Deployment Of Charts (`docs/user-guide/deploy-chart/deployment-of-charts.md`) # Chart Operations ## Introduction Discover, Create, Deploy, Update, Upgrade, Delete charts. ## 1. Discover the chart from the Chart Store Select the `Charts` section from the left pane, you will be landed to the `Chart Store` page. Search `nginx` or any other charts in search filter. Click on chart and it will redirect you to `Chart Details` page where you can see a number of instances deployed by using the same chart. ## 2. Configure the Chart After selecting the version and values, click on `Deploy` Enter the following details, to deploy chart: | Key | Description | | :--- | :--- | | `App Name` | Name of the Chart Unique| | `Project` | Project in which you want to deploy the chart | | `Environment` | Environment in which you want to deploy the chart | | `Chart Version` | Chart version | | `Chart Value` | Latest default value or create a custom value | you can choose any chart version, values and update it on values.yaml Click on `Deploy` to deploy the Chart ## 3. Status of Deployment After clicking on `Deploy` you will land on a page that shows the status of the deployment of the Chart. The status of the chart should be `Healthy`. It might take a few seconds after initiating the deployment of the chart. In case the status of the deployment is `Degraded` or takes a long time to get deployed, click on `Details` in `Application Status` section on the same page or check the logs of the pods to debug the issue. 1. Shows status of deployed chart. 2. Shows the controller service accounts being used. 3. Clicking on `values` will land you on the page where you can update, upgrade or delete chart. 4. Clicking on `View Chart` will land you to the page where you can see all the running instances of this chart. To see deployment history of Helm application, click on `Deployment history` from `App details` page. ## 4. Update or Upgrade Chart For update you can change its `chart version` or `values.yaml` and then click on `Update And Deploy`. For upgrade click on `Repo/Chart` field and search any chart name like `nginx-ingress` and change values corresponding to that chart and Click on `Update And Deploy`. After an update or upgrade you again will land on `App Detail` page, where you can check pods and service name. ## 5. Chart Details and Delete Charts By clicking on `View Chart` in `Chart Used` section on `App Details` page, it will redirect you to `Chart Details` page where you can see number of instances installed by this chart and also you can delete the chart instance from here. --- ### User Guide Deploy Chart Overview Of Charts (`docs/user-guide/deploy-chart/overview-of-charts.md`) # Overview Of Charts ## Deploying Charts Charts can be deployed individually or by creating a group of Charts. Both methods are mentioned here. ### Deploying Chart To deploy any chart or chart group, visit the `Charts` section from the left panel and then select the chart that you want to use. Click on `README.md` to get more ideas about the configurations of the chart. Select the Chart Version that you want to use and Chart Value, you can either use the Default Values or Custom Values. To know about Custom Values, Click On: [Custom Values](overview-of-charts.md#custom-values) The configuration values can be edited in the section given below Chart Version. | Key | Description | | :--- | :--- | | `App Name` | Name of the app | | `Project` | Project of the app | | `Environment` | Environment of the app to be deployed in | | `Chart Version` | Version of the chart to be used | Readme.md present on the left can be used by the user to set configuration values. Click on `Deploy Chart` to deploy the chart. Click on `App Details` to see the status and details of the deployed chart and click on `Values` to reconfigure the deployment. Configuration values can be edited over here by the help of Readme.md. Click on `Update And Deploy` to update new settings. You can also see deployment history of Helm application and values.yaml corresponding to the deployment by clicking on `Deployment history`. ### Custom Values You can use the default values or create Custom value by clicking on `Create Custom`. You can name your Custom Value, select the Chart Version and change the configurations in YAML file. Click on `Save Template` to save the configurations. ### Deploying Chart Groups You can deploy multiple applications and work with them simultaneously by creating `Chart Group`. To create chart group click on `Create Group`. Add the `Group Name` and `Description`(optional), and select `Create Group`. You can select the Charts that you want to add to your Chart Group by clicking on '+' sign. You also can add multiple copies of the same chart in the chart group according to your requirements. Select the `Version` and `Values` for your charts. You can use Default Values or the Custom Values, just make sure the value that you select for the chart is compatible with the version of the chart that you are using. To edit the chart configuration, Click on `Edit`. You can `Add` more charts or `Delete` charts from your existing Chart Group. After making any changes, click on `Save` to save changes for the Chart Group. If you wish to edit the chart configuration of any chart in the chart group, click on that Chart and edit the configurations in YAML file. You also can edit the `App Name`, `Chart Version`, `Values`, `Deploy Environment` and the YAML file from here. | Key | Description | | :--- | :--- | | `App Name` | Name of the app | | `Project` | Name of Project in which app has to be created | | `Environment` | Name of the Environment in which app has to be deployed | | `Chart Version` | Select the Version of the chart to be used | After changing the configurations, click on `Deploy` to initiate the deployment of the chart in the Chart Group. --- ### User Guide Deploying Application Image Labels And Comments (`docs/user-guide/deploying-application/image-labels-and-comments.md`) # Applying Labels and Comments ## Introduction Typically in a CI pipeline, you [build container images](./triggering-ci.md), and the number of images gradually increases over a period of time. Devtron's image labels and comments feature helps you to mark and recall specific images from the repository by allowing you to add special instructions or notes to them. For example: * You can label an image as `non-prod` to indicate that it is meant for 'Dev' or 'QA' environments, but not for production. * Add `hotfix image only` label to indicate a one-time patch on production. * Comments like `This image is buggy and shouldn't be used for deployment` to caution other users from deploying an unwanted image. Such labels and comments will be visible only within Devtron, and will not propagate to your [container registry](../../reference/glossary.md#containeroci-registry) (say Docker Hub), unlike custom [image tag pattern](../creating-application/workflow/ci-pipeline.md#custom-image-tag-pattern). You may use it to simplify the management and [selection of container images](./triggering-cd.md#deploying-approved-image) for deployment. {% hint style="warning" %} Tagging labels and comments are supported only for images in workflows with at least one production deployment pipeline. In Devtron, you can go to **Global Configurations** → **Clusters & Environments** to identify a production environment by checking the 'Prod' label. {% endhint %} --- ## Adding Labels & Comments {% hint style="warning" %} ### Who Can Perform This Action? Users need to have [Build & deploy permission](../global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the environment and application) to add labels and comments. {% endhint %} You can add labels and comments from the following pages: * [From Build & Deploy](#from-build--deploy) * [From Build History](#from-build-history) * [From Deployment History](#from-deployment-history) (only after deployment) * [From App Details](#from-app-details) (only after deployment) {% hint style="warning" %} You can add multiple labels to an image. but each label can be used only once 'per image, per application'. You may use it in an image of other application though.
Refer [Deleting Labels](#deleting-labels-and-comments) if you commit a mistake while adding labels. {% endhint %} ### From Build & Deploy ### From Build History ### From Deployment History ### From App Details --- ## Deleting Labels & Comments ### Soft-Delete Labels {% hint style="warning" %} ### Who Can Perform This Action? Users need to have [Build & deploy permission](../global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the environment and application) to perform soft deletion of labels. {% endhint %} This action marks the label as invalid but doesn't delete the label. Therefore, you can recover it again but you cannot reuse it for other image (unless it's a different application). 1. Click the edit option. 2. Use the (-) icon to strike off the label. This icon is available on the left-side of a label. 3. Click **Save**. ### Hard-Delete Labels {% hint style="warning" %} ### Who Can Perform This Action? Users need to have super-admin permission to perform hard deletion of labels. {% endhint %} This action deletes the label permanently and makes it available for reuse in same/other image of the given application. 1. Click the edit option. 2. Use the (x) icon to permanently remove the label. This icon is available on the right-side of a label. 3. Click **Save**. ### Removing Comments {% hint style="warning" %} ### Who Can Perform This Action? Users need to have [Build & deploy permission](../global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the environment and application) to remove comments. {% endhint %} If you wish to permanently remove a comment, do the following: 1. Click the edit option. 2. Empty the content of an existing comment. 3. Click **Save**. --- ## Extra Use Case If you use [Application Groups](../application-groups.md) to deploy in bulk, image labels (if added) will be available as filters for you to quickly locate the container image. This will be helpful in scenarios (say release package) where you wish to deploy multiple applications at once, and you have already labelled the intended images of the respective applications. --- ### User Guide Deploying Application Rollback Deployment (`docs/user-guide/deploying-application/rollback-deployment.md`) # Rollback Deployment Deployments can be rolled back manually. After a deployment is completed, you can manually rollback to a previously deployed image by retaining the same configuration or changing the configuration. **As an example**, You have deployed four different releases as follows: | Image | Configuration | Release | | --- | --- | --- | | V1 | C1 | R1 | | V2 | C2 | R2 | | V3 | C2 | R3 | | V3 | C3 | R4 | | V3 | C4 (saved but not deployed)| - | If you want to roll back from V3 image to V2 image, then you have the following options: | Configuration Option | Image | Configuration | | --- | --- | --- | | Config deployed with selected image | V2 | C2 | | Last deployed config | V2 | C3 | | Last saved config | V2 | C4 | 1. Select `Rollback` in your deployed pipeline. 2. On the `Rollback` page, select a configuration to deploy from the list: | Configurations | Description | | --- | --- | | **Last saved config** | Deploy the image with the latest saved configuration. | | **Last deployed config** | Deploy the image with the last deployed configuration. [As an example](#rollback-deployment): `The configuration C3`.| | **Config deployed with selected image** | Deploy the configuration which was deployed with the selected image. [As an example](#rollback-deployment): `The configuration C2`. | 3. Once you select the previously deployed image and the configuration, review the difference between `Last Deployed Configuration` and the selected configuration. 4. Click `Deploy`. The selected previously deployed image will be deployed. **Note**: - There will be no difference in the configuration if you select `Last deployed config` from the list. - When you select `Config deployed with selected image` and if the configuration is missing in the selected previously deployed image, it will show as `Config Not Available`. In such cases, you can select either `Last saved config` or `Last deployed config`. --- ### User Guide Deploying Application Triggering Cd (`docs/user-guide/deploying-application/triggering-cd.md`) # Triggering CD Pipelines After the [CI pipeline](./triggering-ci.md) is complete, you can trigger the CD pipeline. 1. Go to the `Build & Deploy` tab of your application and click **Select Image** in the CD pipeline. 2. Select an image to deploy and then click **Deploy** to trigger the CD pipeline. However, if an image is already deployed, you can identify it by the tag `Active on `. ## Manual Approval for Deployment When [manual approval is enabled](../creating-application/workflow/cd-pipeline.md#4-manual-approval-for-deployment) for the deployment pipeline configured in the workflow, you are expected to request for an image approval before each deployment. Alternatively, you can deploy images that have already been approved once. If no approved images are available or the current image is already deployed, you won't see any images for deployment when clicking **Select Image**. ### Requesting for Image Approval Users need to have [Build & deploy permission](../global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the environment and application) to request for an image approval. To request an image approval, follow these steps: 1. Navigate to the `Build & Deploy` page, and click the **Approval for deployment** icon. 2. Click the **Request Approval** button present on the image for which you want to request an approval and click **Submit Request**. In case you have configured [SES or SMTP on Devtron](../global-configurations/manage-notification.md#notification-configurations), you can directly choose the approver(s) from the list of approvers as shown below. The users you selected will receive an approval request via email. Any user with 'Image approver' permission alongwith access to the given application and given environment would be able to approve the image. #### Extras * In case you wish to cancel the image approval request, you can do so from the `Approval pending` tab as shown in the below image. * If you've received an approval but no longer want the image to be deployable, you can let the approval expire. ### Accepting Image Approval Request By default, super-admin users are considered as the default approvers. Users who build the image and/or request for its approval, cannot self-approve it even if they have super-admin privileges. Users with `Approver` permission (for the specific application and environment) can also approve a deployment. This permission can be granted to users from [`User Permissions`](../global-configurations/authorization/user-access.md#role-based-access-levels) present in [Global Configurations](../global-configurations/README.md). In case [SES](../global-configurations/manage-notification.md#manage-ses-configurations) or [SMTP](../global-configurations/manage-notification.md#manage-smtp-configurations) was configured in Devtron, and the user chose the approvers while raising an image approval request, the approvers would receive an email notification as shown below: To approve an image approval request, follow these steps: 1. Go to the `Build & Deploy` page and click the `Approval for deployment` button. 2. Switch to the `Approval pending` tab. Here, you will get a list of images that are awaiting approval. 3. Click **Approve** followed by **Approve Request** button. ### Deploying Approved Image Users need to have [Build & deploy permission](../global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the respective environment and application) to select and deploy an approved image. In case the super-admin has set the minimum number of approval to more than 1 (in [workflow](../creating-application/workflow/cd-pipeline.md#4-manual-approval-for-deployment)), you must wait for all approvals before deploying the image. In other words, partially approved image will not be eligible for deployment. To deploy an approved image, follow these steps: 1. Navigate to the `Build & Deploy` tab and click **Select Image**. 2. You will find all the approved images listed under the `Approved images` section. From the list, you can select the desired image and deploy it to your environment. 3. You can view the status of current deployment in the `App Details` tab. The status initially appears as `Progressing` for approximately 1-2 minutes, and then gradually transitions to `Healthy` state based on the deployment strategy. Here, our CD pipeline trigger was successful and the deployment is in `Healthy` state. To further diagnose the deployments, [click here](../debugging-deployment-and-monitoring.md) --- ### User Guide Deploying Application Triggering Ci (`docs/user-guide/deploying-application/triggering-ci.md`) # Triggering CI Pipelines To trigger the CI pipeline, first you need to select a Git commit. To select a Git commit, click the **Select Material** button present on the CI pipeline. Once clicked, a list will appear showing various commits made in the repository, it includes details such as the author name, commit date, time, etc. Choose the desired commit for which you want to trigger the pipeline, and then click **Start Build** to initiate the CI pipeline. CI Pipelines with automatic trigger enabled are triggered immediately when a new commit is made to the git branch. If the trigger for a build pipeline is set to manual, it will not be automatically triggered and requires a manual trigger. --- ## Partal Cloning Feature [](https://devtron.ai/pricing) CI builds can be time-consuming for large repositories, especially for enterprises. However, Devtron's partial cloning feature significantly increases cloning speed, reducing the time it takes to clone your source code and leading to faster build times. **Advantages** * Smaller image sizes * Reduced resource usage and costs * Faster software releases * Improved productivity Get in touch with us if you are looking for a way to improve the efficiency of your software development process. The **Refresh** icon updates the Git Commits section in the CI Pipeline by fetching the latest commits from the repository. Clicking on the refresh icon ensures that you have the most recent commit available. The **Ignore Cache** option ignores the previous build cache and creates a fresh build. If selected, will take a longer build time than usual. --- ## Passing Build Parameters [](https://devtron.ai/pricing) {% hint style="warning" %} ### Who Can Perform This Action? Users need to have [Build & deploy permission](../global-configurations/authorization/user-access.md#role-based-access-levels) or above (along with access to the environment and application) to pass build parameters. {% endhint %} If you wish to pass runtime parameters for a build job, you can provide key-value pairs before triggering the build. Thereafter, you can access those passed values by referencing the corresponding keys in the environment variable dictionary. **Steps** 1. Go to the **Parameters** tab available on the screen where you select the commit. 2. Click **+ Add parameter**. 3. Enter your key-value pair as shown below.
Similarly, you may add more than one key-value pair by using the **+ Add Parameter** button. 4. Click **Start Build**. {% hint style="info" %} In case you trigger builds in bulk, you can consider passing build parameters in [Application Groups](../application-groups.md). {% endhint %} --- ## Fetching Logs and Reports Click the `CI Pipeline` or navigate to the `Build History` to get the CI pipeline details such as build logs, source code details, artifacts, and vulnerability scan reports. To access the logs of the CI Pipeline, simply click `Logs`. To view specific details of the Git commit you've selected for the build, click on `Source`. This will provide you with information like the commit ID, author, and commit message associated with that particular commit. By selecting the `Artifacts` option, you can download reports related to the tasks performed in the Pre-CI and Post-CI stages. This will allow you to access and retrieve the generated reports, if any, related to these stages. Additionally, you have the option to add tags or comments to the image directly from this section. To check for any vulnerabilities in the build image, click on `Security`. Please note that vulnerabilities will only be visible if you have enabled the `Scan for vulnerabilities` option in the advanced options of the CI pipeline before building the image. For more information about this feature, please refer to this [documentation](../../user-guide/security-features.md). --- --- METRICS --- - Files Extracted: 94 - Estimated Token Budget: ~97879 tokens - Canonical Reference: https://codewiki.google/github.com/devtron-labs/devtron