Explain why we need credential sets (getporter#916)

* Explain why we need credential sets

Add explanation for why we can define credential sources in porter.yaml
from Slack to a new Q & A section on the Credentials page.

Rename the page to just "Credentials" to match how other pages are named
and update references to the page, adding a redirect for the old name.

Fix whitespace on inline <code> blocks so they don't wrap

* Incorporate feedback

docs/config.toml

@@ -340,8 +340,8 @@ defaultContentLanguage = "en"
  parent = "porter-architecture"
  [[menu.main]]
  name = "Credentials"
- url = "/how-credentials-work/"
- identifier = "how-credentials-work"
+ url = "/credentials/"
+ identifier = "credentials"
  weight = 405
  parent = "porter-architecture"
 

docs/content/author-bundles.md

@@ -173,7 +173,7 @@ parameters:
 Credentials are part of the [CNAB Spec](https://github.com/cnabio/cnab-spec/blob/master/802-credential-sets.md) and allow
 you to pass in sensitive data when you execute the bundle, such as passwords or configuration files. 
 
-Learn more about [how credentials work in Porter](/how-credentials-work/).
+Learn more about [how credentials work in Porter](/credentials/).
 
 By default, all credential values are considered sensitive and will be masked in console output.
 

docs/content/how-credentials-work.md → docs/content/credentials.md

@@ -1,6 +1,8 @@
 ---
-title: How credentials work
-description: How credentials work
+title: Credentials
+description: The lifecycle of a credential from definition, to resolution, and finally injection at runtime
+aliases:
+- /how-credentials-work/
 ---
 
 When you are authoring a bundle, you can define what credentials your bundle
@@ -32,3 +34,20 @@ before executing the step.
 Once the bundle finishes executing, the credentials are NOT recorded in the
 bundle instance (claim). Parameters are recorded there so that you can view them
 later using `porter instances show NAME --output json`.
+
+## Q & A
+
+### Why can't the credential source be defined in porter.yaml?
+
+The source of a credential is specific to each installation of the bundle. An
+author writes the bundle and defines what credentials are needed by the bundle
+and where each credential should be put, for example a certain environment
+variable.
+
+When a person installs that bundle only they know where that credential's value
+should be resolved from. Perhaps they put it in a environment variable named
+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/

docs/content/wiring.md

@@ -128,7 +128,7 @@ credentials:
 
 The same mechanism for declaring how to use a parameter can be used for credentials. To declare a credential usage, references are defined with the following syntax: `"{{ bundle.credentials.CREDENTIAL_NAME}}"`.
 
-When the bundle is executed, the Porter runtime will locate the parameter definition in the `porter.yaml` to determine where the parameter value has been stored. The Porter runtime will then rewrite the YAML block before it is passed to the mixin. To understand how credentials work, see [how credentials work][how-credentials-work] page.
+When the bundle is executed, the Porter runtime will locate the parameter definition in the `porter.yaml` to determine where the parameter value has been stored. The Porter runtime will then rewrite the YAML block before it is passed to the mixin. See [Credentials][credentials] to learn how credentials work.
 
 ## Outputs
 
@@ -327,4 +327,4 @@ install:
 ```
 
 [mixin-architecture]: /mixin-dev-guide/architecture/
-[how-credentials-work]: /how-credentials-work/
+[credentials]: /credentials/

docs/resources/_gen/assets/scss/sass/styles.scss_f300667da4f5b5f84e1a9e0702b2fdde.content

@@ -8214,7 +8214,8 @@ body {
  padding: 0.5em 0.5em;
  background-color: #e4f3f9;
  border: none;
- font-size: 1rem; }
+ font-size: 1rem;
+ white-space: nowrap; }
  .main .content-wrap.markdown ul,
  .main .content-wrap.markdown ol,
  .main .content-wrap ul,

docs/themes/porter/static/src/sass/docs-content.scss

@@ -198,6 +198,7 @@
  background-color: #e4f3f9;
  border: none;
  font-size: 1rem;
+ white-space: nowrap;
  }
 
  &.markdown ul,