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.

Who can upload a custom chart - Super admins
Who can use the custom chart - All users

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

Prerequisites

A valid helm chart, which contains Chart.yaml file with name and version fields.
Image descriptor template file .image_descriptor_template.json.
Custom chart packaged in the *.tgz format.

1. How to create a helm chart

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

helm create my-custom-chart

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

Please see the following example:

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

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

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

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

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

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

For example:
To create a template file to allow Devtron to only render the repository name and the tag from the CI/CD pipeline that you created, edit the .image_descriptor_template.json file as:
{
    "image": {
          "repository": "{{.Name}}",
          "tag": "{{.Tag}}"
    }
}

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

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

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

helm package my-custom-chart

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

Uploading a Deployment Chart

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

On the Devtron dashboard, select Global Configurations > Custom charts.
Select Import Chart.
Select tar.gz file... and upload the packaged custom chart in the *.tgz format.

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

Validation

The uploaded archive will be validated against:

Supported archive template should be in *.tgz format.
Content of values.yaml should be there in app-values.yaml file.
release-values.yaml file is required.
ConfigMap/Secret template should be same as that of our reference chart.
Chart.yaml must include the name and the version number.
..image_descriptor_template.json file should be present and the field format must match the format listed in the image builder template section.

The following are the validation results:

Viewing Deployment Charts

All users can view the custom charts.

To view the list of available custom 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 by selecting Upload chart.

Using Deployment Chart in Application

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

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

Who Can Perform This Action?

Only superadmins can edit the GUI schema of deployment charts.

Reference

This section is an extension of 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.

You can edit the GUI schema of both the deployment charts:

Charts provided by Devtron (Deployment, Job & CronJob, Rollout Deployment, and StatefulSet)
Custom charts uploaded by you

Tutorial

Steps

In this example, we will edit the Deployment chart type provided by Devtron.

Click the edit button next to the chart as shown below.
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.
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.
While editing the schema, you may use the Preview GUI option for a real-time preview of your changes.
Click Save Changes.

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.