Recommend combination of create and apply commands instead of generat…

…e for docs (#2302)

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)
 		},

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)

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 <name-of-the-credential-set>
 ```
 
 ## Example Code

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)

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. 
 

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/)
 

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

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
 
 ```
 

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
 
 ```
 

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
 

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

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 <file-name>` 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 <file-name>` 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.

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.

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.