Helm-Toolkit: update comments for endpoint lookup functions

This PS updates the comments for endpoint lookup functions

Change-Id: Ifdc96acaac6972c10f6a580eaf37629910a955a5
Signed-off-by: Pete Birley <pete@port.direct>

helm-toolkit/templates/endpoints/_authenticated_endpoint_uri_lookup.tpl

@@ -14,13 +14,34 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
-# This function helps resolve database style endpoints:
-#
-# Presuming that .Values contains an endpoint: definition for 'neutron-db' with the
-# appropriate attributes, a call such as:
-# { tuple "neutron-db" "internal" "userClass" "portName" . | include "helm-toolkit.endpoints.authenticated_endpoint_uri_lookup" }
-# where portName is optional if a default port has been defined in .Values
-# returns: mysql+pymysql://username:password@internal_host:3306/dbname
+{{/*
+abstract: |
+  Resolves database, or basic auth, style endpoints
+values: |
+  endpoints:
+    cluster_domain_suffix: cluster.local
+    oslo_db:
+      auth:
+        admin:
+          username: root
+          password: password
+        service_username:
+          username: username
+          password: password
+      hosts:
+        default: mariadb
+      host_fqdn_override:
+        default: null
+      path: /dbname
+      scheme: mysql+pymysql
+      port:
+        mysql:
+          default: 3306
+usage: |
+  {{ tuple "oslo_db" "internal" "service_username" "mysql" . | include "helm-toolkit.endpoints.authenticated_endpoint_uri_lookup" }}
+return: |
+  mysql+pymysql://serviceuser:password@mariadb.default.svc.cluster.local:3306/dbname
+*/}}
 
 {{- define "helm-toolkit.endpoints.authenticated_endpoint_uri_lookup" -}}
 {{- $type := index . 0 -}}

helm-toolkit/templates/endpoints/_endpoint_port_lookup.tpl

@@ -14,13 +14,21 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
-# This function returns hostnames from endpoint definitions for use cases
-# where the uri style return is not appropriate, and only the hostname
-# portion is used or relevant in the template:
-# { tuple "memcache" "internal" "portName" . | include "helm-toolkit.endpoints.endpoint_port_lookup" }
-# returns: internal_host:port
-#
-# Output that requires the port aspect striped could simply split the output based on ':'
+{{/*
+abstract: |
+  Resolves the port for an endpoint
+values: |
+  endpoints:
+    cluster_domain_suffix: cluster.local
+    oslo_db:
+      port:
+        mysql:
+          default: 3306
+usage: |
+  {{ tuple "oslo_db" "internal" "mysql" . | include "helm-toolkit.endpoints.endpoint_port_lookup" }}
+return: |
+  3306
+*/}}
 
 {{- define "helm-toolkit.endpoints.endpoint_port_lookup" -}}
 {{- $type := index . 0 -}}

helm-toolkit/templates/endpoints/_host_and_port_endpoint_uri_lookup.tpl

@@ -14,13 +14,25 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
-# This function returns hostnames from endpoint definitions for use cases
-# where the uri style return is not appropriate, and only the hostname
-# portion is used or relevant in the template:
-# { tuple "memcache" "internal" "portName" . | include "helm-toolkit.endpoints.host_and_port_endpoint_uri_lookup" }
-# returns: internal_host:port
-#
-# Output that requires the port aspect striped could simply split the output based on ':'
+{{/*
+abstract: |
+  Resolves 'hostname:port' for an endpoint
+values: |
+  endpoints:
+    cluster_domain_suffix: cluster.local
+    oslo_db:
+      hosts:
+        default: mariadb
+      host_fqdn_override:
+        default: null
+      port:
+        mysql:
+          default: 3306
+usage: |
+  {{ tuple "oslo_db" "internal" "mysql" . | include "helm-toolkit.endpoints.host_and_port_endpoint_uri_lookup" }}
+return: |
+  mariadb.default.svc.cluster.local:3306
+*/}}
 
 {{- define "helm-toolkit.endpoints.host_and_port_endpoint_uri_lookup" -}}
 {{- $type := index . 0 -}}

helm-toolkit/templates/endpoints/_hostname_fqdn_endpoint_lookup.tpl

