Merge branch 'main' into release/v1

Signed-off-by: Carolyn Van Slyck <[email protected]>
getporter · Jun 30, 2021 · 90f2be8 · 90f2be8
2 parents 2b176ec + 5376282
commit 90f2be8
Show file tree

Hide file tree

Showing 22 changed files with 541 additions and 28 deletions.
diff --git a/README.md b/README.md
@@ -13,6 +13,37 @@ application.
 
 <p align="center">Learn all about Porter at <a href="https://porter.sh">porter.sh</a></p>
 
+# <a name="mixins"></a>Porter Mixins
+
+Mixins provide out-of-the-box support for interacting with different tools and services from inside a bundle. You can always create a mixin, or use the exec mixin and a Custom Dockerfile if a custom mixin doesn't exist yet.
+
+[Porter Mixins](https://porter.sh/mixins/) are available for below platform's:
+
+| Platform                                                                                                                                                                                                                        | Supported?  |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------: |
+| <img src="docs\static\images\mixins\docker_icon.png" width="20" height="20" vertical-align="middle" /> [Docker](https://porter.sh/mixins/docker/)                                            |     ✔️      |
+| <img src="docs\static\images\mixins\docker-compose.png" width="20" height="20" vertical-align="middle" /> [Docker-Compose](https://porter.sh/mixins/docker-compose/)            |     ✔️      |
+| <img src="docs\static\images\mixins\kubernetes.svg" width="20" height="20" vertical-align="middle" /> [Kubernetes](https://porter.sh/mixins/kubernetes/)            |     ✔️      |
+| <img src="docs\static\images\mixins\helm.svg" width="20" height="20" vertical-align="middle" /> [Helm](https://porter.sh/mixins/helm/)            |     ✔️      |
+| <img src="docs\static\images\mixins\gcp.png" width="20" height="20" vertical-align="middle" /> [GCloud](https://porter.sh/mixins/gcloud/)            |     ✔️      |
+| <img src="docs\static\images\mixins\terraform_icon.png" width="20" height="20" vertical-align="middle" /> [Terraform](https://porter.sh/mixins/terraform/)            |     ✔️      |
+| <img src="docs\static\images\mixins\aws.svg" width="20" height="20" vertical-align="middle" /> [aws](https://porter.sh/mixins/aws/)            |     ✔️      |
+| <img src="docs\static\images\plugins\azure.png" width="20" height="20" vertical-align="middle" /> [Azure](https://porter.sh/mixins/azure/)            |     ✔️      |
+| <img src="docs\static\images\mixins\exec.png" width="20" height="20" vertical-align="middle" /> [exec](https://porter.sh/mixins/exec/)            |     ✔️      |
+
+# <a name="Plugins"></a>Porter Plugins
+
+Plugins let you store Porter's data and retrieve secrets from an external service.
+
+[Porter Plugins](https://porter.sh/plugins/) are available for below platform's:
+
+| Platform                                                                                                                                                                                                                        | Supported?  |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------: |
+| <img src="docs\static\images\plugins\hashicorp.png" width="20" height="20" vertical-align="middle" /> [Hashicorp](https://porter.sh/plugins/hashicorp/)                                            |     ✔️      |
+| <img src="docs\static\images\plugins\azure.png" width="20" height="20" vertical-align="middle" /> [Azure](https://porter.sh/plugins/azure/)            |     ✔️      |
+| <img src="docs\static\images\mixins\kubernetes.svg" width="20" height="20" vertical-align="middle" /> [Kubernetes](https://porter.sh/plugins/kubernetes/)            |     ✔️      |
+
+
 # Contact
 
 * [Mailing List] - Great for following the project at a high level because it is

diff --git a/build/azure-pipelines.pr-automatic.yml b/build/azure-pipelines.pr-automatic.yml
@@ -18,6 +18,11 @@ parameters:
     type: boolean
     default: false
 
+parameters:
+  - name: buildExamples
+    type: boolean
+    default: false
+
 stages:
   - stage: Setup
     jobs:

diff --git a/docs/config.toml b/docs/config.toml
@@ -38,22 +38,28 @@ pygmentsStyle = "friendly"
   url = "#"
   [[menu.main]]
     name = "Install Porter"
-    url = "/install"
+    url = "/install/"
     identifier = "install"
     weight = 11
     parent = "get-started"
   [[menu.main]]
     name = "QuickStart"
-    url = "/quickstart"
+    url = "/quickstart/"
     identifier = "quickstart"
     weight = 30
     parent = "get-started"
   [[menu.main]]
     name = "QuickStart - Parameters"
-    url = "/quickstart/parameters"
+    url = "/quickstart/parameters/"
     identifier = "quickstart-parameters"
     weight = 31
     parent = "get-started"
+  [[menu.main]]
+    name = "QuickStart - Credentials"
+    url = "/quickstart/credentials/"
+    identifier = "quickstart-credentials"
+    weight = 32
+    parent = "get-started"
   [[menu.main]]
     name = "Examples"
     url = "/examples/"

diff --git a/docs/content/credentials.md b/docs/content/credentials.md
@@ -8,13 +8,31 @@ aliases:
 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 }}`.
+language `{{ bundle.credentials.github_token }}`, or directly access the 
+environment variable or path where the credential is stored.
+
+In the example below, the bundle defines two credentials. A kubeconfig file,
+which once passed to the bundle is stored at /root/.kube/config, and a GitHub
+token which once passed to the bundle is stored in the GITHUB_TOKEN environment
+variable.
+
+```yaml
+credentials:
+- name: kubeconfig
+  path: /root/.kube/config
+- name: token
+  env: GITHUB_TOKEN
+```
+
+The paths and environment variable names used in the credential
+declaration represent where the value of the injected credentials are stored
+_in the bundle when it is executing_. They are not used to locate the credential,
+that is the responsibility of credential sets.
 
 ## Credential Sets
 
-Credentials are injected when a bundle is executed
-(install/upgrade/uninstall/invoke). First a user creates a credentials set using
-[porter credentials generate][generate]. This is a mapping that tells porter
+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
 "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
@@ -30,22 +48,34 @@ to validate that you have created it properly.
 ## Runtime
 
 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.
+with `--cred` or `-c` flags. For example, `porter install --cred github`. Before the
+bundle is executed, Porter users the credential set's mappings to retrieve the
+credential values, and then injects them into the bundle's execution environment 
+as either environment variables or files.
 
-Inside the bundle's execution environment Porter looks for those environment
-variables that represent the credentials and replaces the template placeholders
+Inside the bundle's execution environment Porter replaces the template placeholders
 like `{{ bundle.credentials.github_token }}` with the actual credential value
-before executing the step.
+before executing the step. Credentials are also available directly through the
+environment variable or path used in its declaration.
 
 Once the bundle finishes executing, the credentials are NOT recorded in the
 installation history. Parameters are recorded there so that you can view them
 later using `porter installations show NAME --output json`.
 
 ## Q & A
 
+### Can I pass credentials to a bundle without credential sets?
+
+No, credentials must be passed to a bundle using credential sets.
+Credentials are sensitive values and should ideally be sourced from a secret store such as Hashicorp Vault or Azure Key Vault to limit their exposure.
+
+If circumstances prevent you from using credential sets stored by Porter, you can export a credential set to a file and pass the file to a bundle as demonstrated below.
+
+```
+porter credentials show NAME --output json > creds.json
+porter install --cred ./creds.json
+```
+
 ### 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
@@ -59,4 +89,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/
+[generate]: /cli/porter_credentials_generate/
+
+## Related
+
+* [QuickStart: Pass credentials to a bundle](/quickstart/credentials/)
diff --git a/docs/content/mixins/helm.md → docs/content/mixins/helm2.md b/docs/content/mixins/helm.md → docs/content/mixins/helm2.md
@@ -1,17 +1,19 @@
 ---
-title: helm mixin
-description: Manage a Helm release with the helm CLI
+title: helm v2 mixin
+description: Manage a Helm release with the helm v2 CLI
 ---
 
 <img src="/images/mixins/helm.svg" class="mixin-logo" style="width: 150px"/>
 
-This is a [Helm](https://helm.sh) mixin for
-[Porter](https://github.com/getporter/porter). It executes the appropriate helm
+This is a [Helm](https://helm.sh) v2 mixin for
+[Porter](https://github.com/getporter/porter). It executes the appropriate helm v2
 command based on which action it is included within: `install`, `upgrade`, or
 `delete`.
 
 Source: https://github.com/getporter/helm-mixin
 
+⚠️ Helm v2 is no longer supported. Check out the [helm v3](/mixins/helm3/) mixin!
+
 ### Install or Upgrade
 
 ```shell

diff --git a/docs/content/mixins/helm3.md b/docs/content/mixins/helm3.md
@@ -0,0 +1,172 @@
+---
+title: helm3 mixin
+description: Manage a Helm release with the helm v3 CLI
+aliases:
+- /mixins/helm/
+---
+
+<img src="/images/mixins/helm.svg" class="mixin-logo" style="width: 150px"/>
+
+This is a [Helm](https://helm.sh) v3 mixin for
+[Porter](https://github.com/getporter/porter). It executes the appropriate helm v3
+command based on which action it is included within: `install`, `upgrade`, or
+`delete`.
+
+Source: https://github.com/MChorfa/porter-helm3
+
+### Install or Upgrade
+
+```shell
+porter mixin install helm3 --feed-url https://mchorfa.github.io/porter-helm3/atom.xml
+```
+
+### Mixin Configuration
+
+Helm client version configuration. You can define others minors and patch versions up and down
+
+```yaml
+- helm3:
+    clientVersion: v3.3.4
+```
+
+Repositories
+
+```yaml
+- helm3:
+    repositories:
+      stable:
+        url: "https://charts.helm.sh/stable"
+```
+
+### Mixin Syntax
+
+Install
+
+```yaml
+install:
+  - helm3:
+      description: "Description of the command"
+      name: RELEASE_NAME
+      chart: STABLE_CHART_NAME
+      version: CHART_VERSION
+      namespace: NAMESPACE
+      replace: BOOL # Remove it if upsert is set to true. This is unsafe in production
+      devel: BOOL
+      wait: BOOL # default true
+      upsert: BOOL # default false. If set to true `upgrade --install` will be executed
+      set:
+        VAR1: VALUE1
+        VAR2: VALUE2
+```
+
+Upgrade
+
+```yaml
+upgrade:
+  - helm3:
+      description: "Description of the command"
+      name: RELEASE_NAME
+      chart: STABLE_CHART_NAME
+      version: CHART_VERSION
+      namespace: NAMESPACE
+      resetValues: BOOL
+      reuseValues: BOOL
+      wait: BOOL # default true
+      set:
+        VAR1: VALUE1
+        VAR2: VALUE2
+```
+
+Uninstall
+
+```yaml
+uninstall:
+  - helm3:
+      description: "Description of command"
+      namespace: NAMESPACE
+      releases:
+        - RELEASE_NAME1
+        - RELASE_NAME2
+```
+
+#### Outputs
+
+The mixin supports saving secrets from Kubernetes as outputs.
+
+```yaml
+outputs:
+  - name: NAME
+    secret: SECRET_NAME
+    key: SECRET_KEY
+```
+
+The mixin also supports extracting resource metadata from Kubernetes as outputs.
+
+```yaml
+outputs:
+  - name: NAME
+    resourceType: RESOURCE_TYPE
+    resourceName: RESOURCE_TYPE_NAME
+    namespace: NAMESPACE
+    jsonPath: JSON_PATH_DEFINITION
+```
+
+### Examples
+
+Install
+
+```yaml
+install:
+  - helm3:
+      description: "Install MySQL"
+      name: mydb
+      chart: stable/mysql
+      version: 0.10.2
+      namespace: mydb
+      replace: true
+      set:
+        mysqlDatabase: wordpress
+        mysqlUser: wordpress
+      outputs:
+        - name: mysql-root-password
+          secret: mydb-mysql
+          key: mysql-root-password
+        - name: mysql-password
+          secret: mydb-mysql
+          key: mysql-password
+        - name: mysql-cluster-ip
+          resourceType: service
+          resourceName: porter-ci-mysql-service
+          namespace: "default"
+          jsonPath: "{.spec.clusterIP}"
+```
+
+Upgrade
+
+```yaml
+upgrade:
+  - helm3:
+      description: "Upgrade MySQL"
+      name: porter-ci-mysql
+      chart: stable/mysql
+      version: 0.10.2
+      wait: true
+      resetValues: true
+      reuseValues: false
+      set:
+        mysqlDatabase: mydb
+        mysqlUser: myuser
+        livenessProbe.initialDelaySeconds: 30
+        persistence.enabled: true
+```
+
+Uninstall
+
+```yaml
+uninstall:
+  - helm3:
+      description: "Uninstall MySQL"
+      namespace: mydb
+      releases:
+        - mydb
+```
diff --git a/docs/content/parameters.md b/docs/content/parameters.md
@@ -66,3 +66,7 @@ applies to parameter sources as well.
 
 [generate]: /cli/porter_parameters_generate/
 [edit]: /cli/porter_parameters_edit/
+
+## Related
+
+* [QuickStart: Use parameters with a bundle](/quickstart/parameters/)
diff --git a/docs/content/quickstart/_index.md b/docs/content/quickstart/_index.md
@@ -152,5 +152,5 @@ porter uninstall porter-hello
 
 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.
 
-* [Use parameters with a bundle](/quickstart/parameters/)
+* [QuickStart: Use parameters with a bundle](/quickstart/parameters/)
 * [Learn more about use cases for bundles](/learning/#the-devil-is-in-the-deployments-bundle-use-cases)