Contribute to Helm chart development

Adding new components and charts

When you need to add new components to the GitLab chart, always start by evaluating existing community or vendor charts. This is the recommended approach rather than building a new chart from scratch.

To add a new component the order of preference should be to:

1. Reuse an existing community or vendor chart.
2. Fork an existing community or vendor chart.
3. Add a new GitLab-owned chart and maintain it as dependency of GitLab chart.

Community or vendor charts

Community or vendor charts should be the preferred approach to add new components to GitLab chart.

When an existing chart can be used as is or with modifications that can be upstreamed, the chart can be added as a dependency to GitLab chart.

When a chart requires GitLab-specific functionality that upstream maintainers won’t accept, or when it includes features that shouldn’t be exposed to GitLab users, you can fork it to a separate repository, apply your patches, and integrate it into the GitLab chart - provided the license permits this approach.

Adding a new chart

If you must create a new chart, follow these guidelines. While you can deviate from these recommendations, please document your reasons and alternative approach.

Project setup

• Create a new project in the gitlab-org/cloud-native/charts group.
• Create the chart in its own separate repository following the default Helm project layout (initialised with helm create).
• Treat the chart as a dependency of GitLab chart.

Kubernetes compatibility

Only use Kubernetes APIs and features compatible with the Kubernetes versions currently supported by GitLab chart.

Integrate with GitLab chart

To integrate the new chart with GitLab chart make use of templates and (global) values:

1. Template overrides: Templates can be defined by the subchart and overridden by the parent chart. This allows to separate logic if the chart is used in standalone mode or if it’s used as part of the GitLab (parent) chart.

   Example: The GitLab chart overrides templates defined by the OpenBao chart to inject it’s database configuration.

2. (Global) values: Use and override (global) values to share information between two charts and define proper defaults in both the subcharts values file and the GitLab charts values.

   Example: The GitLab chart allows to specify a global API version for HPAs which can be consumed by all subcharts and dependency charts.

3. Template values: Values can contain templates and can be rendered by using tpl in the subchart. This has similar use cases like template overrides but allows additional flexibility if the same chart is imported twice by allowing to customize the template/value for each instance, while a regular template override impacts all chart instances.

   Example: The GitLab NGINX fork templates the external LoadBalancer IP from a value to allow different behavior in the default and the Geo NGINX instance.

Best practices

• Follow the style guide to ensure a consistent naming and value structure.

• Use Cloud Native GitLab images for all containers.

• Handle sensitive data, such as passwords or cryptographic keys using initContainers.

• Define a security context for all Pods and containers.

• Use the unittest plugin to test your manifests.

• Use standardized CI tasks to run common Helm jobs as part of your CI.

• Use a lightweight Kubernetes integration in CI to perform end to end testing in a live cluster.

• Avoid using Helm hooks if possible, as they are not available for helm template based workflows.

• Ingresses should consume GitLab chart’s:

  • host configuration,
  • certmanager configuration, and
  • global Ingress configuration

  to ensure a consistent TLS and domain configuration.

• Workloads should optionally support internal TLS.

Chart delivery

• Use semver versioning.
• Publish the new chart to charts.gitlab.io.
• The chart version bundled with GitLab chart should be managed by renovate.

Examples

A list of forked charts is available maintained in the architecture decisions.

Charts that are being maintained as a separate repository are GitLab Zoekt and OpenBao.