QuickStart: Parameters (#1601)

* QuickStart: Parameters

Second part of the quickstart that walks through how to set parameters
with a flag or parameter set.

Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

* Review feedback

Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

* Fix grammar

Signed-off-by: Carolyn Van Slyck <me@carolynvanslyck.com>

docs/config.toml

@@ -46,13 +46,19 @@ pygmentsStyle = "friendly"
     name = "QuickStart"
     url = "/quickstart"
     identifier = "quickstart"
-    weight = 12
+    weight = 30
+    parent = "get-started"
+  [[menu.main]]
+    name = "QuickStart - Parameters"
+    url = "/quickstart/parameters"
+    identifier = "quickstart-parameters"
+    weight = 31
     parent = "get-started"
   [[menu.main]]
     name = "Examples"
     url = "/examples/"
     identifier = "examples"
-    weight = 13
+    weight = 50
     parent = "get-started"
 [[menu.main]]
   name = "Use Porter"

docs/content/quickstart/_index.md

@@ -156,6 +156,7 @@ porter uninstall porter-hello
 
 ## Next Steps 
 
-So in this quickstart, you learned how to use some of the features of the porter CLI to explain a bundle, install and manage its lifecycle.
+In this QuickStart, you learned how to use some of the features of the porter CLI to explain a bundle, install and manage its lifecycle.
 
-* [Learn more about use cases for bundles](https://porter.sh/learning/#the-devil-is-in-the-deployments-bundle-use-cases)
+* [Use parameters with a bundle](/quickstart/parameters/)
+* [Learn more about use cases for bundles](/learning/#the-devil-is-in-the-deployments-bundle-use-cases)

docs/content/quickstart/parameters.md

@@ -0,0 +1,158 @@
+---
+title: "QuickStart: Parameters"
+descriptions: Learn how to use a bundle with parameters
+layout: single
+---
+
+Now that you know how to install a bundle, let's look at how to specify parameters to customize how that bundle is installed.
+Bundle authors define parameters in bundles so that end-users can tweak how the bundle is configured at installation.
+A parameter can be a string, integer, boolean or even a json object.
+Some examples of how parameters can be used in a bundle are:
+
+* Log Level: Default the log level for an application to info. At any time a user can upgrade the bundle to change that parameter to a different value.
+* Deployment Region: Let the user specify which region, such as eastus-1, where the application should be deployed.
+* Helm Release Name: A bundle that uses Helm will often define a parameter that allows the user to set the release name for the Helm release.
+
+For optional parameters, bundles set a default value that is used when the user does not specify a value for the parameter.
+
+Let's look at a bundle with parameters:
+
+```console
+$ porter explain --reference getporter/hello-llama:v0.1.1
+Name: hello-llama
+Description: An example Porter bundle with parameters
+Version: 0.1.0
+Porter Version: v0.38.1-32-gb76f5c1c
+
+No credentials defined
+
+Parameters:
+Name   Description                           Type     Default   Required   Applies To
+name   Name of to whom we should say hello   string   llama     false      All Actions
+
+No outputs defined
+
+No custom actions defined
+
+No dependencies defined
+```
+
+In the Parameters section of the output returned by explain, there is a single optional string parameter, name, with a default of "llama" that applies to "All Actions".
+This means that the name parameter can be specified with every action that the bundle defines.
+In the custom actions section of the output returned by explain, there are no custom actions defined.
+The hello-llama bundle only supports the built-in actions of install, upgrade, and uninstall.
+
+## Specifying parameters
+
+Pass parameters to a bundle with the \--param flag, where the flag value is formatted as PARAM=VALUE.
+For example:
+
+```
+porter install --param name=Robin
+```
+
+When trying out a bundle, it might work well to set individual parameter values on the command line with the --param flag.
+Parameter sets store multiple parameters and pass them to a bundle using the parameter set name.
+With parameter sets you can avoid errors, and the requirement of remembering and manually configuring parameters at the command line.
+Parameter sets store the parameter name, and the source of the parameter value which could be a:
+
+* hard-coded value
+* environment variable
+* file
+* command
+* secret
+
+Some parameters may be sensitive, for example a database connection string or oauth token.
+For improved security, and to limit exposure of sensitive values, it is recommended that you source sensitive parameter values from a secret store such as HashiCorp Vault or Azure Key Vault.
+See the list of available [plugins](/plugins/) for which secret providers are supported.
+
+## Use the default parameter values
+
+Install the bundle without specifying any parameters so that you can see the default behavior of the bundle.
+
+```console
+$ porter install hello-llama --reference getporter/hello-llama:v0.1.1
+installing hello-llama...
+executing install action from hello-llama (installation: hello-llama)
+Hello, llama
+execution completed successfully!
+```
+
+The bundle printed "Hello, llama" using the default value for the name parameter.
+
+## Specify a parameter with a flag
+
+Next upgrade the installation and change the name parameter to another value using the \--param flag.
+
+```console
+$ porter upgrade hello-llama --param name=Michelle
+upgrading hello-llama...
+executing upgrade action from hello-llama (installation: hello-llama)
+Michelle 2.0
+execution completed successfully!
+```
+
+## Create a Parameter Set
+
+Create a parameter set for the hello-llama with the `porter parameters generate` command. It is an interactive command that walks through setting values for every parameter in the specified bundle.
+
+```console
+$ porter parameters generate hello-llama --reference getporter/hello-llama:v0.1.1
+Generating new parameter set hello-llama from bundle hello-llama
+==> 2 parameters declared for bundle hello-llama
+
+? How would you like to set parameter "name"
+   [Use arrows to move, space to select, type to filter]
+  secret
+> specific value
+  environment variable
+  file path
+  shell command
+
+? Enter the value that will be used to set parameter "name"
+  Porter
+```
+
+This creates a parameter set named hello-llama.
+View the parameter set with the `porter parameters show` command:
+
+```console
+$ porter parameters show hello-llama
+Name: hello-llama
+Created: 4 minutes ago
+Modified: 4 minutes ago
+
+-----------------------------------
+  Name  Local Source  Source Type
+-----------------------------------
+  name  Porter       value
+```
+
+The output shows that the parameter set has one parameter stored in it, the name parameter, and it will use the hard-coded value "Porter".
+
+## Specify a parameter with a Parameter Set
+
+Now re-run the upgrade command, this time specifying the name of the parameter set instead of individually specifying each parameter value with flags.
+Parameter sets are specified with the \--parameter-set or -p flag.
+
+```console
+$ porter upgrade hello-llama --parameter-set hello-llama
+upgrading hello-llama...
+executing upgrade action from hello-llama (installation: hello-llama)
+Porter 2.0
+execution completed successfully!
+```
+
+## Cleanup
+
+To clean up the resources installed from this QuickStart, use the `porter uninstall` command. 
+
+```
+porter uninstall hello-llama
+```
+
+## Next Steps 
+
+In this QuickStart, you learned how to see the parameters defined on a bundle, their default values, and customize the installation of a bundle by specifying alternate values.
+
+* [Understanding how parameters are resolved](/parameters)

workshop/hello-llama/helpers.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+install() {
+  echo Hello, $1
+}
+
+upgrade() {
+  echo $1 2.0
+}
+
+uninstall() {
+  echo Goodbye, $1
+}
+
+# Call the requested function and pass the arguments as-is
+"$@"

workshop/hello-llama/porter.yaml

@@ -1,33 +1,34 @@
-name: porter-hello-llama-bundle
-version: 0.1.0
-description: "An example Porter configuration with moar llamas"
+name: hello-llama
+version: 0.1.1
+description: "An example Porter bundle with parameters"
 registry: getporter
 
 mixins:
   - exec
 
 parameters:
 - name: name
+  description: Name of to whom we should say hello
   type: string
   default: llama
 
 install:
   - exec:
-      description: "Install Hello Llama"
-      command: bash
-      flags:
-        c: "echo Hello, {{ bundle.parameters.name }}"
+      command: ./helpers.sh
+      arguments:
+        - install
+        - "{{ bundle.parameters.name }}"
 
 upgrade:
   - exec:
-      description: "Llama 2.0"
-      command: bash
-      flags:
-        c: "echo {{ bundle.parameters.name }} 2.0"
+      command: ./helpers.sh
+      arguments:
+        - upgrade
+        - "{{ bundle.parameters.name }}"
 
 uninstall:
   - exec:
-      description: "Uninstall Hello Llama"
-      command: bash
-      flags:
-        c: "echo Goodbye, {{ bundle.parameters.name }}"
+      command: ./helpers.sh
+      arguments:
+        - uninstall
+        - "{{ bundle.parameters.name }}"