@@ -14,11 +14,22 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
-# This function returns hostnames from endpoint definitions for use cases
-# where the uri style return is not appropriate, and only the hostname
-# portion is used or relevant in the template:
-# { tuple "memcache" "internal" . | include "helm-toolkit.endpoints.hostname_fqdn_endpoint_lookup" }
-# returns: internal_host_fqdn
+{{/*
+abstract: |
+  Resolves the fully qualified hostname for an endpoint
+values: |
+  endpoints:
+    cluster_domain_suffix: cluster.local
+    oslo_db:
+      hosts:
+        default: mariadb
+      host_fqdn_override:
+        default: null
+usage: |
+  {{ tuple "oslo_db" "internal" . | include "helm-toolkit.endpoints.hostname_fqdn_endpoint_lookup" }}
+return: |
+  mariadb.default.svc.cluster.local
+*/}}
 
 {{- define "helm-toolkit.endpoints.hostname_fqdn_endpoint_lookup" -}}
 {{- $type := index . 0 -}}

helm-toolkit/templates/endpoints/_hostname_namespaced_endpoint_lookup.tpl

@@ -14,11 +14,21 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
-# This function returns hostnames from endpoint definitions for use cases
-# where the uri style return is not appropriate, and only the hostname
-# portion is used or relevant in the template:
-# { tuple "memcache" "internal" . | include "helm-toolkit.endpoints.hostname_namespaced_endpoint_lookup" }
-# returns: internal_host_namespaced
+{{/*
+abstract: |
+  Resolves the namespace scoped hostname for an endpoint
+values: |
+  endpoints:
+    oslo_db:
+      hosts:
+        default: mariadb
+      host_fqdn_override:
+        default: null
+usage: |
+  {{ tuple "oslo_db" "internal" . | include "helm-toolkit.endpoints.hostname_namespaced_endpoint_lookup" }}
+return: |
+  mariadb.default
+*/}}
 
 {{- define "helm-toolkit.endpoints.hostname_namespaced_endpoint_lookup" -}}
 {{- $type := index . 0 -}}

helm-toolkit/templates/endpoints/_hostname_short_endpoint_lookup.tpl

@@ -14,11 +14,21 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
-# This function returns hostnames from endpoint definitions for use cases
-# where the uri style return is not appropriate, and only the short hostname or
-# kubernetes servicename is used or relevant in the template:
-# { tuple "memcache" "internal" . | include "helm-toolkit.endpoints.hostname_short_endpoint_lookup" }
-# returns: the short internal hostname, which will also match the service name
+{{/*
+abstract: |
+  Resolves the short hostname for an endpoint
+values: |
+  endpoints:
+    oslo_db:
+      hosts:
+        default: mariadb
+      host_fqdn_override:
+        default: null
+usage: |
+  {{ tuple "oslo_db" "internal" . | include "helm-toolkit.endpoints.hostname_short_endpoint_lookup" }}
+return: |
+  mariadb
+*/}}
 
 {{- define "helm-toolkit.endpoints.hostname_short_endpoint_lookup" -}}
 {{- $type := index . 0 -}}

helm-toolkit/templates/endpoints/_keystone_endpoint_name_lookup.tpl

@@ -14,10 +14,18 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
-# This function is used in endpoint management templates
-# it returns the service type for an openstack service eg:
-# { tuple orchestration . | include "keystone_endpoint_name_lookup" }
-# will return "heat"
+{{/*
+abstract: |
+  Resolves the service name for an service type
+values: |
+  endpoints:
+    identity:
+      name: keystone
+usage: |
+  {{ tuple identity . | include "keystone_endpoint_name_lookup" }}
+return: |
+  "keystone"
+*/}}
 
 {{- define "helm-toolkit.endpoints.keystone_endpoint_name_lookup" -}}
 {{- $type := index . 0 -}}

helm-toolkit/templates/endpoints/_keystone_endpoint_path_lookup.tpl

@@ -14,10 +14,26 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
-# This function returns the path for a service, it takes an tuple
-# input in the form: service-type, endpoint-class, port-name. eg:
-# { tuple "orchestration" "public" "api" . | include "helm-toolkit.endpoints.keystone_endpoint_path_lookup" }
-# will return the appropriate path.
+# FIXME(portdirect): it appears the port input here serves no purpose,
+# and should be removed. In addition this function is bugged, do we use it?
+
+{{/*
+abstract: |
+  Resolves the path for an endpoint
+values: |
+  endpoints:
+    cluster_domain_suffix: cluster.local
+    oslo_db:
+      path:
+       default: /dbname
+      port:
+        mysql:
+          default: 3306
+usage: |
+  {{ tuple "oslo_db" "internal" "mysql" . | include "helm-toolkit.endpoints.keystone_endpoint_path_lookup" }}
+return: |
+  /dbname
+*/}}
 
 {{- define "helm-toolkit.endpoints.keystone_endpoint_path_lookup" -}}
 {{- $type := index . 0 -}}

