• Architecture
• Environment setup
• Style guide
• Writing and running tests
  • Developing RSpec tests
  • Running GitLab QA
  • ChaosKube
• Versioning and Release
• Changelog Entries
• When to fork upstream charts
  • No changes, no fork
  • Guidelines for forking
    • Sensitive information
    • Extending functionality
• Handling configuration deprecations
• Attempt to catch problematic configurations
• Verifying registry
• Troubleshooting a development environment
• Additional Helm information

Contribute to Helm chart development

Our contribution policies can be found in CONTRIBUTING.md

Contributing documentation changes to the charts requires only a text editor. Documentation is stored in the doc/ directory.

Architecture

Before starting development, it is helpful to review the goals, architecture, and design decisions for the charts.

See Architecture of GitLab Helm charts for this information.

Environment setup

See setting up your development environment to prepare your workstation for charts development.

Style guide

See the chart development style guide for guidelines and best practices for chart development.

Writing and running tests

We run several different types of tests to validate the charts work as intended.

Developing RSpec tests

Unit tests are written in RSpec and stored in the spec/ directory of the chart repository.

Read the notes on creating RSpec tests to validate the functionality of the chart.

Running GitLab QA

GitLab QA can be used to run integrations and functional tests against a deployed cloud-native GitLab installation.

Read more in the GitLab QA chart docs.

ChaosKube

ChaosKube can be used to test the fault tolerance of highly available cloud-native GitLab installations.

Read more in the ChaosKube chart docs.

Versioning and Release

Details on the version scheme, branching and tags can be found in release document.

Changelog Entries

All CHANGELOG.md entries should be created via the changelog entries workflow.

When to fork upstream charts

No changes, no fork

Let it be stated that any chart that does not require changes to function for our use should not be forked into this repository.

Guidelines for forking

Sensitive information

If a given chart expects that sensitive communication secrets will be presented from within environment, such as passwords or cryptographic keys, we prefer to use initContainers.

Extending functionality

There are some cases where it is needed to extend the functionality of a chart in such a way that an upstream may not accept.

Handling configuration deprecations

There are times in a development where changes in behavior require a functionally breaking change. We try to avoid such changes, but some items can not be handled without such a change.

To handle this, we have implemented the deprecations template. This template is designed to recognize properties that need to be replaced or relocated, and inform the user of the actions they need to take. This template will compile all messages into a list, and then cause the deployment to stop via a fail call. This provides a method to inform the user at the same time as preventing the deployment the chart in a broken or unexpected state.

See the documentation of the deprecations template for further information on the design, functionality, and how to add new deprecations.

Attempt to catch problematic configurations

Due to the complexity of these charts and their level of flexibility, there are some overlaps where it is possible to produce a configuration that would lead to an unpredictable, or entirely non-functional deployment. In an effort to prevent known problematic settings combinations, we have the following two patterns in place:

• We use schema validations for all our sub-charts to ensure the user-specified values meet expectations. See the documentation to learn more.
• We implement template logic designed to detect and warn the user that their configuration will not work. See the documentation of the checkConfig template for further information on the design and functionality, and how to add new configuration checks.

Verifying registry

In development mode, verifying Registry with Docker clients can be difficult. This is partly due to issues with certificate of the registry. You can either add the certificate or expose the registry over HTTP (see global.hosts.registry.https). Note that adding the certificate is more secure than the insecure registry solution.

Please keep in mind that Registry uses the external domain name of MinIO service (see global.hosts.minio.name). You may encounter an error when using internal domain names, e.g. with custom TLDs for development environment. The common symptom is that you can log in to the Registry but you can’t push or pull images. This is generally because the Registry container(s) can not resolve the MinIO domain name and find the correct endpoint (you can see the errors in container logs).

Troubleshooting a development environment

Developers may encounter unique issues while working on new chart features. Refer to the troubleshooting guide for information if your development cluster seems to have strange issues.

Additional Helm information

Some information on how all the inner Helm workings behave:

• The Distribution Team has a training presentation for Helm charts.
• Templating in Helm is done via golang’s text/template and sprig.
• Helm repository has some additional information on developing with Helm in its tips and tricks section.
• Functions and Pipelines.
• Subcharts and Globals.