From 9b9cadd5cb73be2098a3d02948ca38c847c83ae1 Mon Sep 17 00:00:00 2001 From: Joshua Bezaleel Abednego Date: Wed, 7 Sep 2022 04:24:32 +0700 Subject: [PATCH] Recommend combination of create and apply commands instead of generate for docs (#2302) --- cmd/porter/credentials.go | 19 +++++---- cmd/porter/parameters.go | 12 +++--- .../content/best-practices/github-workflow.md | 4 +- docs/content/best-practices/kind.md | 29 +++++++++----- docs/content/blog/docker-mixin-blog-post.md | 26 ++++++++++++- docs/content/bundle/manifest/_index.md | 2 + docs/content/cli/credentials_create.md | 7 ++-- docs/content/cli/credentials_generate.md | 12 +++--- docs/content/cli/parameters_generate.md | 12 +++--- docs/content/credentials.md | 7 ++-- docs/content/parameters.md | 6 ++- docs/content/plugin-tutorial.md | 39 ++++++++++++------- docs/content/quickstart/credentials.md | 33 +++++++++------- docs/content/quickstart/parameters.md | 35 ++++++++++------- docs/content/slides/cnab-unpacked/index.md | 27 +++++++++---- .../credentials/create/credential-set.json | 2 +- .../parameters/create/parameter-set.json | 2 +- 17 files changed, 172 insertions(+), 102 deletions(-) diff --git a/cmd/porter/credentials.go b/cmd/porter/credentials.go index 797914560..0103d78bb 100644 --- a/cmd/porter/credentials.go +++ b/cmd/porter/credentials.go @@ -99,12 +99,12 @@ file system. When you wish to install, upgrade or delete a bundle, Porter will use the credential set to determine where to read the necessary information from and will then provide it to the bundle in the correct location. `, - Example: ` porter credential generate - porter credential generate kubecred --reference getporter/mysql:v0.1.4 --namespace test - porter credential generate kubekred --label owner=myname --reference getporter/mysql:v0.1.4 - porter credential generate kubecred --reference localhost:5000/getporter/mysql:v0.1.4 --insecure-registry --force - porter credential generate kubecred --file myapp/porter.yaml - porter credential generate kubecred --cnab-file myapp/bundle.json + Example: ` porter credentials generate + porter credentials generate kubecred --reference getporter/mysql:v0.1.4 --namespace test + porter credentials generate kubekred --label owner=myname --reference getporter/mysql:v0.1.4 + porter credentials generate kubecred --reference localhost:5000/getporter/mysql:v0.1.4 --insecure-registry --force + porter credentials generate kubecred --file myapp/porter.yaml + porter credentials generate kubecred --cnab-file myapp/bundle.json `, PreRunE: func(cmd *cobra.Command, args []string) error { return opts.Validate(cmd.Context(), args, p) @@ -228,10 +228,9 @@ func buildCredentialsCreateCommand(p *porter.Porter) *cobra.Command { Use: "create", Short: "Create a Credential", Long: "Create a new blank resource for the definition of a Credential Set.", - Example: ` - porter credentials create FILE [--output yaml|json] - porter credentials create credential-set.json - porter credentials create credential-set --output yaml`, + Example: ` porter credentials create FILE [--output yaml|json] + porter credentials create credential-set.json + porter credentials create credential-set --output yaml`, PreRunE: func(cmd *cobra.Command, args []string) error { return opts.Validate(args) }, diff --git a/cmd/porter/parameters.go b/cmd/porter/parameters.go index c6da70ffd..a98f0271e 100644 --- a/cmd/porter/parameters.go +++ b/cmd/porter/parameters.go @@ -99,12 +99,12 @@ file system. When you wish to install, upgrade or delete a bundle, Porter will use the parameter set to determine where to read the necessary information from and will then provide it to the bundle in the correct location. `, - Example: ` porter parameter generate - porter parameter generate myparamset --reference getporter/hello-llama:v0.1.1 --namespace dev - porter parameter generate myparamset --label owner=myname --reference getporter/hello-llama:v0.1.1 - porter parameter generate myparamset --reference localhost:5000/getporter/hello-llama:v0.1.1 --insecure-registry --force - porter parameter generate myparamset --file myapp/porter.yaml - porter parameter generate myparamset --cnab-file myapp/bundle.json + Example: ` porter parameters generate + porter parameters generate myparamset --reference getporter/hello-llama:v0.1.1 --namespace dev + porter parameters generate myparamset --label owner=myname --reference getporter/hello-llama:v0.1.1 + porter parameters generate myparamset --reference localhost:5000/getporter/hello-llama:v0.1.1 --insecure-registry --force + porter parameters generate myparamset --file myapp/porter.yaml + porter parameters generate myparamset --cnab-file myapp/bundle.json `, PreRunE: func(cmd *cobra.Command, args []string) error { return opts.Validate(cmd.Context(), args, p) diff --git a/docs/content/best-practices/github-workflow.md b/docs/content/best-practices/github-workflow.md index d2c68d953..c2c939890 100644 --- a/docs/content/best-practices/github-workflow.md +++ b/docs/content/best-practices/github-workflow.md @@ -91,9 +91,9 @@ If you are not the only one contributing to the repository and other contributor ### Use credential files -If you were using credentials in your bundle, you will need to set up a credential file in your repository to use with your workflow. For example, if you run `porter credentials generate mybun`, a JSON file named mybun.json is created. The resulting credential mapping (which does not contain any sensitive credentials) is located in ~/.porter/credentials/mybun.json. You need to add this file to your repository so you can pass in the file as the credential. This file should be located at the base directory, next to the porter.yaml. Then, to install your bundle with credentials in a file mybun.json, you would run the following: +If you were using credentials in your bundle, you will need to set up a credential file in your repository to use with your workflow. For example, if you run `porter credentials create mybun.json`, a JSON file named mybun.json is created. The resulting [credential set template file](/reference/file-formats/#credential-set) (which does not contain any sensitive credentials) is located in the current directory. You can run `porter credentials apply mybun.json` to apply the changes. If the specified credential set already exists, the changes will override the existing credential set, otherwise the apply command will create a new credential set. Then, to install your bundle with the newly created credential set, you would run the following: ```yaml -porter install -c ./mybun.json +porter install -c ``` ## Example Code diff --git a/docs/content/best-practices/kind.md b/docs/content/best-practices/kind.md index ff52f32be..d35a9dec5 100644 --- a/docs/content/best-practices/kind.md +++ b/docs/content/best-practices/kind.md @@ -55,17 +55,28 @@ To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'. Porter bundles that access a Kubernetes cluster when running can now be installed as normal, once the [Credential Set](../credentials) is generated/edited to use the KinD kubeconfig. -Here we'll generate credentials and install the [MySQL bundle](/src/build/testdata/bundles/mysql): +Here we'll create and edit credentials and then install the [MySQL bundle](/src/build/testdata/bundles/mysql): ```console - $ porter credentials generate -Generating new credential mysql from bundle mysql -==> 1 credentials required for bundle mysql -? How would you like to set credential "kubeconfig" - file path -? Enter the path that will be used to set credential "kubeconfig" - /Users/vdice/.kubes/kind/kubeconfig - + $ porter credentials create mysql.json +creating porter credential set in the current directory + $ cat mysql.json +# modify mysql.json with your editor to the content below +{ + "schemaType": "CredentialSet", + "schemaVersion": "1.0.1", + "name": "mysql", + "credentials": [ + { + "name": "kubeconfig", + "source": { + "path": "/Users/vdice/.kubes/kind/kubeconfig" + } + } + ] +} + $ porter cdredentials apply mysql.json +Applied /mysql credential set $ porter install -c mysql installing mysql... executing install action from mysql (bundle instance: mysql) diff --git a/docs/content/blog/docker-mixin-blog-post.md b/docs/content/blog/docker-mixin-blog-post.md index ec52a12e0..c8154362c 100644 --- a/docs/content/blog/docker-mixin-blog-post.md +++ b/docs/content/blog/docker-mixin-blog-post.md @@ -139,9 +139,31 @@ credentials: - name: DOCKER_PASSWORD env: DOCKER_PASSWORD ``` -Next, run the following line and select environment variable for where the credentials will come from. +Next, run the following commands and edit the file with where the credentials will come from. ```console -$ porter credentials generate docker +$ porter credentials create docker.json +$ cat docker.json +# modify docker.json with your editor to the content below +{ + "schemaType": "CredentialSet", + "schemaVersion": "1.0.1", + "name": "docker", + "credentials": [ + { + "name": "DOCKER_USERNAME", + "source": { + "env": "DOCKER_USERNAME" + } + }, + { + "name": "DOCKER_PASSWORD", + "source": { + "env": "DOCKER_PASSWORD" + } + } + ] +} +$ porter credentials apply docker.json ``` Your credentials are now set up. When you run install or upgrade or uninstall, you need to pass in your credentials using the `-c` or `--credential-set` flag. diff --git a/docs/content/bundle/manifest/_index.md b/docs/content/bundle/manifest/_index.md index 579ffa3dd..5a9236520 100644 --- a/docs/content/bundle/manifest/_index.md +++ b/docs/content/bundle/manifest/_index.md @@ -329,6 +329,8 @@ credentials: ### See Also * [porter credentials generate](/cli/porter_credentials_generate/) +* [porter credentials create](/cli/porter_credentials_create/) +* [porter credentials apply](/cli/porter_credentials_apply/) * [How Credentials Work](/how-credentials-work/) * [Wiring Credentials](/wiring/) diff --git a/docs/content/cli/credentials_create.md b/docs/content/cli/credentials_create.md index 760223543..76f4fb09c 100644 --- a/docs/content/cli/credentials_create.md +++ b/docs/content/cli/credentials_create.md @@ -18,10 +18,9 @@ porter credentials create [flags] ### Examples ``` - - porter credentials create FILE [--output yaml|json] - porter credentials create credential-set.json - porter credentials create credential-set --output yaml + porter credentials create FILE [--output yaml|json] + porter credentials create credential-set.json + porter credentials create credential-set --output yaml ``` ### Options diff --git a/docs/content/cli/credentials_generate.md b/docs/content/cli/credentials_generate.md index 2c8c6385f..2b416e227 100644 --- a/docs/content/cli/credentials_generate.md +++ b/docs/content/cli/credentials_generate.md @@ -34,12 +34,12 @@ porter credentials generate [NAME] [flags] ### Examples ``` - porter credential generate - porter credential generate kubecred --reference getporter/mysql:v0.1.4 --namespace test - porter credential generate kubekred --label owner=myname --reference getporter/mysql:v0.1.4 - porter credential generate kubecred --reference localhost:5000/getporter/mysql:v0.1.4 --insecure-registry --force - porter credential generate kubecred --file myapp/porter.yaml - porter credential generate kubecred --cnab-file myapp/bundle.json + porter credentials generate + porter credentials generate kubecred --reference getporter/mysql:v0.1.4 --namespace test + porter credentials generate kubekred --label owner=myname --reference getporter/mysql:v0.1.4 + porter credentials generate kubecred --reference localhost:5000/getporter/mysql:v0.1.4 --insecure-registry --force + porter credentials generate kubecred --file myapp/porter.yaml + porter credentials generate kubecred --cnab-file myapp/bundle.json ``` diff --git a/docs/content/cli/parameters_generate.md b/docs/content/cli/parameters_generate.md index f2ff42f61..58f89496a 100644 --- a/docs/content/cli/parameters_generate.md +++ b/docs/content/cli/parameters_generate.md @@ -34,12 +34,12 @@ porter parameters generate [NAME] [flags] ### Examples ``` - porter parameter generate - porter parameter generate myparamset --reference getporter/hello-llama:v0.1.1 --namespace dev - porter parameter generate myparamset --label owner=myname --reference getporter/hello-llama:v0.1.1 - porter parameter generate myparamset --reference localhost:5000/getporter/hello-llama:v0.1.1 --insecure-registry --force - porter parameter generate myparamset --file myapp/porter.yaml - porter parameter generate myparamset --cnab-file myapp/bundle.json + porter parameters generate + porter parameters generate myparamset --reference getporter/hello-llama:v0.1.1 --namespace dev + porter parameters generate myparamset --label owner=myname --reference getporter/hello-llama:v0.1.1 + porter parameters generate myparamset --reference localhost:5000/getporter/hello-llama:v0.1.1 --insecure-registry --force + porter parameters generate myparamset --file myapp/porter.yaml + porter parameters generate myparamset --cnab-file myapp/bundle.json ``` diff --git a/docs/content/credentials.md b/docs/content/credentials.md index 348302321..c47c245ee 100644 --- a/docs/content/credentials.md +++ b/docs/content/credentials.md @@ -32,8 +32,8 @@ that is the responsibility of credential sets. ## Credential Sets -Before running a bundle the user must first create a credential set using -[porter credentials generate][generate]. A credentials set is a mapping that tells porter +Before running a bundle the user must first create a credential set using two commands, +[porter credentials create][create]and [porter credentials apply][apply]. A credentials set is a mapping that tells porter "given a name of a credential such as `github_token`, where can the value be found?". Credential values can be resolved from many places, such as environment variables or local files, or if you are using a [secrets @@ -83,7 +83,8 @@ after the production environment, or in a file under /tmp, or in their team’s key vault. This is why the author of the bundle can’t guess and put it in porter.yaml up front. -[generate]: /cli/porter_credentials_generate/ +[create]: /cli/porter_credentials_create/ +[apply]: /cli/porter_credentials_apply/ ## Related diff --git a/docs/content/parameters.md b/docs/content/parameters.md index c5ba6051d..9f937db95 100644 --- a/docs/content/parameters.md +++ b/docs/content/parameters.md @@ -29,7 +29,8 @@ can have a secret source (`secret`). See the [secrets plugin docs](/plugins/types/#secrets) to learn how to configure Porter to use an external secret store. -Parameter Sets are created using [porter parameters generate][generate]. +Parameter Sets are created using the combination of [porter parameters create][create] +and [porter parameters apply][apply]. Afterwards a parameter set can be [edited][edit] if changes are required. See [porter parameters help](/cli/porter_parameters/) for all available commands. @@ -72,7 +73,8 @@ the [Author Bundles](/author-bundles#parameters/) doc for more info. See the helpful explanation in the [credentials](/credentials/) doc, which applies to parameter sources as well. -[generate]: /cli/porter_parameters_generate/ +[create]: /cli/porter_parameters_create/ +[apply]: /cli/porter_parameters_apply/ [edit]: /cli/porter_parameters_edit/ ## Related diff --git a/docs/content/plugin-tutorial.md b/docs/content/plugin-tutorial.md index 1f11d7515..88d8c73e7 100644 --- a/docs/content/plugin-tutorial.md +++ b/docs/content/plugin-tutorial.md @@ -230,24 +230,35 @@ Name Description password Password for installing the world. We recommend getting this from a secret store. true ``` -Since the bundle needs a credential we will generate some for it using `porter -credentials generate`. When prompted, select **secret** for how you like to set -the credential "password" and type `password` for the secret that will be used -to set the credential "password". +Since the bundle needs a credential, let's generate it using `porter credentials` command. +First, run `porter credentials create ` to generate the template file. +Then, edit the file to include required credentials and set the source for its value. +Lastly, run `porter credentials apply ` to generate the credential set. ```console -$ porter credentials generate --reference ghcr.io/getporter/examples/plugins-tutorial:v0.2.0 -Generating new credential plugins-tutorial from bundle plugins-tutorial -==> 1 credentials required for bundle plugins-tutorial -? How would you like to set credential "password" [Use arrows to move, space to select, type to filter] -> secret - specific value - environment variable - file path - shell command -? Enter the secret that will be used to set credential "password" password +$ porter credentials create plugins-tutorial.json +creating porter credential set in the current directory +$ cat plugins-tutorial.json +# modify plugins-tutorial.json with your editor to the content below +{ + "schemaType": "CredentialSet", + "schemaVersion": "1.0.1", + "name": "plugins-tutorial", + "credentials": [ + { + "name": "password", + "source": { + "secret": "password" + } + } + ] +} +$ porter credentials apply plugins-tutorial.json +Applied /plugins-tutorial credential set ``` +For more information on how to use `porter credentials` commands, take a look at our [credentials quickstart guide](/quickstart/credentials). + Now we are ready to install the bundle and pass it our generated credentials. 🎉 Porter is using the Azure plugin to inject the password credential from Azure Key Vault into the bundle during install. diff --git a/docs/content/quickstart/credentials.md b/docs/content/quickstart/credentials.md index b8fb69710..8bb0a29c7 100644 --- a/docs/content/quickstart/credentials.md +++ b/docs/content/quickstart/credentials.md @@ -52,21 +52,28 @@ This means that the github-token credential is required to run porter install or ## Create a Credential Set -Create a credential set for the credentials-tutorial bundle with the `porter credentials generate` command. It is an interactive command that walks through setting values for every credential in the specified bundle. +Create a credential set for the credentials-tutorial bundle with the combination of `porter credentials create` and `porter credentials apply` command. Edit the generated file to contain the required credentials for the corresponding bundle. In this case, it is the `github-token` that uses `GITHUB_TOKEN` environment variable as its source. Then, run the `porter credentials apply` command to create the new credential set from the modified file. ```console -$ porter credentials generate github --reference ghcr.io/getporter/examples/credentials-tutorial:v0.3.0 -Generating new credential github from bundle credentials-tutorial -==> 1 credentials required for bundle credentials-tutorial -? How would you like to set credential "github-token" - [Use arrows to move, space to select, type to filter] - secret - specific value -> environment variable - file path - shell command -? Enter the environment variable that will be used to set credential "github-token" - GITHUB_TOKEN +$ porter credentials create github.json +creating porter credential set in the current directory +$ cat github.json +# modify github.json with your editor to the content below +{ + "schemaType": "CredentialSet", + "schemaVersion": "1.0.1", + "name": "github", + "credentials": [ + { + "name": "github-token", + "source": { + "env": "GITHUB_TOKEN" + } + } + ] +} +$ porter credentials apply github.json +Applied /github credential set ``` This creates a credential set named github. diff --git a/docs/content/quickstart/parameters.md b/docs/content/quickstart/parameters.md index 2071f025d..d6597ed79 100644 --- a/docs/content/quickstart/parameters.md +++ b/docs/content/quickstart/parameters.md @@ -90,23 +90,28 @@ 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. +Create a parameter set for the hello-llama with the combination of `porter parameters create` and `porter parameters apply` commands. The `create` command will generate a [template file](/reference/file-formats#parameter-set). You need to edit the file to include the corresponding parameters needed for the bundle. After modifying the file, the `apply` command will create the parameter set based on the file. ```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 +$ porter parameters create hello-llama.json +creating porter parameter set in the current directory +$ cat hello-llama.json +# modify hello-llama.json with your editor to the content below +{ + "schemaType": "ParameterSet", + "schemaVersion": "1.0.1", + "name": "hello-llama", + "parameters": [ + { + "name": "name", + "source": { + "value": "Porter" + } + } + ] +} +$ porter parameters apply hello-llama.json +Applied /hello-llama parameter se ``` This creates a parameter set named hello-llama. diff --git a/docs/content/slides/cnab-unpacked/index.md b/docs/content/slides/cnab-unpacked/index.md index 38009aaa9..1ea7182ed 100644 --- a/docs/content/slides/cnab-unpacked/index.md +++ b/docs/content/slides/cnab-unpacked/index.md @@ -140,14 +140,25 @@ Parameters # Get Set... ``` -$ porter credentials generate -t deislabs/tron:v1.0 - -Generating new credential azure from bundle tron -==> 1 credentials required for bundle tron -? How would you like to set credential "kubeconfig" file path -? Enter the path that will be used to set credential "kubeconfig" - -Saving credential to /Users/carolynvs/.porter/credentials/azure.yaml +$ porter credentials create azure-tron.json +creating porter credential set in the current directory +$ cat azure-tron.json +# modify azure-tron.json with your editor to the content below +{ + "schemaType": "CredentialSet", + "schemaVersion": "1.0.1", + "name": "azure", + "credentials": [ + { + "name": "kubeconfig", + "source": { + "path": "/path/to/credential-path-file.txt" + } + }, + ] +} +$ porter credentials apply azure-tron.json +Applied /azure credential set ``` # Go! diff --git a/pkg/templates/templates/credentials/create/credential-set.json b/pkg/templates/templates/credentials/create/credential-set.json index d84f75d0a..94b47e2d6 100644 --- a/pkg/templates/templates/credentials/create/credential-set.json +++ b/pkg/templates/templates/credentials/create/credential-set.json @@ -22,7 +22,7 @@ { "name": "credential-env", "source": { - "ENV": "CREDENTIAL_ENV" + "env": "CREDENTIAL_ENV" } }, { diff --git a/pkg/templates/templates/parameters/create/parameter-set.json b/pkg/templates/templates/parameters/create/parameter-set.json index 78afadb13..ca3ef13c8 100644 --- a/pkg/templates/templates/parameters/create/parameter-set.json +++ b/pkg/templates/templates/parameters/create/parameter-set.json @@ -22,7 +22,7 @@ { "name": "parameter-env", "source": { - "ENV": "PARAMETER_ENV" + "env": "PARAMETER_ENV" } }, {