helm-toolkit/templates/endpoints/_keystone_endpoint_scheme_lookup.tpl

@@ -14,6 +14,28 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
+# FIXME(portdirect): it appears the port input here serves no purpose,
+# and should be removed. In addition this function is bugged, do we use it?
+
+{{/*
+abstract: |
+  Resolves the scheme for an endpoint
+values: |
+  endpoints:
+    cluster_domain_suffix: cluster.local
+    oslo_db:
+      scheme:
+        default:
+          mysql+pymysql
+      port:
+        mysql:
+          default: 3306
+usage: |
+  {{ tuple "oslo_db" "internal" "mysql" . | include "helm-toolkit.endpoints.keystone_endpoint_scheme_lookup" }}
+return: |
+  mysql+pymysql
+*/}}
+
 # This function returns the scheme for a service, it takes an tuple
 # input in the form: service-type, endpoint-class, port-name. eg:
 # { tuple "etcd" "internal" "client" . | include "helm-toolkit.endpoints.keystone_scheme_lookup" }

helm-toolkit/templates/endpoints/_keystone_endpoint_uri_lookup.tpl

@@ -14,10 +14,27 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
-# This function returns the endpoint uri for a service, it takes an tuple
-# input in the form: service-type, endpoint-class, port-name. eg:
-# { tuple "orchestration" "public" "api" . | include "helm-toolkit.endpoints.keystone_endpoint_uri_lookup" }
-# will return the appropriate URI.
+{{/*
+abstract: |
+  This function helps resolve uri style endpoints
+values: |
+  endpoints:
+    cluster_domain_suffix: cluster.local
+    oslo_db:
+      hosts:
+        default: mariadb
+      host_fqdn_override:
+        default: null
+      path: /dbname
+      scheme: mysql+pymysql
+      port:
+        mysql:
+          default: 3306
+usage: |
+  {{ tuple "oslo_db" "internal" "mysql" . | include "helm-toolkit.endpoints.keystone_endpoint_uri_lookup" }}
+return: |
+  mysql+pymysql://mariadb.default.svc.cluster.local:3306/dbname
+*/}}
 
 {{- define "helm-toolkit.endpoints.keystone_endpoint_uri_lookup" -}}
 {{- $type := index . 0 -}}

helm-toolkit/templates/endpoints/_service_name_endpoint_with_namespace_lookup.tpl

@@ -14,16 +14,32 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */}}
 
-# This function returns endpoint "<namespace>:<name>" pair from an endpoint
-# definition. This is used in kubernetes-entrypoint to support dependencies
-# between different services in different namespaces.
-# returns: the endpoint namespace and the service name, delimited by a colon
-#
-# Normally, the service name is constructed dynamically from the hostname
-# however when an ip address is used as the hostname, we default to
-# namespace:endpointCategoryName in order to construct a valid service name
-# however this can be overridden to a custom service name by defining
-# .service.name within the endpoint definition
+{{/*
+abstract: |
+  This function returns endpoint "<namespace>:<name>" pair from an endpoint
+  definition. This is used in kubernetes-entrypoint to support dependencies
+  between different services in different namespaces.
+  returns: the endpoint namespace and the service name, delimited by a colon
+
+  Normally, the service name is constructed dynamically from the hostname
+  however when an ip address is used as the hostname, we default to
+  namespace:endpointCategoryName in order to construct a valid service name
+  however this can be overridden to a custom service name by defining
+  .service.name within the endpoint definition
+values: |
+  endpoints:
+    cluster_domain_suffix: cluster.local
+    oslo_db:
+      namespace: foo
+      hosts:
+        default: mariadb
+      host_fqdn_override:
+        default: null
+usage: |
+  {{ tuple oslo_db internal . | include "helm-toolkit.endpoints.service_name_endpoint_with_namespace_lookup" }}
+return: |
+  foo:mariadb
+*/}}
 
 {{- define "helm-toolkit.endpoints.service_name_endpoint_with_namespace_lookup" -}}
 {{- $type := index . 0 -}}