Merge pull request #9708 from jupierce/dev/jupierce/feature/template_feedback

Merged by openshift-bot

Author: OpenShift Bot

api/swagger-spec/oapi-v1.json

@@ -24900,23 +24900,27 @@
       "$ref": "v1.ObjectMeta",
       "description": "Standard object's metadata."
      },
+     "message": {
+      "type": "string",
+      "description": "message is an optional instructional message that will be displayed when this template is instantiated. This field should inform the user how to utilize the newly created resources. Parameter substitution will be performed on the message before being displayed so that generated credentials and other parameters can be included in the output."
+     },
      "objects": {
       "type": "array",
       "items": {
        "$ref": "runtime.RawExtension"
       },
-      "description": "Objects is an array of objects to include in this template. Required."
+      "description": "objects is an array of resources to include in this template."
      },
      "parameters": {
       "type": "array",
       "items": {
        "$ref": "v1.Parameter"
       },
-      "description": "Optional: Parameters is an array of Parameters used during the Template to Config transformation."
+      "description": "parameters is an optional array of Parameters used during the Template to Config transformation."
      },
      "labels": {
       "type": "object",
-      "description": "Labels is a set of labels that are applied to every object during the Template to Config transformation. Optional"
+      "description": "labels is a optional set of labels that are applied to every object during the Template to Config transformation."
      }
     }
    },

pkg/cmd/cli/describe/describer.go

@@ -870,6 +870,15 @@ type TemplateDescriber struct {
 	kctl.ObjectDescriber
 }
 
