diff --git a/docs/FAQs/devtron-troubleshoot.md b/docs/FAQs/devtron-troubleshoot.md index fb6b07624..2e3a8dd15 100644 --- a/docs/FAQs/devtron-troubleshoot.md +++ b/docs/FAQs/devtron-troubleshoot.md @@ -613,3 +613,10 @@ Follow the below steps if you are getting the above error: ![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/devtron-troubleshooting/chart-sync.jpg) +#### 30. The Advanced (YAML) and Basic (GUI) sections are appearing blank in the Base Deployment Template of the application. + +![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/empty-values.jpg) + +This happens due to a missing [app-values.yaml](../user-guide/global-configurations/deployment-charts.md#3-add-app-values.yaml) file in your deployment chart. + +To fix this issue, include an `app-values.yaml` file in your deployment helm chart before uploading the chart. Refer [adding app-values.yaml](../user-guide/global-configurations/deployment-charts.md#3-add-app-values.yaml) to know more. \ No newline at end of file diff --git a/docs/user-guide/global-configurations/deployment-charts.md b/docs/user-guide/global-configurations/deployment-charts.md index 256e105cc..db0222bca 100644 --- a/docs/user-guide/global-configurations/deployment-charts.md +++ b/docs/user-guide/global-configurations/deployment-charts.md @@ -1,70 +1,94 @@ # Deployment Charts -Devtron includes predefined helm charts that cover the majority of use cases. -For any use case not addressed by the default helm charts, you can upload your own helm chart and use it as a custom chart in Devtron. +## Introduction -* Who can upload a custom chart - Super admins -* Who can use the custom chart - All users +Devtron Apps leverage helm charts to carry out deployment of your images and configuration. Devtron includes predefined Helm charts (e.g., Deployment, Rollout, StatefulSet) that cover majority of your use cases. -> A super admin can upload multiple versions of a custom helm chart. +For any use case not addressed by the default Helm charts, you can upload your own Helm chart and use it as a deployment chart in Devtron. ![Figure 1: Deployment Charts](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/gc-deployment-charts.jpg) -## Prerequisites +### Tutorial + +This video contains a quick walkthrough of the steps mentioned in the [Preparing a Deployment Chart](#preparing-a-deployment-chart) section of this page and the subsequent uploading of the deployment chart on Devtron. -1. A valid helm chart, which contains `Chart.yaml` file with name and version fields. -2. Image descriptor template file `.image_descriptor_template.json`. -3. Custom chart packaged in the `*.tgz` format. +{% embed url="https://www.youtube.com/watch?v=jzMZa7bSiyA" caption="How to Upload your Deployment Chart in Devtron" %} + +--- -### 1. How to create a helm chart +## Preparing a Deployment Chart -You can use the following command to create the Helm chart: +### 1. Create a Helm Chart + +You can use the following command to create a Helm chart: ```bash helm create my-custom-chart ``` ->Note: `Chart.yaml` is the metadata file that gets created when you create a [helm chart](https://helm.sh/docs/helm/helm_create/). +> **Note**: `Chart.yaml` is a metadata file that gets created when you create a [helm chart](https://helm.sh/docs/helm/helm_create/). The following table consists the fields that are relevant to you in `Chart.yaml`. | Field | Description | | --- | --- | -| `Name` | Name of the helm chart (Required). | +| `Name` | Name of the Helm chart (Required). | | `Version` | This is the chart version. Update this value for each new version of the chart (Required). | -| `Description` | Description of the chart (Optional). | +| `Description` | Give a description to your chart (Optional). | + +{% hint style="info" %} +### Example of Chart.yaml +[Click here](https://devtron-public-asset.s3.us-east-2.amazonaws.com/custom-charts/chart-yaml-file.png) to view a sample 'Chart.yaml' file. +{% endhint %} -Please see the following example: +### 2. Create an Image Descriptor Template File -![Chart.yaml file](https://devtron-public-asset.s3.us-east-2.amazonaws.com/custom-charts/chart-yaml-file.png) +The Image Descriptor Template file is a GO template that produces a valid JSON file upon processing. It allows Devtron to dynamically inject values from the CD pipeline into your Helm chart during deployment. Therefore, details like image repository, tag, and environment are automatically populated at the placeholders specified in `.image_descriptor_template.json`. -### 2. Create the image descriptor template file `.image_descriptor_template.json` +* In the root directory of your chart, create a file named `.image_descriptor_template.json` using the following command: -It's a GO template file that should produce a valid `JSON` file upon rendering. This file is passed as the last argument in -`helm install -f myvalues.yaml -f override.yaml` command. + ```bash + touch .image_descriptor_template.json + ``` -Place the `.image_descriptor_template.json` file in the root directory of your chart. +* Ensure the above file is created in the directory where the main `Chart.yaml` exists (as shown below): -You can use the following variables in the helm template (all the placeholders are optional): + ![Figure 2: Filepath of Image Descriptor Template](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/descriptor-filepath.jpg) -> The values from the CD deployment pipeline are injected at the placeholder specified in the `.image_descriptor_template.json` template file. +* Paste the following content in `.image_descriptor_template.json` file: -```bash -{ - "server": { - "deployment": { - "image_tag": "{{.Tag}}", - "image": "{{.Name}}" + ```bash + { + "server": { + "deployment": { + "image_tag": "{{.Tag}}", + "image": "{{.Name}}" + } + }, + "pipelineName": "{{.PipelineName}}", + "releaseVersion": "{{.ReleaseVersion}}", + "deploymentType": "{{.DeploymentType}}", + "app": "{{.App}}", + "env": "{{.Env}}", + "appMetrics": {{.AppMetrics}} + } + ``` + + You can customize this template to include only the values your deployment needs. For instance, if you only require the image repository and tag, your template would look like: + + ```bash + { + "image": { + "repository": "{{.Name}}", + "tag": "{{.Tag}}" } - }, - "pipelineName": "{{.PipelineName}}", - "releaseVersion": "{{.ReleaseVersion}}", - "deploymentType": "{{.DeploymentType}}", - "app": "{{.App}}", - "env": "{{.Env}}", - "appMetrics": {{.AppMetrics}} -} -``` + } + ``` -| Field | Description | +{% hint style="warning" %} +### Got a JSON Error? +If your code editor highlights a syntax error (property or EOF error) in the above JSON, ignore it. +{% endhint %} + + + +### 3. Add app-values.yaml + +In the root directory of your chart, Devtron expects an `app-values.yaml` file. It uses this file to determine the values to be displayed on the [deployment template](../../reference/glossary.md#base-deployment-template) as shown below. + +![Figure 3: Chart Values](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/deployment-template.jpg) + +The `app-values.yaml` file is simply a subset of your `values.yaml` file. Therefore, you can insert specific entries from `values.yaml` that you wish to display. + +However, if you upload the chart without an `app-values.yaml` or with an empty one, your deployment template will appear blank (as shown below) or null. + +![Figure 4: Blank Chart Values](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/empty-values.jpg) + + +### 4. Add release-values.yaml + +The `release-values.yaml` file contains essential values needed for deployment that aren’t covered by [app-values.yaml](#3-add-app-values.yaml). For example: + +* Some dynamic values (such as `IMAGE_TAG` and `IMAGE_REPO` from the [image descriptor JSON file](#2-create-an-image-descriptor-template-file)) are populated here because they are needed for deployment. +* You can use `autoPromotionSeconds` to decide how long to keep old pods running once the latest pods of new release are available. + +In the root directory of your chart, create a file named `release-values.yaml` with the following command: -> **For example**: -> -> To create a template file to allow Devtron to only render the repository name and the tag from the CI/CD pipeline that you created, edit the `.image_descriptor_template.json` file as: -> ```bash -> { -> "image": { -> "repository": "{{.Name}}", -> "tag": "{{.Tag}}" -> } -> } -> ``` +```bash +touch release-values.yaml +``` -### 3. Package the custom chart in the `*.tgz` format +Use the following content in the `release-values.yaml` file (edit it as per your requirement): -> Before you begin, ensure that your helm chart includes both `Chart.yaml` (with `name` and `version` fields) and `.image_descriptor_template.json` files. +```yml +server: + deployment: + image_tag: IMAGE_TAG + image: IMAGE_REPO + enabled: false +dbMigrationConfig: + enabled: false -The helm chart to be uploaded must be packaged as a versioned archive file in the format `-vx.x.x.tgz`. +pauseForSecondsBeforeSwitchActive: 0 +waitForSecondsBeforeScalingDown: 0 +autoPromotionSeconds: 30 +#used for deployment algo selection +orchestrator.deploymant.algo: 1 ``` + +### 5. Package the chart in a tgz format + + + +The Helm chart to be uploaded must be packaged as a versioned archive file in the format: `-x.x.x.tgz`. +Both `` and `x.x.x` will be automatically fetched from the name and version fields present in the Chart.yaml file, respectively." + +{% hint style="warning" %} +### Note +Ensure you navigate out of the Helm chart folder before packaging it in a '.tgz' format +{% endhint %} + +Run the following command to package the chart: + +```bash helm package my-custom-chart ``` -The above command will create a `my-custom-chart-0.1.0.tgz` file. +The above command will generate a `-x.x.x.tgz` file. --- ## Uploading a Deployment Chart -> A custom chart can only be uploaded by a super admin. +{% hint style="warning" %} +### Who Can Perform This Action? +Only super admin users can upload a deployment chart. A super admin can upload multiple versions of a chart. +{% endhint %} -* On the Devtron dashboard, select **Global Configurations > Custom charts**. -* Select **Import Chart**. -* **Select tar.gz file...** and upload the packaged custom chart in the `*.tgz` format. +### Steps -![Selecting custom chart](https://devtron-public-asset.s3.us-east-2.amazonaws.com/custom-charts/Chart+pre-requisites.png) +* Go to **Global Configurations** → **Deployment Charts**. -The chart is being uploaded and validated. You may also **Cancel upload** if required. + ![Figure 5: Global Configurations - Deployment Charts](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/gc-deployment-charts.jpg) -![Uploading custom chart](https://devtron-public-asset.s3.us-east-2.amazonaws.com/custom-charts/List+-+Empty-4.png) +* Click **Upload Chart**. -### Validation + ![Figure 6: Upload Chart Button](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/upload-chart.jpg) -The uploaded archive will be validated against: +* Click **Select .tgz file** and upload your packaged deployment chart (in **.tgz** format). -- Supported archive template should be in `*.tgz` format. -- Content of `values.yaml` should be there in `app-values.yaml` file. -- `release-values.yaml` file is required. -- ConfigMap/Secret template should be same as that of our [reference chart](https://github.com/devtron-labs/devtron/tree/main/scripts/devtron-reference-helm-charts/reference-chart_4-14-0). -- `Chart.yaml` must include the name and the version number. -- `..image_descriptor_template.json` file should be present and the field format must match the format listed in the image builder template section. + ![Figure 7: Uploading .tgz File](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/select-tgz-file.jpg) +The system initiates the validation of your uploaded chart. You may also click **Cancel upload** if you wish to abort the process. -The following are the validation results: +![Figure 8: Cancelling Upload](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/cancel-upload.jpg) -| Validation status | Description | User action | -| :--- | :--- | :--- | -| **Success** | The files uploaded are validated. | Enter a description for the chart and select **Save** or **Cancel upload**. | -| **Unsupported template** | The archive file do not match the [required template](#prerequisites). | **Upload another chart** or **Cancel upload**. | -| **New version detected** | You are uploading a newer version of an existing chart | Enter a **Description** and select **Save** to continue uploading, or **Cancel upload**. | -| **Already exists** | There already exists a chart with the same version. |
  • Edit the version and re-upload the same chart using **Upload another chart**.
  • Upload a new chart with a new name using **Upload another chart**.
  • **Cancel upload**.
