deployment: update helm and add quick-start docs (pomerium#75)

- adds quick-start documentation for using helm
- update helm deployment charts to match outstanding official charts repo.

docs/.vuepress/config.js

@@ -30,7 +30,7 @@ function guideSidebar(title) {
 		{
 			title,
 			collapsable: false,
-			children: ["", "kubernetes", "from-source"]
+			children: ["", "helm", "kubernetes", "from-source"]
 		}
 	];
 }

docs/guide/helm.md

@@ -0,0 +1,72 @@
+# Helm
+
+This quickstart will show you how to deploy Pomerium with Helm. For the purpose of this guide, we will be using Google's Kubernetes Engine. However, there are many other ways to work with Kubernetes:
+
+- [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine/)
+- [Azure Kubernetes Service](https://azure.microsoft.com/en-us/services/kubernetes-service/)
+- [Amazon Elastic Kubernetes Service (Amazon EKS)](https://aws.amazon.com/eks/)
+- [OpenShift Kubernetes](https://www.openshift.com/learn/topics/kubernetes/)
+- Or locally, with [minikube](https://kubernetes.io/docs/setup/minikube/)
+
+Most of the following steps should be very similar using any other provider, but may require additional tweaks. 
+
+
+## Prerequisites
+
+- A [Google Cloud Account](https://console.cloud.google.com/)
+- A configured [identity provider]
+- Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
+- Install the [Google Cloud SDK](https://cloud.google.com/kubernetes-engine/docs/quickstart)
+- Install [helm](https://helm.sh/docs/using_helm/)
+
+## Download
+
+Retrieve the latest copy of pomerium's source-code by cloning the repository.
+
+```bash
+git clone https://github.com/pomerium/pomerium.git $HOME/pomerium
+```
+
+## Configure
+
+Edit the the install command in the [helm_gke.sh script ][./scripts/helm_gke.sh] to match your [identity provider] settings.
+
+
+Generate a wild-card TLS certificate. If you don't have one handy, the included [script] generates one from [LetsEncrypt].
+
+## Run
+
+Run [./scripts/helm_gke.sh] which will:
+
+1. Provision a new cluster
+2. Create authenticate, authorize, and proxy [deployments](https://cloud.google.com/kubernetes-engine/docs/concepts/deployment).
+3. Provision and apply authenticate, authorize, and proxy [services](https://cloud.google.com/kubernetes-engine/docs/concepts/service).
+4. Configure an ingress, Google's default load balancer.
+
+```bash
+sh ./scripts/helm_gke.sh
+```
+
+You should see roughly the following in your terminal. Note, provisioning does take a few minutes.
+
+[![helm pomerium screencast](https://asciinema.org/a/223821.svg)]([https://asciinema.org/a/223821](https://asciinema.org/a/YcYC4iZLZi5kCCU5lQIWzFnhV)
+
+And if you check out Google's Kubernetes Engine dashboard you'll see something like:
+
+![Google's Kubernetes Engine dashboard](./kubernetes-gke.png)
+
+## Navigate
+
+Open a browser and navigate to `httpbin.corp.example.com`.
+
+You should see something like the following in your browser.
+
+![Getting started](./get-started.gif)
+
+[./scripts/helm_gke.sh]: ../docs/examples.html#google-kubernetes-engine
+[example kubernetes files]: ../docs/examples.html#google-kubernetes-engine
+[helloworld]: https://hub.docker.com/r/tutum/hello-world
+[httpbin]: https://httpbin.org/
+[identity provider]: ../docs/identity-providers.md
+[letsencrypt]: https://letsencrypt.org/
+[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh

docs/guide/kubernetes.md

@@ -10,11 +10,6 @@ This quickstart will show you how to deploy Pomerium with Kubernetes. For the pu
 
 Most of the following steps should be very similar using any other provider.
 
-:::tip
-
-Google Cloud Platform has a [free trial with $300 credits](https://cloud.google.com/free/docs/gcp-free-tier).
-
-:::
 
 ## Prerequisites
 

helm/Chart.yaml

@@ -1,6 +1,6 @@
 apiVersion: v1
 name: pomerium
-version: 0.0.3
+version: 1.0.0
 appVersion: 0.0.3
 home: http://www.pomerium.io/
 icon: https://www.pomerium.io/logo.svg
@@ -22,5 +22,5 @@ sources:
 engine: gotpl
 
 maintainers:
-- name: bobby desimone
+- name: desimone
   email: [email protected]

helm/OWNERS

@@ -0,0 +1,5 @@
+approvers:
+- desimone
+reviewers:
+- desimone
+- victornoel

helm/README.md

@@ -1,9 +1,71 @@
 # Pomerium
 
-[Pomerium](https://github.com/pomerium/pomerium) is a tool for managing secure access to internal applications and resources.
+[Pomerium](https://pomerium.io) is an [open-source](https://github.com/pomerium/pomerium) tool for managing secure access to internal applications and resources.
 
 ## TL;DR;
 
 ```console
-$ helm install pomerium/pomerium
+helm install --name my-release stable/pomerium
 ```
+
+> Note: Pomerium depends on being configured with a third party identity providers to function properly. If you run pomerium without specifiying default values, you will need to change those configuration variables following setup.
+
+## Install the chart
+
+An example of a minimal, but complete installation of pomerium with identity provider settings, random secrets, certificates, and external URLs is as follows:
+
+```sh
+helm install --name my-release \
+    --set config.rootDomain="corp.example.com" \
+    --set ingress.tls.certificate=$(base64 -i "*.corp.example.com.cer") \
+    --set ingress.tls.key=$(base64 -i "*.corp.example.com.key") \
+    --set config.policy=$(base64 -i "policy.yaml") \
+    --set authenticate.idp.provider="google" \
+    --set authenticate.idp.clientID="REPLACE_ME" \
+    --set authenticate.idp.clientSecret="REPLACE_ME"
+    stable/pomerium
+```
+
+## Uninstalling the Chart
+
+To uninstall/delete the `my-release` deployment:
+
+```console
+helm delete --purge my-release
+```
+
+The command removes nearly all the Kubernetes components associated with the chart and deletes the release.
+
+## Configuration
+
+A full listing of Pomerium's configuration variables can be found on the [config reference page](https://www.pomerium.io/docs/config-reference.html).
+
+Parameter                         | Description                                                                                                                                                                                                | Default
+--------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------
+`config.rootDomain`               | Root Domain specifies the sub-domain handled by pomerium. [See more](https://www.pomerium.io/docs/config-reference.html#proxy-root-domains).                                                   | `corp.pomerium.io`
+`config.generateTLS`              | Generate a dummy Certificate Authority and certs for service communication. Manual CA and certs can be set in values.                                                                                      | `true`
+`config.sharedSecret`             | 256 bit key to secure service communication. [See more](https://www.pomerium.io/docs/config-reference.html#shared-secret).                                                                                 | 32 [random ascii chars](http://masterminds.github.io/sprig/strings.html)
+`config.cookieSecret`             | Cookie secret is a 32 byte key used to encrypt user sessions.                                                                                                                                              | 32 [random ascii chars](http://masterminds.github.io/sprig/strings.html)
+`config.policy`                   | Base64 encoded string containing the routes, and their access policies.                                                                                                                                    |
+`config.policyFile`               | Relative file location of the policy file which contains the routes, and their access policies.                                                                                                            | [See example](https://www.pomerium.io/docs/config-reference.html#policy) in values
+`authenticate.name`               | Name of the authenticate service.                                                                                                                                                                          | `authenticate`
+`authenticate.redirectUrl`        | Redirect URL is the url the user will be redirected to following authentication with the third-party identity provider (IdP). [See more](https://www.pomerium.io/docs/config-reference.html#redirect-url). | `https://{{authenticate.name}}.{{config.rootDomain}}/oauth2/callback`
+`authenticate.idp.provider`       | Identity [Provider Name](https://www.pomerium.io/docs/config-reference.html#identity-provider-name).                                                                                                       | `google`
+`authenticate.idp.clientID`       | Identity Provider oauth [client ID](https://www.pomerium.io/docs/config-reference.html#identity-provider-client-id).                                                                                       | Required
+`authenticate.idp.clientSecret`   | Identity Provider oauth [client secret](https://www.pomerium.io/docs/config-reference.html#identity-provider-client-secret).                                                                               | Required
+`authenticate.idp.url`            | Identity [Provider URL](https://www.pomerium.io/docs/config-reference.html#identity-provider-url).                                                                                                         | Optional
+`authenticate.idp.serviceAccount` | Identity Provider [service account](https://www.pomerium.io/docs/config-reference.html#identity-provider-service-account).                                                                                 | Optional
+`proxy.name`                      | Name of the proxy service.                                                                                                                                                                                 | `proxy`
+`proxy.authenticateServiceUrl`    | The externally accessible url for the authenticate service.                                                                                                                                                | `https://{{authenticate.name}}.{{config.rootDomain}}`
+`proxy.authorizeServiceUrl`       | The externally accessible url for the authorize service.                                                                                                                                                   | `https://{{authorize.name}}.{{config.rootDomain}}`
+`authorize.name`                  | Name of the authorize service.                                                                                                                                                                             | `authorize`
+`images.server.repository`        | Pomerium image                                                                                                                                                                                             | `pomerium/pomerium`
+`images.server.tag`               | Pomerium image tag                                                                                                                                                                                         | `latest`
+`images.server.pullPolicy`        | Pomerium image pull policy                                                                                                                                                                                 | `Always`
+`service.annotations`             | Service annotations                                                                                                                                                                                        | `{}`
+`service.externalPort`            | Pomerium's port                                                                                                                                                                                            | `443`
+`service.type`                    | Service type (ClusterIP, NodePort or LoadBalancer)                                                                                                                                                         | `ClusterIP`
+`ingress.enabled`                 | Enables Ingress for pomerium                                                                                                                                                                               | `false`
+`ingress.annotations`             | Ingress annotations                                                                                                                                                                                        | `{}`
+`ingress.hosts`                   | Ingress accepted hostnames                                                                                                                                                                                 | `nil`
+`ingress.tls`                     | Ingress TLS configuration                                                                                                                                                                                  | `[]`

helm/templates/NOTES.txt

@@ -0,0 +1,67 @@
+{{- if eq (include "pomerium.providerOK" .) "true" }}
+{{- if .Values.ingress.enabled }}
+From outside the cluster, the server URL(s) are:
+{{- range .Values.ingress.hosts }}
+     {{ $.Values.server.protocol }}://{{ . }}
+{{- end }}
+
+{{- else if contains "NodePort" .Values.service.type }}
+
+Get the Pomerium URL by running:
+  export NODE_PORT=$(kubectl get -o jsonpath="{.spec.ports[0].nodePort}" services {{ template "pomerium.fullname" . }})
+  export NODE_IP=$(kubectl get nodes -o jsonpath="{.items[0].status.addresses[0].address}")
+  echo http://$NODE_IP:$NODE_PORT/
+
+{{- else if contains "LoadBalancer" .Values.service.type }}
+
+  NOTE: It may take a few minutes for the LoadBalancer IP to be available.
+        Watch the status with: 'kubectl get svc -w {{ template "pomerium.fullname" . }}'
+
+Get the Pomerium URL by running:
+  export SERVICE_IP=$(kubectl get svc {{ template "pomerium.fullname" . }} -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
+  echo http://$SERVICE_IP/
+{{- else if contains "ClusterIP" .Values.service.type }}
+
+Get the Pomerium URL by running:
+  export POD_NAME=$(kubectl get pods -n {{ .Release.Namespace }} -l "component=server,app={{ template "pomerium.name" . }},release={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
+  echo http://127.0.0.1:8000/
+  kubectl -n {{ .Release.Namespace }} port-forward $POD_NAME 8000:8000
+{{- end }}
+{{- else -}}
+##############################################################################
+####        ERROR: You did not set a valid identity provider              ####
+##############################################################################
+
+This deployment will be incomplete until you configure a valid version
+control provider:
+
+    helm upgrade {{ .Release.Name }} \
+        --reuse-values \
+        --set config.sharedSecret=$(head -c32 /dev/urandom | base64) \
+        --set config.cookieSecret=$(head -c32 /dev/urandom | base64) \
+        --set config.cert=$(base64 -i cert.pem) \
+        --set config.key=$(base64 -i privkey.pem) \
+        --set config.policy="$(cat policy.example.yaml | base64)" \
+        --set authenticate.idp.provider="google" \
+        --set config.rootDomain="corp.pomerium.io" \
+        --set authenticate.redirectUrl="https://auth.corp.pomerium.io/oauth2/callback" \
+        --set authenticate.idp.clientID="REPLACE_ME" \
+        --set authenticate.idp.clientSecret="REPLACE_ME" \
+        --set proxy.authenticateServiceUrl="https://auth.corp.pomerium.io" \
+        --set proxy.authorizeServiceUrl="https://access.corp.pomerium.io"
+        stable/pomerium
+
+Currently supported providers:
+
+    - Okta
+    - Google
+    - Azure Active Directory
+    - OneLogin
+
+See the values.yaml file to see what values are required for each provider.
+
+If you are having trouble with the configuration of a provider please visit
+the official documentation:
+
+    https://www.pomerium.io/docs/identity-providers.html
+{{- end }}

helm/templates/_helpers.tpl

@@ -35,3 +35,24 @@ If release name contains chart name it will be used as a full name.
 {{- end -}}
 {{- join "," $routes.routes | default "none=none" | quote -}}
 {{- end -}}
+
+
+{{/*
+Check if a valid source control provider has been set
+Adapted from : https://github.com/helm/charts/blob/master/stable/drone/templates/_provider-envs.yaml
+*/}}
+{{- define "pomerium.providerOK" -}}
+{{- if .Values.authenticate.idp -}}
+  {{- if eq .Values.authenticate.idp.clientID "" -}}
+  false
+  {{- else if eq .Values.authenticate.idp.clientSecret "" -}}
+  false
+  {{- else if eq .Values.authenticate.idp.clientID "REPLACE_ME" -}}
+  false
+  {{- else if eq .Values.authenticate.idp.clientSecret "REPLACE_ME" -}}
+  false
+  {{- else -}}
+  true
+  {{- end -}}
+{{- end -}}
+{{- end -}}