Helm & Kubernetes conventions

The idea of this issue is to describe some naming conventions that we will use through the Helm setup to ensure consistency. Eventually, this should also be added to the documentation for developers.

General Helm Guidelines:

Follow the following directory structure per chart:

my-chart/
├── charts/                # Directory for dependent subcharts
├── templates/             # YAML templates for Kubernetes resources
│   ├── _helpers.tpl       # Helper templates (e.g., for names, labels)
│   ├── subcomponent1/     # Additional resources for a subcomponent (optional)
│   ├── subcomponent2/     
│   ├── deployment.yaml    # Deployment manifest (optional)
│   ├── service.yaml       # Service manifest (optional)
│   └── ingress.yaml       # Ingress manifest (optional)
├── Chart.yaml             # Chart metadata (name, version, etc.)
├── values.yaml            # Default configuration values
├── values.schema.json     # JSON schema for validating values (optional)
├── README.md              # Documentation

General Guidelines for Naming:

  • Use lowercase letters
  • Use hyphens (-) for separators
  • Keep names descriptive but concise: Names should indicate the purpose of the resource without being excessively long.
  • Avoid special characters: Only use alphanumeric characters and hyphens.

1. Helm Charts

Chart Directory and File Names

  • Chart Directory: <name>/
    • Example: my-app/, cta
  • Values File: values.yaml (default values file)
  • Custom Values Files: <env>[-<resource>]-values.yaml
    • Example: dev-values.yaml, prod-values.yaml, ci-catalogue-oracle-values.yaml
  • Templates Directory: templates/

2. Resource templates

Each resource should reside in its own separate file. Do not define multiple resources in a single file.

Stick to simple names for the main different resource types:

  • Pod: pod.yaml
  • Deployment: deployment.yaml
  • Service: service.yaml
  • Ingress: ingress.yaml

If required, prefix the above with a descriptive name.

For the following resource types, use a descriptive name, followed by the shortname of the resource type:

  • ConfigMap: <name>-cm.yaml
  • Secret: <name>-secret.yaml
  • Job: <name>-job.yaml
  • CronJob: <name>-cronjob.yaml

In general, the templates/ directory should be split into separate components if relevant. For example, instead of:

templates/
├── postgres-pod.yaml
├── postgres-svc.yaml
├── oracle-pod.yaml

You should do:

my-chart/
├── postgres/
│   ├── pod.yaml
│   ├── service.yaml
├── oracle/
│   ├── pod.yaml

3. Resource Naming Patterns

Resource names themselves should simply have a short descriptive name. In the case of jobs, postfix the name with -job. This way it is clear during kubectl get pods when something is a job.

4. Helm Release Names

  • Naming Pattern: <app-name>-<env>
    • Example: myapp-dev, myapp-prod
Edited by Niels Alexander Buegel