Add documentation on how credentials work internally

docs/content/how-credentials-work.md

@@ -0,0 +1,14 @@
+---
+title: How credentials work
+description: How credentials work
+---
+
+When you are authoring a bundle, you can define what credentials your bundle requires such as a github token, cloud provider username/password, etc. Then in your action's steps you can reference the credentials using porter's template language `{{ bundle.credentials.github_token }}`.
+
+Credentials are injected when a bundle is executed (install/upgrade/uninstall/invoke). First a user creates a credentials set using `porter credentials generate`. This is a mapping that tells porter "given a name of a credential such as `github_token`, where can the value be found?", possible locations of a credential are: result of a command, environment value, file path, or hard coded value. The generate command walks you through all the credentials used by a bundle and where the values can be found.
+
+Now when you execute the bundle you can pass the credential set to the command use `--cred` or `-c` flag, e.g. `porter install --cred github`. Before the bundle is executed, porter users the credential set's mappings to retrieve the credential values and then inject them into the bundle's execution environment, e.g. the docker container, as environment variables.
+
+Inside the bundle's execution environment Porter looks for those environment variables that represent the credentials and replaces the template placeholders like `{{ bundle.credentials.github_token }}` with the actual credential value 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`.

docs/content/use-mixins.md

@@ -10,13 +10,11 @@ if you would like to add content for this page.
 
 # TODO
 
-* What is a mixin
-* Snippet of yaml
 * How to install and find mixins
 * Mixin Schema and autocomplete
 
 # Next
 
 * [Mixin Architecture](/mixin-dev-guide/architecture/)
 
-[contrib]: https://github.com/deislabs/porter/blob/master/CONTRIBUTING.md#documentation
+[contrib]: https://github.com/deislabs/porter/blob/master/CONTRIBUTING.md#documentation

docs/content/wiring.md

@@ -3,7 +3,7 @@ title: Parameters, Credentials, Outputs, and Images in Porter
 description: How to wire parameters, credentials and outputs into steps
 ---
 
-In the Porter manifest, you can declare both parameters and credentials. In addition to providing a mechanism for declaring parameters and credentials at the bundle level, Porter provides a way to declare how each of these are provided to [mixins](/mixin-architecture). This mechanism is also applicable to declaring how output from one mixin can be passed to another, as well as how to consume parameters, credentials and outputs from bundle dependencies. Finally, you can also use this technique to reference images defined in the `images` section of the manifest.
+In the Porter manifest, you can declare both parameters and credentials. In addition to providing a mechanism for declaring parameters and credentials at the bundle level, Porter provides a way to declare how each of these are provided to [mixins][mixin-architecture]. This mechanism is also applicable to declaring how output from one mixin can be passed to another, as well as how to consume parameters, credentials and outputs from bundle dependencies. Finally, you can also use this technique to reference images defined in the `images` section of the manifest.
 
 ## Parameters
 
@@ -99,7 +99,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.
+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.
 
 ## Outputs
 
@@ -296,3 +296,6 @@ install:
     set:
       jdbc_url: "jdbc:mysql://{{ bundle.outputs.mysql_host }}:{{ bundle.outputs.mysql_port }}/{{ bundle.parameters.database_name }}"
 ```
+
+[mixin-architecture]: /mixin-dev-guide/architecture/
+[how-credentials-work]: /how-credentials-work/