| +### Validation Checks -![Chart validated](https://devtron-public-asset.s3.us-east-2.amazonaws.com/custom-charts/List+-+Empty-2.png) +In the uploading process, your file will be validated against the following criteria: -![Unsupported template](https://devtron-public-asset.s3.us-east-2.amazonaws.com/custom-charts/List+-+Empty.png) +- Supported archive template should be in `*.tgz` format. +- `Chart.yaml` must include the name and the version number. +- `.image_descriptor_template.json` file should be present. -![New version detected](https://devtron-public-asset.s3.us-east-2.amazonaws.com/custom-charts/List+-+Empty-3.png) +The following are interpretations of the validation checks performed: -![Already exists](https://devtron-public-asset.s3.us-east-2.amazonaws.com/custom-charts/List+-+Empty-1.png) +| Validation Status | Description | User Action | +| :--- | :--- | :--- | +| **Success** | The files uploaded are validated
([View Snapshot](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/chart-success.jpg)) | Enter a description for the chart and select **Save** or **Cancel upload** | +| **Unsupported template** | The archive file do not match the [required template](#preparing-a-deployment-chart)
([View Snapshot](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/unsupported-template.jpg)) | **Upload another chart** or **Cancel upload** | +| **New version detected** | You are uploading a newer version of an existing chart
([View Snapshot](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/new-version.jpg)) | Enter a **Description** and select **Save** to continue uploading, or **Cancel upload** | +| **Already exists** | There already exists a chart with the same version
([View Snapshot](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/chart-exists.jpg)) |
  • Edit the version and re-upload the same chart using **Upload another chart**.
  • Upload a new chart with a new name using **Upload another chart**
  • **Cancel upload**
| --- ## Viewing Deployment Charts -> All users can view the custom charts. +{% hint style="warning" %} +### Who Can Perform This Action? +Only super-admins can view deployment charts. +{% endhint %} -To view the list of available custom charts, go to **Global Configurations → Deployment Charts** page. +To view the list of available deployment charts, go to **Global Configurations** → **Deployment Charts** page. -* The charts can be searched with their name, version, or description. -* New [custom charts can be uploaded](#uploading-a-custom-chart) by selecting **Upload chart**. +![Figure 9: Viewing Deployment Charts](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/view-charts.jpg) -![Custom charts](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/upload-custom-chart.jpg) +* You can search a chart by its name, version, or description. +* You can add new [charts or chart versions](#uploading-a-deployment-chart) by clicking **Upload Chart**. --- ## Using Deployment Chart in Application -The custom charts can be used from the [Deployment Template](../creating-application/deployment-template.md) section. +Once you successfully upload a deployment chart, you can start using it as a deployment template for your application. Refer [Deployment Template](../creating-application/deployment-template.md) to know more. -> **Info**: -> -> The deployment strategy for a custom chart is fetched from the custom chart template and cannot be configured in the [CD pipeline](../creating-application/workflow/cd-pipeline.md#deployment-strategies). +![Figure 10: Using Deployment Charts](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/use-chart.gif) + +{% hint style="warning" %} +### Note +The deployment strategy for a deployment chart is fetched from the chart template and cannot be configured in the [CD pipeline](../creating-application/workflow/cd-pipeline.md#deployment-strategies). +{% endhint %} --- @@ -173,16 +243,16 @@ The custom charts can be used from the [Deployment Template](../creating-applica {% hint style="warning" %} ### Who Can Perform This Action? -Only superadmins can edit the GUI schema of deployment charts. +Only super-admins can edit the GUI schema of deployment charts. {% endhint %} {% hint style="info" %} ### Reference -This section is an extension of [Customize Basic GUI](../creating-application/deployment-template.md#customize-basic-gui) feature within **App Configuration** → **Base Deployment Template**. Refer the document to know more about the significance of having a customizable GUI schema for your deployment templates. +This section is an extension of [Customize GUI](../creating-application/deployment-template.md#customize-basic-gui) feature. Refer the document to know more about the significance of having a custom GUI schema for your deployment templates. {% endhint %} -You can edit the GUI schema of both the deployment charts: -1. Charts provided by Devtron (*Deployment*, *Job & CronJob*, *Rollout Deployment*, and *StatefulSet*) +You can edit the GUI schema of the following deployment charts: +1. Default charts provided by Devtron (*Deployment*, *Job & CronJob*, *Rollout Deployment*, and *StatefulSet*) 2. Custom charts uploaded by you ### Tutorial @@ -195,22 +265,22 @@ In this example, we will edit the Deployment chart type provided by Devtron. 1. Click the edit button next to the chart as shown below. - ![Edit GUI Schema Button](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/edit-chart-schema.jpg) + ![Figure 11: Edit GUI Schema Button](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/edit-chart-schema.jpg) 2. A GUI schema is available for you to edit in case of Devtron charts. In case of custom charts, you may have to define a GUI schema yourself. To know how to create such GUI schema, refer [RJSF JSON Schema Tool](https://rjsf-team.github.io/react-jsonschema-form/). - ![Editable Schema](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/gui-schema.jpg) + ![Figure 12: Editable Schema](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/gui-schema.jpg) 3. You may start editing the schema by excluding existing fields/objects or including more of them. Click the **Refer YAML** button to view all the supported fields. - ![Refer YAML Button](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/refer-yaml.gif) + ![Figure 13: Refer YAML Button](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/refer-yaml.gif) 4. While editing the schema, you may use the **Preview GUI** option for a real-time preview of your changes. - ![Preview GUI Button](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/preview-gui.gif) + ![Figure 14: Preview GUI Button](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/preview-gui.gif) 5. Click **Save Changes**. - ![Save Changes](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/save-changes.jpg) + ![Figure 15: Save Changes](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/global-configurations/deployment-charts/save-changes.jpg) -Next, if you go to **App Configuration** → **Base Deployment Template**, you will be able to see the deployment template fields (in Basic GUI) as per your customized schema. \ No newline at end of file +Next, if you go to **App Configuration** → **Base Configurations** → **Deployment Template**, you will be able to see the deployment template fields (in GUI) as per your customized schema. \ No newline at end of file