QuickStart: Parameters #1601

carolynvs · 2021-05-21T22:52:06Z

What does this change

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

What issue does it fix

N/A

Notes for the reviewer

Ideally there was be sub menus under quickstart but I'd rather get the content out first then work with @flynnduism to get our nav bar to do what we want.

Checklist

Unit Tests
Documentation
Schema (porter.yaml)

carolynvs · 2021-05-21T22:57:59Z

Just trying out the new netlify preview functionality

Browser metadata

Path:      /quickstart/parameters/
Browser:   Firefox 88.0 on Mac OS 10.15
Viewport:  1440 x 692 @2x
Language:  en-US
Cookies:   Enabled

View on BrowserStack

Open Deploy Preview · Mark as Resolved

docs/content/quickstart/parameters.md

iennae · 2021-05-22T23:20:03Z

docs/content/quickstart/parameters.md

+---
+
+Now that you know how to install a bundle, let's look at how to specify parameters to customize how that bundle is installed.
+Bundles can define parameters to allow the end-user to tweak how the bundle is configured.


Needs to be active here.

Bundle authors add parameters to bundles so that end-users can tweak how the bundle is configured at installation. An example of where this would be useful is supplying a username and password value for a database.

I am going to leave off the second sentence because a) those are most likely credentials and I don't want to confuse the issue of creds vs params just yet, and b) there are 3 examples of parameters in the next paragraph.

iennae · 2021-05-22T23:23:10Z

docs/content/quickstart/parameters.md

+* 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 often will 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.


To make the parameter optional, you must set a default value for the parameter within the bundle.

Q: is the parameter optional here? Or really just optional at being specified. Just think this doesn't feel exactly precise.

Just realized in the quickstart that the parameters are

namespace
wordpress-name
wordpress-password

and both namespace and wordpress-name are optional (required is set to false) and only wordpress-name has a default setting.

I'm a bit lost here and I think some of the confusion may being caused by the old/unused parameter field required. That isn't supported anymore to specifying if a parameter must be specified or not. If a default is set, then the parameter is optional and does not need to be specified by the user. If a default is not set, then the parameter is required. In a separate PR I will clean up any example porter.yaml files that are still using required: false or anything like that.

Does that help clear up this question? Or does the text still need to change?

Ahhhhhh! The output is confusing which is why I'm lost. so I think there is more nuance here and I'll need to chat to you more about it because optional feels like the wrong word

iennae · 2021-05-22T23:23:46Z

docs/content/quickstart/parameters.md

+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:
+


I'm wondering if starting this out looking at the same bundle that was used in the quickstart (getporter/wordpress:v0.1..3) would be useful here.

