diff --git a/docs/chart_best_practices/templates.md b/docs/chart_best_practices/templates.md index 7b21c5fea..a3689a7dc 100644 --- a/docs/chart_best_practices/templates.md +++ b/docs/chart_best_practices/templates.md @@ -132,6 +132,43 @@ metadata: ``` +## Resource Naming in Templates + +Hard-coding the `name:` into a resource is usually considered to be bad practice. +Names should be unique to a release. So we might want to generate a name field +by inserting the release name - for example: + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: {{ .Release.Name }}-myservice +``` + +Or if there is only one resource of this kind then we could use .Release.Name or the template fullname function defined in \_helpers.tpl (which uses release name): + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: {{ template "fullname" . }} +``` + +However, there may be cases where it is known that there won't be naming conflicts from a fixed name. +In these cases a fixed name might make it easier for an application to find a resource such as a Service. +If the option for fixed names is needed then one way to manage this might be to make the setting of the name explicit by using a service.name value from the values.yaml if provided: + +```yaml +apiVersion: v1 +kind: Service +metadata: + {{- if .Values.service.name }} + name: {{ .Values.service.name }} + {{- else }} + name: {{ template "fullname" . }} + {{- end }} +``` + ## Comments (YAML Comments vs. Template Comments) Both YAML and Helm Templates have comment markers.