Helm Chart Development — Skill Instructions¶
Architecture¶
The ODA Canvas uses an umbrella chart pattern:
charts/canvas-oda/— Main umbrella chart, aggregates all sub-chartscharts/<sub-chart>/— Individual operator/service charts
Sub-charts are referenced as local dependencies in the umbrella Chart.yaml.
Chart.yaml Conventions¶
apiVersion: v2
name: <chart-name>
description: <one-line description>
type: application
version: <semver> # e.g., 1.2.5 or 1.2.5-LT5 (prerelease)
appVersion: "v1" # tracks CRD spec version
Version changelog: Maintain as comments in
Chart.yaml— each version with date and descriptionPrerelease suffix: Author initials (e.g.,
-LT5,-JS3). Clear for releases.
Dependency Management¶
Local Sub-Chart Dependencies¶
dependencies:
- name: cert-manager-init
version: "1.1.2"
repository: 'file://../cert-manager-init'
External Dependencies¶
- name: keycloak
version: "13.0.3"
repository: 'https://charts.bitnami.com/bitnami'
condition: keycloak.enabled
Always use condition: for optional dependencies so they can be toggled in values.yaml.
Updating Dependencies¶
cd charts/canvas-oda
helm dependency update
Sub-Chart Directory Structure¶
charts/<chart-name>/
Chart.yaml
values.yaml
templates/
deployment.yaml
rbac.yaml # ServiceAccount + ClusterRole + ClusterRoleBinding
configMap.yaml # Environment variables
_helpers.tpl # Standard template helpers
values.yaml Patterns¶
Global Values (Umbrella Chart)¶
global:
image:
registry: "" # Docker registry prefix (include trailing /)
imagePullSecrets: []
certificate:
appName: "compcrdwebhook"
hookImages:
kubectl: bitnamilegacy/kubectl:latest
kubectlCurl: tmforumodacanvas/baseimage-kubectl-curl:1.30.5
Sub-Chart Toggles (Umbrella)¶
oda-crds:
enabled: true
canvas-namespaces:
enabled: true
component-operator:
compopImage: tmforumodacanvas/component-operator
compopVersion: "1.2.5"
compopPrereleaseSuffix: "" # Set to initials for prerelease
Operator values.yaml¶
compopImage: tmforumodacanvas/component-operator
compopVersion: "1.2.5"
compopPrereleaseSuffix: ""
monitoredNamespaces: "components"
_helpers.tpl Standard Patterns¶
Docker Image Construction¶
{{- define "<chart>.DockerImage" -}}
{{ include "docker.registry" . }}{{ .Values.image }}:{{ .Values.version }}
{{- if .Values.prereleaseSuffix -}}-{{ .Values.prereleaseSuffix }}{{- end -}}
{{- end }}
Image Pull Policy¶
{{- define "<chart>.ImagePullPolicy" -}}
{{- if .Values.prereleaseSuffix -}}Always{{- else -}}IfNotPresent{{- end -}}
{{- end }}
Docker Registry (Global)¶
{{- define "docker.registry" -}}
{{- if .Values.global -}}{{- if .Values.global.image -}}{{- if .Values.global.image.registry -}}
{{ .Values.global.image.registry }}
{{- end -}}{{- end -}}{{- end -}}
{{- end -}}
Namespace CLI Conversion¶
Convert comma-separated namespaces to KOPF CLI flags:
{{- define "<chart>.monitoredNamespacesCLIOpts" -}}
{{- $namespaces := splitList "," .Values.monitoredNamespaces -}}
{{- range $namespaces }} -n {{ . }}{{- end -}}
{{- end }}
Standard Labels¶
{{- define "<chart>.labels" -}}
helm.sh/chart: {{ include "<chart>.chart" . }}
{{ include "<chart>.selectorLabels" . }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}
Deployment Template¶
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "<chart>.fullname" . }}
namespace: {{ .Release.Namespace }} # NEVER hardcode
labels:
{{- include "<chart>.labels" . | nindent 4 }}
oda.tmforum.org/operator: "true" # operator charts only, see below
oda.tmforum.org/operatorName: <operator-name>
oda.tmforum.org/operatorId: TMFOP0xx
spec:
replicas: 1
selector:
matchLabels:
{{- include "<chart>.selectorLabels" . | nindent 6 }}
template:
spec:
serviceAccountName: {{ .Values.serviceAccountName }}
{{- with .Values.global.imagePullSecrets }}
imagePullSecrets:
{{- toYaml . | nindent 8 }}
{{- end }}
containers:
- name: {{ .Chart.Name }}
image: {{ include "<chart>.DockerImage" . }}
imagePullPolicy: {{ include "<chart>.ImagePullPolicy" . }}
envFrom:
- configMapRef:
name: {{ include "<chart>.fullname" . }}-config
Operator Discovery Labels¶
Canvas Portal v2 lists an operator on its Operators page when the operator’s Deployment carries these labels. Put them on the Deployment’s own metadata.labels. Don’t put them on the Pod template or the selector: spec.selector is immutable, so changing it breaks helm upgrade.
oda.tmforum.org/operator: "true": opts the Deployment in.oda.tmforum.org/operatorName: the operator name, used in the portal’s detail page URL. Use a fixed slug (letters, digits,-,_,.; max 63 characters), not a templated release name. Separate the words with-: the portal builds the card title from the slug by starting each word with a capital letter and writing known abbreviations such as API, APISIX and PDB in capitals, soapi-operator-kongbecomes “API Operator Kong”. Writeidentity-config-operator-keycloak, notidentityconfig-operator-keycloak, which would read “Identityconfig Operator Keycloak”.oda.tmforum.org/operatorId: the TMF operator ID (TMFOP001…TMFOP011), shown as a badge.Optional annotation
oda.tmforum.org/operatorContainer: names the operator container when the Deployment has several containers and none is named after the operator or the Deployment.
Use one Deployment per operator. On the label path the portal shows one card per Deployment. See canvas-portal-v2/README.md for the full contract.
RBAC Template¶
apiVersion: v1
kind: ServiceAccount
metadata:
name: {{ .Values.serviceAccountName }}
namespace: {{ .Release.Namespace }}
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: {{ include "<chart>.fullname" . }}
rules:
# KOPF peering
- apiGroups: [zalando.org]
resources: [clusterkopfpeerings, kopfpeerings]
verbs: [list, watch, patch, get]
# ODA resources
- apiGroups: [oda.tmforum.org]
resources: [components, components/status, exposedapis, exposedapis/status]
verbs: [list, watch, patch, get, create, update, delete]
# Core K8s
- apiGroups: [""]
resources: [pods, services, configmaps, events, namespaces]
verbs: [list, watch, get, create, update, delete]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: {{ include "<chart>.fullname" . }}
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: {{ include "<chart>.fullname" . }}
subjects:
- kind: ServiceAccount
name: {{ .Values.serviceAccountName }}
namespace: {{ .Release.Namespace }}
Versioning Workflow¶
During development: set
prereleaseSuffix: LT5(your initials + iteration)Docker images built as
<image>:<version>-<suffix>withimagePullPolicy: AlwaysFor release: clear
prereleaseSuffix: "", image usesIfNotPresentBump
versioninChart.yamlwith changelog comment
Validation¶
# Lint chart
helm lint charts/<chart-name>
# Dry-run install
helm install --dry-run --debug test charts/<chart-name>
# Template rendering
helm template test charts/<chart-name>
Do¶
Use
{{ .Release.Namespace }}— never hard-code namespacesInclude version changelog comments in
Chart.yamlUse
condition:for optional umbrella dependenciesConstruct Docker images via
_helpers.tplhelper templatesUse
global.imagePullSecretsfor registry authenticationFollow standard labels (
helm.sh/chart,app.kubernetes.io/*)
Don’t¶
Don’t edit umbrella
Chart.yamldependencies without runninghelm dependency updateDon’t use
latesttags for operator imagesDon’t hard-code Docker registry paths — use
global.image.registryDon’t forget RBAC — KOPF needs cluster-wide permissions for peering
Don’t add prerelease suffixes in PRs to main