From 7f8906befde8d9cd0e9a735bcc81e7b67127f17d Mon Sep 17 00:00:00 2001 From: Carolyn Van Slyck Date: Thu, 27 May 2021 13:55:49 -0500 Subject: [PATCH] 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 * Review feedback Signed-off-by: Carolyn Van Slyck * Fix grammar Signed-off-by: Carolyn Van Slyck --- docs/config.toml | 10 +- docs/content/quickstart/_index.md | 5 +- docs/content/quickstart/parameters.md | 158 ++++++++++++++++++++++++++ workshop/hello-llama/helpers.sh | 17 +++ workshop/hello-llama/porter.yaml | 31 ++--- 5 files changed, 202 insertions(+), 19 deletions(-) create mode 100644 docs/content/quickstart/parameters.md create mode 100755 workshop/hello-llama/helpers.sh diff --git a/docs/config.toml b/docs/config.toml index 14c2c1df3..9f496f3f6 100644 --- a/docs/config.toml +++ b/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" diff --git a/docs/content/quickstart/_index.md b/docs/content/quickstart/_index.md index cd3664342..6837b8d76 100644 --- a/docs/content/quickstart/_index.md +++ b/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) diff --git a/docs/content/quickstart/parameters.md b/docs/content/quickstart/parameters.md new file mode 100644 index 000000000..bec0ec65c --- /dev/null +++ b/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) diff --git a/workshop/hello-llama/helpers.sh b/workshop/hello-llama/helpers.sh new file mode 100755 index 000000000..74d84c2f7 --- /dev/null +++ b/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 +"$@" diff --git a/workshop/hello-llama/porter.yaml b/workshop/hello-llama/porter.yaml index 7415fb323..3af198758 100644 --- a/workshop/hello-llama/porter.yaml +++ b/workshop/hello-llama/porter.yaml @@ -1,6 +1,6 @@ -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: @@ -8,26 +8,27 @@ mixins: 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 }}" \ No newline at end of file + command: ./helpers.sh + arguments: + - uninstall + - "{{ bundle.parameters.name }}"