+// DescribeMessage prints the message that will be parameter substituted and displayed to the
+// user when this template is processed.
+func (d *TemplateDescriber) DescribeMessage(msg string, out *tabwriter.Writer) {
+	if len(msg) == 0 {
+		msg = "<none>"
+	}
+	formatString(out, "Message", msg)
+}
+
 // DescribeParameters prints out information about the parameters of a template
 func (d *TemplateDescriber) DescribeParameters(params []templateapi.Parameter, out *tabwriter.Writer) {
 	formatString(out, "Parameters", " ")
@@ -954,6 +963,8 @@ func (d *TemplateDescriber) DescribeTemplate(template *templateapi.Template) (st
 		out.Write([]byte("\n"))
 		formatString(out, "Object Labels", formatLabels(template.ObjectLabels))
 		out.Write([]byte("\n"))
+		d.DescribeMessage(template.Message, out)
+		out.Write([]byte("\n"))
 		out.Flush()
 		d.describeObjects(template.Objects, out)
 		return nil

pkg/template/api/deep_copy_generated.go

@@ -40,6 +40,7 @@ func DeepCopy_api_Template(in Template, out *Template, c *conversion.Cloner) err
 	if err := api.DeepCopy_api_ObjectMeta(in.ObjectMeta, &out.ObjectMeta, c); err != nil {
 		return err
 	}
+	out.Message = in.Message
 	if in.Parameters != nil {
 		in, out := in.Parameters, &out.Parameters
 		*out = make([]Parameter, len(in))

pkg/template/api/types.go

@@ -13,15 +13,23 @@ type Template struct {
 	unversioned.TypeMeta
 	kapi.ObjectMeta
 
-	// Optional: Parameters is an array of Parameters used during the
+	// message is an optional instructional message that will
+	// be displayed when this template is instantiated.
+	// This field should inform the user how to utilize the newly created resources.
+	// Parameter substitution will be performed on the message before being
+	// displayed so that generated credentials and other parameters can be
+	// included in the output.
+	Message string
+
+	// parameters is an optional array of Parameters used during the
 	// Template to Config transformation.
 	Parameters []Parameter
 
-	// Required: A list of resources to create
+	// objects is an array of resources to include in this template.
 	Objects []runtime.Object
 
-	// Optional: ObjectLabels is a set of labels that are applied to every
-	// object during the Template to Config transformation
+	// objectLabels is an optional set of labels that are applied to every
+	// object during the Template to Config transformation.
 	ObjectLabels map[string]string
 }
 

pkg/template/api/v1/deep_copy_generated.go

@@ -41,6 +41,7 @@ func DeepCopy_v1_Template(in Template, out *Template, c *conversion.Cloner) erro
 	if err := api_v1.DeepCopy_v1_ObjectMeta(in.ObjectMeta, &out.ObjectMeta, c); err != nil {
 		return err
 	}
+	out.Message = in.Message
 	if in.Objects != nil {
 		in, out := in.Objects, &out.Objects
 		*out = make([]runtime.RawExtension, len(in))

pkg/template/api/v1/swagger_doc.go

@@ -23,9 +23,10 @@ func (Parameter) SwaggerDoc() map[string]string {
 var map_Template = map[string]string{
 	"":           "Template contains the inputs needed to produce a Config.",
 	"metadata":   "Standard object's metadata.",
-	"objects":    "Objects is an array of objects to include in this template. Required.",
-	"parameters": "Optional: Parameters is an array of Parameters used during the Template to Config transformation.",
-	"labels":     "Labels is a set of labels that are applied to every object during the Template to Config transformation. Optional",
+	"message":    "message is an optional instructional message that will be displayed when this template is instantiated. This field should inform the user how to utilize the newly created resources. Parameter substitution will be performed on the message before being displayed so that generated credentials and other parameters can be included in the output.",
+	"objects":    "objects is an array of resources to include in this template.",
+	"parameters": "parameters is an optional array of Parameters used during the Template to Config transformation.",
+	"labels":     "labels is a optional set of labels that are applied to every object during the Template to Config transformation.",
 }
 
 func (Template) SwaggerDoc() map[string]string {

pkg/template/api/v1/types.go

@@ -14,15 +14,23 @@ type Template struct {
 	// Standard object's metadata.
 	kapi.ObjectMeta `json:"metadata,omitempty"`
 
-	// Objects is an array of objects to include in this template. Required.
+	// message is an optional instructional message that will
+	// be displayed when this template is instantiated.
+	// This field should inform the user how to utilize the newly created resources.
+	// Parameter substitution will be performed on the message before being
+	// displayed so that generated credentials and other parameters can be
+	// included in the output.
+	Message string `json:"message,omitempty"`
+
+	// objects is an array of resources to include in this template.
 	Objects []runtime.RawExtension `json:"objects"`
 
-	// Optional: Parameters is an array of Parameters used during the
+	// parameters is an optional array of Parameters used during the
 	// Template to Config transformation.
 	Parameters []Parameter `json:"parameters,omitempty"`
 
-	// Labels is a set of labels that are applied to every
-	// object during the Template to Config transformation. Optional
+	// labels is a optional set of labels that are applied to every
+	// object during the Template to Config transformation.
 	Labels map[string]string `json:"labels,omitempty"`
 }
 

pkg/template/template.go

@@ -38,6 +38,16 @@ func (p *Processor) Process(template *api.Template) field.ErrorList {
 		return append(templateErrors, fieldError)
 	}
 
+	// Place parameters into a map for efficient lookup
+	paramMap := make(map[string]api.Parameter)
+	for _, param := range template.Parameters {
+		paramMap[param.Name] = param
+	}
+
+	// Perform parameter substitution on the template's user message. This can be used to
+	// instruct a user on next steps for the template.
+	template.Message = p.EvaluateParameterSubstitution(paramMap, template.Message)
+
 	itemPath := field.NewPath("item")
 	for i, item := range template.Objects {
 		idxPath := itemPath.Index(i)
@@ -51,7 +61,7 @@ func (p *Processor) Process(template *api.Template) field.ErrorList {
 			item = decodedObj
 		}
 
-		newItem, err := p.SubstituteParameters(template.Parameters, item)
+		newItem, err := p.SubstituteParameters(paramMap, item)
 		if err != nil {
 			templateErrors = append(templateErrors, field.Invalid(idxPath.Child("parameters"), template.Parameters, err.Error()))
 		}
@@ -114,30 +124,29 @@ func GetParameterByName(t *api.Template, name string) *api.Parameter {
 	return nil
 }
 
+// EvaluateParameterSubstitution replaces escaped parameters in a string with values from the
+// provided map.
+func (p *Processor) EvaluateParameterSubstitution(params map[string]api.Parameter, in string) string {
+	for _, match := range parameterExp.FindAllStringSubmatch(in, -1) {
+		if len(match) > 1 {
+			if paramValue, found := params[match[1]]; found {
+				in = strings.Replace(in, match[0], paramValue.Value, 1)
+			}
+		}
+	}
+	return in
+}
+
 // SubstituteParameters loops over all values defined in structured
 // and unstructured types that are children of item.
 //
 // Example of Parameter expression:
 //   - ${PARAMETER_NAME}
 //
-func (p *Processor) SubstituteParameters(params []api.Parameter, item runtime.Object) (runtime.Object, error) {
-	// Make searching for given parameter name/value more effective
-	paramMap := make(map[string]string, len(params))
-	for _, param := range params {
-		paramMap[param.Name] = param.Value
-	}
-
+func (p *Processor) SubstituteParameters(params map[string]api.Parameter, item runtime.Object) (runtime.Object, error) {
 	stringreplace.VisitObjectStrings(item, func(in string) string {
-		for _, match := range parameterExp.FindAllStringSubmatch(in, -1) {
-			if len(match) > 1 {
-				if paramValue, found := paramMap[match[1]]; found {
-					in = strings.Replace(in, match[0], paramValue, 1)
-				}
-			}
-		}
-		return in
+		return p.EvaluateParameterSubstitution(params, in)
 	})
-
 	return item, nil
 }
 

test/templates/testdata/guestbook.json

@@ -8,6 +8,7 @@
       "description": "Example shows how to build a simple multi-tier application using Kubernetes and Docker"
     }
   },
+  "message": "Your admin credentials are ${ADMIN_USERNAME}:${ADMIN_PASSWORD}",
   "objects": [
     {
       "kind": "Route",

test/templates/testdata/guestbook_list.json

@@ -8,6 +8,7 @@
             "description": "Example shows how to build a simple multi-tier application using Kubernetes and Docker"
         }
     },
+    "message": "Your admin credentials are adminQ3H:dwNJiJwW",
     "objects": [
         {
             "apiVersion": "v1",
@@ -310,4 +311,4 @@
             "value": "1"
         }
     ]
-}
+}