note on prefixing of resource names with release name (#4633)

* note on naming of resources

Signed-off-by: Ryan Dawson <ryan.dawson@alfresco.com>

* put whitespace back in

Signed-off-by: Ryan Dawson <ryan.dawson@alfresco.com>

* put whitespace back

Signed-off-by: Ryan Dawson <ryan.dawson@alfresco.com>

* put whitespace back

Signed-off-by: Ryan Dawson <ryan.dawson@alfresco.com>

* clarify template fullname

Signed-off-by: Ryan Dawson <ryan.dawson@alfresco.com>

* fix formatting problem by escaping underscore

Signed-off-by: ryandawsonuk <ryandawson@cantab.net>

* no need to change whitespace elsewhere in doc

Signed-off-by: ryandawsonuk <ryandawson@cantab.net>

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.