Skip to content

Commit e0feaa5

Browse files
author
Divya Bhushan
authored
docs: Adding docs for custom charts (BYOC) (#1762)
1 parent b5785a5 commit e0feaa5

File tree

3 files changed

+195
-2
lines changed

3 files changed

+195
-2
lines changed

‎docs/user-guide/creating-application/deployment-template.md‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,41 @@
11
# Devtron Charts
22

3-
This documentation consists of the charts available on Devtron.
3+
A deployment configuration is a manifest for the application. It defines the runtime behavior of the application.
4+
5+
Devtron includes deployment template for both default as well as custom charts created by a super admin.
6+
7+
To configure a deployment chart for your application:
8+
9+
* Go to **Applications** and create a new application.
10+
* Go to **App Configuration** page and configure your application.
11+
* On the **Deployment Template** page, select the drop-down under **Chart type**.
12+
13+
You can select a chart in one of the following ways:
14+
15+
## Select chart by Devtron
416

517
1. [Rollout Deployment](deployment-template/rollout-deployment.md)
618
2. [Job and Cronjob](deployment-template/job-and-cronjob.md)
719
3. Knative
20+
21+
## Select chart from custom charts
22+
23+
Custom charts are added by a super admin from the [custom charts](./../global-configurations/custom-charts.md) section.
24+
25+
Users can select the available custom charts from the drop-down list.
26+
27+
![Select custom chart](https://devtron-public-asset.s3.us-east-2.amazonaws.com/custom-charts/use-custom-chart.png)
28+
29+
### Upload custom chart
30+
31+
A [custom chart](../global-configurations/custom-charts.md) can be uploaded by a super admin.
32+
33+
## Application Metrics
34+
35+
Enable **show application metrics** toggle to view the application metrics on the **App Details** page.
36+
37+
![Show application metrics](https://devtron-public-asset.s3.us-east-2.amazonaws.com/custom-charts/show-application-metrics.png)
38+
39+
> **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-prod environment before enabling it in production environment.
40+
41+
Select **Save** to save your configurations.

‎docs/user-guide/creating-application/workflow/ci-pipeline.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@
66
77
A CI Pipeline can be created in one of the three ways:
88

9-
[Continous Integration](#1-continuous-integration) | [Linked CI Pipeline](#2-linked-ci-pipeline) | [Incoming Webhook](#3-incoming-webhook)
9+
* [Continuous Integration](#1-continuous-integration)
10+
* [Linked CI Pipeline](#2.-linked-ci-pipeline)
11+
* [Incoming Webhook](#3.-incoming-webhook)
1012

1113
![](https://devtron-public-asset.s3.us-east-2.amazonaws.com/images/creating-application/workflow-ci-pipeline/workflow-ci.jpg)
1214

‎docs/user-guide/global-configurations/custom-charts.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# Custom charts
2+
3+
Devtron includes predefined helm charts that cover the majority of use cases.
4+
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.
5+
6+
* Who can upload a custom chart - Super admins
7+
* Who can use the custom chart - All users
8+
9+
> A super admin can upload multiple versions of a custom helm chart.
10+
11+
![Custom charts](https://devtron-public-asset.s3.us-east-2.amazonaws.com/custom-charts/custom-charts-lists.png)
12+
13+
## Prerequisites
14+
15+
1. A valid [helm chart](#1-how-to-create-a-helm-chart), which contains `Chart.yaml` file with name and version fields.
16+
2. [Image descriptor template file - `.image_descriptor_template.json`](#2-create-the-image-descriptor-template-file---image_descriptor_templatejson).
17+
3. [Custom chart packaged in the `*.tgz` format](#3-package-the-custom-chart-in-the-tgz-format).
18+
19+
### 1. How to create a helm chart
20+
21+
`Chart.yaml` is the metadata file that gets created when you create a [helm chart](https://helm.sh/docs/helm/helm_create/).
22+
23+
```bash
24+
helm create my-custom-chart
25+
```
26+
27+
| Field | Description |
28+
| --- | --- |
29+
| Name | Required. Name of the helm chart. |
30+
| Version | Required. This is the chart version. Update this value for each new version of the chart. |
31+
| Description | Optional. Description of the chart. |
32+
33+
![Chart.yaml file](https://devtron-public-asset.s3.us-east-2.amazonaws.com/custom-charts/chart-yaml-file.png)
34+
35+
### 2. Create the image descriptor template file - `.image_descriptor_template.json`
36+
37+
It's a GO template file that should produce a valid `JSON` file upon rendering. This file is passed as the last argument in
38+
`helm install -f myvalues.yaml -f override.yaml ` command.
39+
40+
Place the `.image_descriptor_template.json` file in the root directory of your chart.
41+
42+
You can use the following variables in the helm template (all the placeholders are optional):
43+
44+
> The values from the CD deployment pipeline are injected at the placeholder specified in the `.image_descriptor_template.json` template file.
45+
46+
```bash
47+
{
48+
"server": {
49+
"deployment": {
50+
"image_tag": "{{.Tag}}"
51+
"image": "{{.Name}}"
52+
}
53+
},
54+
"pipelineName": "{{.PipelineName}}",
55+
"releaseVersion": "{{.ReleaseVersion}}",
56+
"deploymentType": "{{.DeploymentType}}", ?
57+
"app": "{{.App}}",
58+
"env": "{{.Env}}",
59+
"appMetrics": {
60+
{.AppMetrics
61+
}
62+
}
63+
}
64+
```
65+
66+
| Field | Description |
67+
| --- | --- |
68+
| **image_tag** | The build image tag |
69+
| **image** | Repository name |
70+
| **pipelineName** | The CD pipeline name created in Devtron |
71+
| **releaseVersion** | Devtron's internal release number |
72+
| **deploymentType** | Deployment strategy used in the pipeline |
73+
| **app** | Application's ID within the Devtron ecosystem |
74+
| **env** | Environment used to deploy the chart |
75+
| **appMetrics** | For the App metrics UI feature to be effective, include the `appMetrics` placeholder. |
76+
77+
> **For example**:
78+
>
79+
> 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:
80+
> ```bash
81+
> {
82+
> "image": {
83+
> "repository": "{{.Name}}",
84+
> "tag": "{{.Tag}}"
85+
> }
86+
> }
87+
> ```
88+
89+
### 3. Package the custom chart in the `*.tgz` format
90+
91+
> Before you begin, ensure that your helm chart includes both `Chart.yaml` (with `name` and `version` fields) and `.image_descriptor_template.json` files.
92+
93+
The helm chart to be uploaded must be packaged as a versioned archive file in the format - `<helm-chart-name>-vx.x.x.tgz`.
94+
95+
```
96+
helm package my-custom-chart
97+
```
98+
99+
The above command will create a `my-custom-chart-0.1.0.tgz` file.
100+
101+
## Uploading a custom chart
102+
103+
> A custom chart can only be uploaded by a super admin.
104+
105+
* On the Devtron dashboard, select **Global Configurations > Custom charts**.
106+
* Select **Import Chart**.
107+
* Choose **Select tar.gz file...** and upload the [packaged custom chart](#3-package-the-custom-chart-in-the-tgz-format) in the `*.tgz` format.
108+
109+
![Selecting custom chart](https://devtron-public-asset.s3.us-east-2.amazonaws.com/custom-charts/Chart+pre-requisites.png)
110+
111+
The chart is being uploaded and validated. You may also **Cancel upload** if required.
112+
113+
![Uploading custom chart](https://devtron-public-asset.s3.us-east-2.amazonaws.com/custom-charts/List+-+Empty-4.png)
114+
115+
### Validation
116+
117+
The uploaded archive will be validated against:
118+
119+
- Supported archive template should be in `*.tgz` format.
120+
- `Chart.yaml` must include the name and the version number.
121+
- `image_descriptor_template.json` file should be present and the field format must match the format listed in the [image builder template](#step-2-create-the-image-builder-template-file) section.
122+
123+
The following are the validation results:
124+
125+
| Validation status | Description | User action |
126+
| :--- | :--- | :--- |
127+
| **Success** | The files uploaded are validated. | Enter a description for the chart and select **Save** or **Cancel upload**. |
128+
| **Unsupported template** | The archive file do not match the [required template](#prerequisites). | **Upload another chart** or **Cancel upload**. |
129+
| **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**. |
130+
| **Already exists** | There already exists a chart with the same version. | <ul><li>Edit the version and re-upload the same chart using **Upload another chart**.</li><li>Upload a new chart with a new name using **Upload another chart**.</li><li>**Cancel upload**.</li></ul> |
131+
132+
![Chart validated](./images/uploading-chart/List%20-%20Empty-2.png)
133+
134+
![Unsupported template](./images/uploading-chart/List%20-%20Empty.png)
135+
136+
![New version detected](./images/uploading-chart/List%20-%20Empty-3.png)
137+
138+
![Already exists](./images/uploading-chart/List%20-%20Empty-1.png)
139+
140+
## View the custom charts
141+
142+
> All users can view the custom charts.
143+
144+
To view a list of available custom charts, go to **Global Configurations > Custom charts** page.
145+
146+
* The charts can be searched with their name, version, or description.
147+
* New [custom charts can be uploaded](#uploading-a-custom-chart) by selecting **Upload chart**.
148+
149+
![Custom charts](./images/uploading-chart/custom-charts-lists.png)
150+
151+
## Use the custom chart in an application
152+
153+
The custom charts can be used from the [Deployment Template](../creating-application/deployment-template.md) section.
154+
155+
> **Info**:
156+
>
157+
> 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).

0 commit comments

Comments
 (0)