I decided to not use that bundle because it requires credentials, which we have not introduced yet, and a kubernetes cluster (more work for the reader that isn't relevant).

I used wordpress as an example earlier in the first quickstart because it is a bundle that has credentials, parameters, outputs and custom actions defined. That was useful because I was highlighting the output of porter explain, and if all the output said was "no credentials/parameters/outputs defined" then that wouldn't demonstrate the command very well. This is why later in the same quickstart I switched to the hello world bundle, so that we weren't using features that have not been explained yet.

iennae · 2021-05-22T23:28:56Z

docs/content/quickstart/parameters.md

+No dependencies defined
+```
+
+The output tells us that the bundle has one optional string parameter, name, which defaults to "llama".


I keep reading this example as llama as in llamar "to call" you call me ..

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".

Yup! that is the hidden joke. 😀

iennae · 2021-05-22T23:34:26Z

docs/content/quickstart/parameters.md

+```
+
+The output tells us that the bundle has one optional string parameter, name, which defaults to "llama".
+The name parameter applies to "All Actions" meaning that this parameter can be specified with every action that the bundle defines.


This means that the name parameter can be specified with each action that the bundle defines.

iennae · 2021-05-22T23:36:46Z

docs/content/quickstart/parameters.md

+
+The output tells us that the bundle has one optional string parameter, name, which defaults to "llama".
+The name parameter applies to "All Actions" meaning that this parameter can be specified with every action that the bundle defines.
+Since it says that no custom actions are defined, the bundle only supports the built-in actions of install, upgrade, and uninstall.


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.

iennae · 2021-05-22T23:37:39Z

docs/content/quickstart/parameters.md

+## Use the default parameter values
+
+
+First install the bundle and do not specify any parameters so that you can observe how the bundle installs without any customization.


Install the bundle without specifying any parameters so that you can see the default behavior of the bundle install.

iennae · 2021-05-22T23:42:03Z

docs/content/quickstart/parameters.md

+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.


Let's see the behavior when customizing the bundle with parameters. Upgrade the bundle and specify the name parameter.

iennae · 2021-05-22T23:42:40Z

docs/content/quickstart/parameters.md

+
+## Specify a parameter with a flag
+Next upgrade the installation and change the name parameter to another value.
+Parameters are specified with the \--param flag: 


This feels like it should be explained earlier before we start experimenting.

iennae · 2021-05-22T23:43:12Z

docs/content/quickstart/parameters.md

+Parameters are specified with the \--param flag: 
+
+```console
+$ porter upgrade hello-llama --param name=Porter


Maybe use a different name than Porter so it isn't confusing to new folks. (Michele?)

iennae · 2021-05-22T23:45:48Z

docs/content/quickstart/parameters.md

+```
+
+## Create a Parameter Set
+Setting a parameter value individually on the command line with the \--param flag works well when trying out a bundle.


While trying out a bundle, it might work well when you set individual parameter values on the command line with the --param flag.

iennae · 2021-05-22T23:47:57Z

docs/content/quickstart/parameters.md

+## Create a Parameter Set
+Setting a parameter value individually on the command line with the \--param flag works well when trying out a bundle.
+When working with a bundle often though, remembering and typing out every parameter values every time is error prone.
+Parameter Sets store a set of parameter values to use with a bundle.


To alleviate errors and the requirement of remembering and manually configuring parameters at the command line, you can store a set of parameter values to use with a bundle with a parameter set.

iennae · 2021-05-22T23:48:38Z

docs/content/quickstart/parameters.md

+Setting a parameter value individually on the command line with the \--param flag works well when trying out a bundle.
+When working with a bundle often though, remembering and typing out every parameter values every time is error prone.
+Parameter Sets store a set of parameter values to use with a bundle.
+Even more powerful, the value of the parameters can come from the following sources:


more powerful than what?

iennae · 2021-05-22T23:51:44Z

docs/content/quickstart/parameters.md

+* 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 those parameter values from a secret store such as Hashicorp Vault or Azure Key Vault.


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, Azure Key Vault or Google Secret Manager.

I can't mention google because no one has made a plugin for that yet.

AHHH. just cut the Google Secret Manager out and keep the "sensitive parameter values" (instead of those)

iennae · 2021-05-22T23:53:45Z

docs/content/quickstart/parameters.md

+? Enter the value that will be used to set parameter "name"
+  Porter
+```
+


What if I want to accept a default value for a particular parameter?

Can there only be one parameter set per bundle? What happens if I re-run generate?

What if I want to accept a default value for a particular parameter?

Let me make an issue for that (#1604). Right now the answer is manually edit the parameter set to remove the parameter mapping from the file.

Can there only be one parameter set per bundle? What happens if I re-run generate?

I have answers but I'm not sure if that level of detail belongs in the quickstart, which is a task focused document and isn't intended to be a complete reference of the topic. A better place to answer those questions is porter.sh/parameters I think. We already say in the command-line documentation for the --parameter-set flag that it can be used more than once.

Yes you can define multiple parameter sets and use them when installing a bundle.

Re-running generate, runs you through the same process as the first time. If you choose the same parameter set name the previous parameter set is overwritten.

Cool, wasn't saying that these things need to defined here but wondering if folks have more questions if they were answered somewhere.

carolynvs · 2021-05-24T15:46:38Z

@iennae Thanks for the thoughtful suggestions! I've updated it with your feedback.

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>

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

iennae

LGTM

carolynvs force-pushed the params-quickstart branch from 15da68d to 361fa87 Compare May 21, 2021 23:17

carolynvs marked this pull request as ready for review May 21, 2021 23:30

carolynvs force-pushed the params-quickstart branch from 7d9de7c to 61a91d9 Compare May 21, 2021 23:30

carolynvs requested review from jeremyrickard and vdice as code owners May 21, 2021 23:30

carolynvs requested a review from iennae May 21, 2021 23:30

iennae reviewed May 22, 2021

View reviewed changes

docs/content/quickstart/parameters.md Show resolved Hide resolved

iennae reviewed May 22, 2021

View reviewed changes

carolynvs added 3 commits May 24, 2021 13:37

QuickStart: Parameters

3c8bf81

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

eb599e1

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

Fix grammar

88a493c

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

carolynvs force-pushed the params-quickstart branch from 9a69550 to 88a493c Compare May 24, 2021 18:38

iennae approved these changes May 27, 2021

View reviewed changes

carolynvs merged commit 7f8906b into getporter:main May 27, 2021

carolynvs deleted the params-quickstart branch May 27, 2021 18:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

QuickStart: Parameters #1601

QuickStart: Parameters #1601

carolynvs commented May 21, 2021 •

edited

Loading

carolynvs commented May 21, 2021

iennae May 22, 2021

carolynvs May 24, 2021

iennae May 22, 2021

iennae May 22, 2021

carolynvs May 24, 2021

iennae May 24, 2021

iennae May 22, 2021

carolynvs May 24, 2021

iennae May 22, 2021

iennae May 22, 2021

carolynvs May 24, 2021

iennae May 22, 2021

iennae May 22, 2021

iennae May 22, 2021

iennae May 22, 2021

iennae May 22, 2021

iennae May 22, 2021

iennae May 22, 2021

iennae May 22, 2021

iennae May 22, 2021

iennae May 22, 2021

carolynvs May 24, 2021

iennae May 24, 2021

iennae May 22, 2021

iennae May 22, 2021

carolynvs May 24, 2021 •

edited

Loading

carolynvs May 24, 2021

iennae May 24, 2021

carolynvs commented May 24, 2021

iennae left a comment

		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:

		## Use the default parameter values


		First install the bundle and do not specify any parameters so that you can observe how the bundle installs without any customization.

QuickStart: Parameters #1601

QuickStart: Parameters #1601

Conversation

carolynvs commented May 21, 2021 • edited Loading

What does this change

What issue does it fix

Notes for the reviewer

Checklist

carolynvs commented May 21, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carolynvs May 24, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carolynvs commented May 24, 2021

iennae left a comment

Choose a reason for hiding this comment

carolynvs commented May 21, 2021 •

edited

Loading

carolynvs May 24, 2021 •

edited

Loading