docs: add kubernetes (#33)

- Update PR template to use Go language conventions.
- Moved healthcheck middleware to hijack a request before logging.
- Rewrote the quickstart guides to follow a similar pattern.
- Added an overview blurb on pomerium and its goals.
- Add an "example config" section to docs.

.github/PULL_REQUEST_TEMPLATE

@@ -1,12 +1,24 @@
-<!--  Thanks for sending a pull request!  Here are some tips for you:
-1. If this PR closes another issue, add 'closes #<issue number>' somewhere in the PR summary. GitHub will automatically close that issue when this PR gets merged. Alternatively, adding 'refs #<issue number>' will not close the issue, but help provide the reviewer more context.-->
-2. The PR title is formatted as follows: `proxy: frob the quux before blarfing`
+<!--  Thanks for sending a pull request!
+We generally follow Go coding and contributing conventions 
+which you can read about here https://golang.org/doc/contribute.html#commit_messages
 
-**What this PR does / why we need it**:
+Here's an example of a good PR/Commit:
 
-**Special notes for your reviewer**:
+    math: improve Sin, Cos and Tan precision for very large arguments
 
-**If applicable**:
-- [ ] this PR contains documentation
-- [ ] this PR contains unit tests
-- [ ] this PR has been tested for backwards compatibility
+    The existing implementation has poor numerical properties for
+    large arguments, so use the McGillicutty algorithm to improve
+    accuracy above 1e10.
+
+    The algorithm is described at https://wikipedia.org/wiki/McGillicutty_Algorithm
+
+    Fixes #159
+-->
+
+
+<!--  handy checklist ; not required--> 
+**Checklist**:
+- [ ] documentation updated
+- [ ] unit tests added
+- [ ] related issues referenced
+- [ ] ready for review

README.md

@@ -24,7 +24,7 @@ To get started with pomerium, check out our [quick start guide].
 For comprehensive docs see our [documentation] and the [godocs].
 
 [awesome-zero-trust]: https://github.com/pomerium/awesome-zero-trust
-[documentation]: https://www.pomerium.io/
+[documentation]: https://www.pomerium.io/docs/
 [go environment]: https://golang.org/doc/install
 [godocs]: https://godoc.org/github.com/pomerium/pomerium
 [quick start guide]: https://www.pomerium.io/guide/

authenticate/handlers.go

@@ -30,6 +30,7 @@ var securityHeaders = map[string]string{
 func (p *Authenticate) Handler() http.Handler {
 	// set up our standard middlewares
 	stdMiddleware := middleware.NewChain()
+	stdMiddleware = stdMiddleware.Append(middleware.Healthcheck("/ping", version.UserAgent()))
 	stdMiddleware = stdMiddleware.Append(middleware.NewHandler(log.Logger))
 	stdMiddleware = stdMiddleware.Append(middleware.AccessHandler(func(r *http.Request, status, size int, duration time.Duration) {
 		// executed after handler route handler
@@ -47,7 +48,6 @@ func (p *Authenticate) Handler() http.Handler {
 	stdMiddleware = stdMiddleware.Append(middleware.UserAgentHandler("user_agent"))
 	stdMiddleware = stdMiddleware.Append(middleware.RefererHandler("referer"))
 	stdMiddleware = stdMiddleware.Append(middleware.RequestIDHandler("req_id", "Request-Id"))
-	stdMiddleware = stdMiddleware.Append(middleware.Healthcheck("/ping", version.UserAgent()))
 	validateSignatureMiddleware := stdMiddleware.Append(
 		middleware.ValidateSignature(p.SharedKey),
 		middleware.ValidateRedirectURI(p.ProxyRootDomains))

docs/.vuepress/config.js

@@ -9,19 +9,32 @@ module.exports = {
 		docsDir: "docs",
 		editLinkText: "Edit this page on GitHub",
 		lastUpdated: "Last Updated",
-		nav: [{ text: "Guide", link: "/guide/" }],
+		nav: [{ text: "Quick Start", link: "/guide/" },
+		{ text: "Documentation", link: "/docs/" }],
 		sidebar: {
-			"/guide/": genSidebarConfig("Guide")
+			"/guide/": guideSidebar("Quick Start"),
+			"/docs/": docsSidebar("Documentation")
+
 		}
 	}
 };
 
-function genSidebarConfig(title) {
+function guideSidebar(title) {
 	return [
 		{
 			title,
 			collapsable: false,
-			children: ["", "identity-providers", "signed-headers"]
+			children: ["", "docker", "kubernetes", "from-source"]
+		}
+	];
+}
+
+function docsSidebar(title) {
+	return [
+		{
+			title,
+			collapsable: false,
+			children: ["", "identity-providers", "signed-headers", "examples"]
 		}
 	];
 }

docs/docs/examples.md

@@ -0,0 +1,98 @@
+---
+sidebarDepth: 3
+---
+
+# Example Configurations
+
+A collection of copy-and-pasteable example pomerium configurations for various types of clouds, use-cases, and deployments. All of these files can also be found in the git repository in the `docs/docs/examples/` directory.
+
+:::tip
+
+Remember to set your identity provider settings and to generate new secret keys!
+
+:::
+
+## Binary
+
+- Suitable for bare-metal and virtual-machines
+- No docker, docker-compose, or kubernetes required
+- Minimal configuration
+- Pomerium services are run in "all-in-one" mode
+- No load balancer required
+- Great for testing Pomerium
+- Routes default to hosted version of httpbin.org
+
+Customize for your identity provider and run `source ./env && ./bin/pomerium`
+
+<<< @/env.example
+
+## Docker
+
+Uses the [latest pomerium build](https://hub.docker.com/r/pomerium/pomerium) from docker hub. Docker and docker-compose are great tools for standing up and testing multiple service, and containers without having to stand-up a full on cluster.
+
+### Basic
+
+- Minimal container-based configuration.
+- Docker and Docker-Compose based.
+- Uses pre-configured built-in nginx load balancer
+- Runs separate containers for each service
+- Comes with a pre-configured instance of on-prem Gitlab-CE
+- Routes default to on-prem [helloworld], [httpbin] containers.
+
+Customize for your identity provider run `docker-compose up -f basic.docker-compose.yml`
+
+#### basic.docker-compose.yml
+
+<<< @/docs/docs/examples/basic.docker-compose.yml
+
+### Gitlab On-premise
+
+- Docker and Docker-Compose based.
+- Uses pre-configured built-in nginx load balancer
+- Runs separate containers for each service
+- Comes with a pre-configured instance of on-prem Gitlab-CE
+- Routes default to on-prem [helloworld], [httpbin], and [gitlab] containers.
+
+Customize for your identity provider run `docker-compose up -f gitlab.docker-compose.yml`
+
+#### gitlab.docker-compose.yml
+
+<<< @/docs/docs/examples/gitlab.docker-compose.yml
+
+## Kubernetes
+
+### Google Kubernetes Engine
+
+- Uses GKE's built-in ingress to do [HTTPS load balancing]
+- HTTPS (TLS) between client and load balancer
+- Routes default to hosted version of httpbin.org
+- Includes all-in-one script
+
+#### kubernetes_gke.sh
+
+<<< @/scripts/kubernetes_gke.sh
+
+#### authenticate.deploy.yml
+
+<<< @/docs/docs/examples/kubernetes/authenticate.deploy.yml
+
+#### authenticate.service.yml
+
+<<< @/docs/docs/examples/kubernetes/authenticate.service.yml
+
+#### proxy.deploy.yml
+
+<<< @/docs/docs/examples/kubernetes/proxy.deploy.yml
+
+#### proxy.service.yml
+
+<<< @/docs/docs/examples/kubernetes/proxy.service.yml
+
+#### ingress.yml
+
+<<< @/docs/docs/examples/kubernetes/ingress.yml
+
+[gitlab]: https://docs.gitlab.com/ee/user/project/container_registry.html
+[helloworld]: https://hub.docker.com/r/tutum/hello-world
+[httpbin]: https://httpbin.org/
+[https load balancing]: https://cloud.google.com/kubernetes-engine/docs/concepts/ingress

docs/docs/examples/gitlab.docker-compose.yml

@@ -1,7 +1,6 @@
 version: "3"
 
 services:
-  # NGINX routes to pomerium's services depending on the request.
   nginx:
     image: jwilder/nginx-proxy:latest
     ports:
@@ -68,16 +67,6 @@ services:
     expose:
       - 443
 
-  # https://httpbin.corp.beyondperimeter.com
-  httpbin:
-    image: kennethreitz/httpbin:latest
-    expose:
-      - 80
-  # https://hello.corp.beyondperimeter.com
-  hello-world:
-    image: tutum/hello-world:latest
-    expose:
-      - 80
   gitlab:
     hostname: gitlab.corp.beyondperimeter.com
     image: gitlab/gitlab-ce:latest

docs/docs/examples/kubernetes/authenticate.deploy.yml

@@ -0,0 +1,82 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: pomerium-authenticate
+  labels:
+    app: pomerium-authenticate
+  namespace: pomerium
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: pomerium-authenticate
+  template:
+    metadata:
+      labels:
+        app: pomerium-authenticate
+    spec:
+      containers:
+        - image: pomerium/pomerium:latest
+          name: pomerium-authenticate
+          ports:
+            - containerPort: 443
+              name: https
+              protocol: TCP
+          env:
+            - name: SERVICES
+              value: authenticate
+            - name: REDIRECT_URL
+              value: https://sso-auth.corp.beyondperimeter.com/oauth2/callback
+            - name: IDP_PROVIDER
+              value: google
+            - name: IDP_PROVIDER_URL
+              value: https://accounts.google.com
+            - name: IDP_CLIENT_ID
+              value: 851877082059-bfgkpj09noog7as3gpc3t7r6n9sjbgs6.apps.googleusercontent.com
+            - name: PROXY_ROOT_DOMAIN
+              value: beyondperimeter.com
+            - name: ALLOWED_DOMAINS
+              value: "*"
+            - name: SHARED_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: shared-secret
+                  key: shared-secret
+            - name: COOKIE_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: cookie-secret
+                  key: cookie-secret
+            - name: IDP_CLIENT_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: idp-client-secret
+                  key: idp-client-secret
+            - name: CERTIFICATE
+              valueFrom:
+                secretKeyRef:
+                  name: certificate
+                  key: certificate
+            - name: CERTIFICATE_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: certificate-key
+                  key: certificate-key
+            - name: VIRTUAL_PROTO
+              value: https
+            - name: VIRTUAL_HOST
+              value: sso-auth.corp.beyondperimeter.com
+            - name: VIRTUAL_PORT
+              value: "443"
+          readinessProbe:
+            httpGet:
+              path: /ping
+              port: 443
+              scheme: HTTPS
+          livenessProbe:
+            httpGet:
+              path: /ping
+              port: 443
+              scheme: HTTPS
+            initialDelaySeconds: 10
+            timeoutSeconds: 1

docs/docs/examples/kubernetes/authenticate.service.yml

@@ -0,0 +1,14 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: pomerium-authenticate-service
+  namespace: pomerium
+  annotations:
+    cloud.google.com/app-protocols: '{"https":"HTTPS"}'
+spec:
+  ports:
+    - port: 443
+      name: https
+  selector:
+    app: pomerium-authenticate
+  type: NodePort

docs/docs/examples/kubernetes/ingress.yml

@@ -0,0 +1,39 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  name: pomerium-ingress
+  namespace: pomerium
+  annotations:
+    kubernetes.io/ingress.allow-http: "false"
+    kubernetes.io/ingress.global-static-ip-name: pomerium
+
+spec:
+  tls:
+    - secretName: pomerium-tls
+      hosts:
+        - "*.corp.beyondperimeter.com"
+        - "sso-auth.corp.beyondperimeter.com"
+  rules:
+    - host: "*.corp.beyondperimeter.com"
+      http:
+        paths:
+          - path: /
+            backend:
+              serviceName: pomerium-proxy-service
+              servicePort: 443
+          - path: /*
+            backend:
+              serviceName: pomerium-proxy-service
+              servicePort: 443
+
+    - host: "sso-auth.corp.beyondperimeter.com"
+      http:
+        paths:
+          - path: /*
+            backend:
+              serviceName: pomerium-authenticate-service
+              servicePort: 443
+          - path: /
+            backend:
+              serviceName: pomerium-authenticate-service
+              servicePort: 443

docs/docs/examples/kubernetes/proxy.deploy.yml

@@ -0,0 +1,74 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: pomerium-proxy
+  labels:
+    app: pomerium-proxy
+  namespace: pomerium
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: pomerium-proxy
+  template:
+    metadata:
+      labels:
+        app: pomerium-proxy
+    spec:
+      containers:
+        - image: pomerium/pomerium:latest
+          name: pomerium-proxy
+          ports:
+            - containerPort: 443
+              name: https
+              protocol: TCP
+          env:
+            - name: ROUTES
+              value: https://httpbin.corp.beyondperimeter.com=https://httpbin.org
+            - name: SERVICES
+              value: proxy
+            - name: AUTHENTICATE_SERVICE_URL
+              value: https://sso-auth.corp.beyondperimeter.com
+            - name: SHARED_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: shared-secret
+                  key: shared-secret
+            - name: COOKIE_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: cookie-secret
+                  key: cookie-secret
+            - name: IDP_CLIENT_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: idp-client-secret
+                  key: idp-client-secret
+            - name: CERTIFICATE
+              valueFrom:
+                secretKeyRef:
+                  name: certificate
+                  key: certificate
+            - name: CERTIFICATE_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: certificate-key
+                  key: certificate-key
+            - name: VIRTUAL_PROTO
+              value: https
+            - name: VIRTUAL_HOST
+              value: "*.corp.beyondperimeter.com"
+            - name: VIRTUAL_PORT
+              value: "443"
+          readinessProbe:
+            httpGet:
+              path: /ping
+              port: 443
+              scheme: HTTPS
+          livenessProbe:
+            httpGet:
+              path: /ping
+              port: 443
+              scheme: HTTPS
+            initialDelaySeconds: 10
+            timeoutSeconds: 1

docs/docs/examples/kubernetes/proxy.service.yml

@@ -0,0 +1,17 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: pomerium-proxy-service
+  namespace: pomerium
+  annotations:
+    cloud.google.com/app-protocols: '{"https":"HTTPS"}'
+
+spec:
+  ports:
+    - port: 443
+      protocol: TCP
+      name: https
+      targetPort: https
+  selector:
+    app: pomerium-proxy
+  type: NodePort

docs/docs/readme.md

@@ -0,0 +1,53 @@
+# Overview
+
+## What
+
+Pomerium is an open-source, identity-aware access proxy.
+
+## Why
+
+Traditional [perimeter](https://www.redbooks.ibm.com/redpapers/pdfs/redp4397.pdf) [security](https://en.wikipedia.org/wiki/Perimeter_Security)has some shortcomings, namely:
+
+- Insider threat is not well addressed and 28% of breaches are [by internal actors](http://www.documentwereld.nl/files/2018/Verizon-DBIR_2018-Main_report.pdf).
+- Impenetrable fortress in theory falls in practice; multiple entry points (like VPNs), lots of firewall rules, network segmentation creep.
+- Failure to encapsulate a heterogeneous mix of cloud, on-premise, cloud, and multi-cloud environments.
+- User's don't like VPNs.
+
+Pomerium attempts to mitigate these shortcomings by by adopting the following principles.
+
+- Trust flows from user, device, and context.
+- Network location _does not impart trust_. Treat both internal and external networks as completely untrusted.
+- Act like you are already breached, because your probably are.
+- Every device, user, and application's communication should be authenticated, authorized, and encrypted.
+- Policy should be dynamic, and built from multiple sources.
+
+## Resources
+
+### Books
+
+- [Zero Trust Networks](http://shop.oreilly.com/product/0636920052265.do) by Gilman and Barth
+
+### Papers
+
+- Forrester [Build Security Into Your Network's DNA: The Zero Trust Network Architecture](http://www.virtualstarmedia.com/downloads/Forrester_zero_trust_DNA.pdf)
+- Google BeyondCorp 1 [An overview: "A New Approach to Enterprise Security"](https://research.google.com/pubs/pub43231.html)
+- Google BeyondCorp 2 [How Google did it: "Design to Deployment at Google"](https://research.google.com/pubs/pub44860.html)
+- Google BeyondCorp 3 [Google's front-end infrastructure: "The Access Proxy"](https://research.google.com/pubs/pub45728.html)
+- Google BeyondCorp 4 [Migrating to BeyondCorp: Maintaining Productivity While Improving Security](https://research.google.com/pubs/pub46134.html)
+- Google BeyondCorp 5 [The human element: "The User Experience"](https://research.google.com/pubs/pub46366.html)
+- Google BeyondCorp 6 [Secure your endpoints: "Building a Healthy Fleet"](https://ai.google/research/pubs/pub47356)
+
+### Posts
+
+- Google [Securing your business and securing your fleet the BeyondCorp way](https://cloud.google.com/blog/products/identity-security/securing-your-business-and-securing-your-fleet-the-beyondcorp-way)
+- Google [Preparing for a BeyondCorp world: Understanding your device inventory](https://cloud.google.com/blog/products/identity-security/preparing-beyondcorp-world-understanding-your-device-inventory)
+- Google [How BeyondCorp can help businesses be more productive](https://www.blog.google/products/google-cloud/how-beyondcorp-can-help-businesses-be-more-productive/)
+- Google [How to use BeyondCorp to ditch your VPN, improve security and go to the cloud](https://www.blog.google/products/google-cloud/how-use-beyondcorp-ditch-your-vpn-improve-security-and-go-cloud/)
+- Wall Street Journal [Google Moves Its Corporate Applications to the Internet](https://blogs.wsj.com/cio/2015/05/11/google-moves-its-corporate-applications-to-the-internet/)
+
+### Videos
+
+- [USENIX Enigma 2016 - NSA TAO Chief on Disrupting Nation State Hackers](https://youtu.be/bDJb8WOJYdA?list=PLKb9-P1fRHxhSmCy5OaYZ5spcY8v3Pbaf)
+- [What, Why, and How of Zero Trust Networking](https://youtu.be/eDVHIfVSdIo?list=PLKb9-P1fRHxhSmCy5OaYZ5spcY8v3Pbaf) by Armon Dadgar, Hashicorp
+- [O'Reilly Security 2017 NYC Beyondcorp: Beyond Fortress Security](https://youtu.be/oAvDASLehpY?list=PLKb9-P1fRHxhSmCy5OaYZ5spcY8v3Pbaf) by Neal Muller, Google
+- [Be Ready for BeyondCorp: enterprise identity, perimeters and your application](https://youtu.be/5UiWAlwok1s?list=PLKb9-P1fRHxhSmCy5OaYZ5spcY8v3Pbaf) by Jason Kent

docs/guide/docker.md

@@ -0,0 +1,48 @@
+# Docker
+
+## Prerequisites
+
+- A configured [identity provider]
+
+## Install
+
+Install [docker] and [docker-compose]. Docker-compose is a tool for defining and running multi-container Docker applications. We've created an example docker-compose file that creates a minimal, but complete test environnement for pomerium.
+
+## Download
+
+Copy and paste the contents of the provided example [basic.docker-compose.yml] and save it locally as `docker-compose.yml`.
+
+## Configure
+
+Edit the [docker-compose.yml] to match your [identity provider] settings.
+
+Place your domain's wild-card TLS certificate next to the compose file. If you don't have one handy, the included [script] generates one from [LetsEncrypt].
+
+## Run
+
+You can then download the latest pomerium release of pomerium in docker form along some example containers and an nginx load balancer all in one step.
+
+```bash
+docker-compose up
+```
+
+Pomerium is configured to delegate access to two test apps [helloworld] and [httpbin].
+
+## Navigate
+
+Open a browser and navigate to `hello.your.domain.com` or `httpbin.your.domain.com`. You should see something like the following in your browser.
+
+![Getting started](./get-started.gif)
+
+And in your terminal.
+
+[![asciicast](https://asciinema.org/a/tfbSWkUZgMRxHAQDqmcjjNwUg.svg)](https://asciinema.org/a/tfbSWkUZgMRxHAQDqmcjjNwUg)
+
+[basic.docker-compose.yml]: ../docs/examples.html#basic-docker-compose-yml
+[docker]: https://docs.docker.com/install/
+[docker-compose]: (https://docs.docker.com/compose/install/)
+[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/from-source.md

@@ -0,0 +1,75 @@
+# From source
+
+## Prerequisites
+
+- Install [git](https://git-scm.com/) version control system
+- Install the [go](https://golang.org/doc/install) programming language
+- A configured [identity provider].
+
+## 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
+```
+
+## Make
+
+Build pomerium from source in a single step using make.
+
+```bash
+cd $HOME/pomerium
+make
+```
+
+The command will run all the tests, some code linters, then build the binary. If all is good, you should now have a freshly built pomerium binary in the `pomerium/bin` directory.
+
+## Configure
+
+Make a copy of the [env.example] and name it something like `env`.
+
+```bash
+cp env.example env
+```
+
+Modify your `env` configuration to to match your [identity provider] settings.
+
+```bash
+vim env
+```
+
+Place your domain's wild-card TLS certificate next to the compose file. If you don't have one handy, the included [script] generates one from [LetsEncrypt].
+
+## Run
+
+Finally, source the the configuration `env` file and run pomerium.
+
+```bash
+source ./env
+./bin/pomerium
+```
+
+Assuming your configuration file ready to go, you can simply use this one-liner.
+
+```bash
+make && source ./env && ./bin/pomerium
+```
+
+## Navigate
+
+Browse to `httpbin.your.domain.com`. You should see something like the following in your browser.
+
+![Getting started](./get-started.gif)
+
+[certbot]: https://certbot.eff.org/docs/install.html
+[docker]: https://docs.docker.com/install/
+[docker-compose]: (https://docs.docker.com/compose/install/)
+[download]: https://github.com/pomerium/pomerium/releases
+[env.example]: https://github.com/pomerium/pomerium/blob/master/env.example
+[google gke]: https://cloud.google.com/kubernetes-engine/docs/quickstart#create_cluster
+[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

@@ -0,0 +1,83 @@
+# Kubernetes
+
+This quickstart will show you how to deploy Pomerium with Kubernetes. For the purpose of this guide, we will be using Google's Kubernetes Engine. However, there are countless 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.
+
+:::tip
+
+Google Cloud Platform has a [free trial with $300 credits](https://cloud.google.com/free/docs/gcp-free-tier).
+
+:::
+
+## 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)
+
+## 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 [example kubernetes files][./scripts/kubernetes_gke.sh] to match your [identity provider] settings:
+
+- `./docs/docs/examples/authenticate.deploy.yml`
+- `./docs/docs/examples/authenticate.service.yml`
+- `./docs/docs/examples/proxy.deploy.yml`
+- `./docs/docs/examples/proxy.service.yml`
+- `./docs/docs/examples/ingress.yml`
+
+Place your domain's wild-card TLS certificate (`privkey.pem` and `cert.pem`) in the root of the repository. If you don't have one handy, the included [script] generates one from [LetsEncrypt].
+
+Edit [./scripts/kubernetes_gke.sh] making sure to change the identity provider secret value to match your [identity provider] settings.
+
+## Run
+
+Run [./scripts/kubernetes_gke.sh] which will:
+
+1. Provision a new cluster
+2. Create authenticate and proxy [deployments](https://cloud.google.com/kubernetes-engine/docs/concepts/deployment).
+3. Provision and apply authenticate and proxy [services](https://cloud.google.com/kubernetes-engine/docs/concepts/service).
+4. Configure an ingress to do serve TLS between client and load balancer
+
+```bash
+sh ./scripts/kubernetes_gke.sh
+```
+
+You should see roughly the following in your terminal. Note, provisioning does take a few minutes.
+
+[![asciicast](https://asciinema.org/a/223821.svg)](https://asciinema.org/a/223821)
+
+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.your.domain.com`.
+
+You should see something like the following in your browser.
+
+![Getting started](./get-started.gif)
+
+[./scripts/kubernetes_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/readme.md

@@ -1,78 +1 @@
-# Quick start
-
-## Using Docker
-
-- Install [docker] and [docker-compose].
-- Grab Pomerium's included example [`docker-compose.yml`](https://raw.githubusercontent.com/pomerium/pomerium/master/docker-compose.yml) directly or by cloning the repository.
-- Update `docker-compose.yml` to match your [identity provider] settings.
-- Copy your subdomain's wild-card TLS certificate next to the compose file. If you don't have one handy, the included [script] generates one from [LetsEncrypt].
-- Run docker-compose by runnig the command `$ docker-compose up`.
-- Pomerium is configured to delegate access to two test apps [helloworld] and [httpbin]. Navigate to `hello.corp.example.com` or `httpbin.corp.example.com`. You should see something like the following in your browser and in your terminal.
-
-![Getting started](./get-started.gif)
-
-[![asciicast](https://asciinema.org/a/tfbSWkUZgMRxHAQDqmcjjNwUg.svg)](https://asciinema.org/a/tfbSWkUZgMRxHAQDqmcjjNwUg)
-
-## From source
-
-### Get the code
-
-Using [git](https://git-scm.com/), retrieve the latest copy of pomerium's source code by cloning the repository.
-
-```bash
-# where `$HOME/pomerium` is the directory you want to save pomerium
-git clone https://github.com/pomerium/pomerium.git $HOME/pomerium
-```
-
-Build pomerium from source in a single step using make.
-
-```bash
-cd $HOME/pomerium
-make
-```
-
-The command will run all the tests, some code linters, then build the binary. If all is good, you should now have a freshly built pomerium binary in the `pomerium/bin` directory.
-
-### Configure
-
-Make a copy of the [env.example] and name it something like `env`.
-
-```bash
-cp env.example env
-```
-
-Modify your `env` configuration to to match your [identity provider] settings.
-
-```bash
-vim env
-```
-
-### Run
-
-Finally, source the the configuration `env` file and run pomerium.
-
-```bash
-source ./env
-./bin/pomerium
-```
-
-### All-in-one
-
-Assuming your configuration file ready to go, you can simply use this one-liner.
-
-```bash
-make && source ./env && ./bin/pomerium
-```
-
-[certbot]: https://certbot.eff.org/docs/install.html
-[docker]: https://docs.docker.com/install/
-[docker-compose]: (https://docs.docker.com/compose/install/)
-[download]: https://github.com/pomerium/pomerium/releases
-[env.example]: https://github.com/pomerium/pomerium/blob/master/env.example
-[helloworld]: https://hub.docker.com/r/tutum/hello-world
-[httpbin]: https://httpbin.org/
-[identity provider]: ./identity-providers.md
-[kms]: https://en.wikipedia.org/wiki/Key_management
-[letsencrypt]: https://letsencrypt.org/
-[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
-[source]: https://github.com/pomerium/pomerium#start-developing
+# Prerequisites

proxy/handlers.go

@@ -46,6 +46,7 @@ func (p *Proxy) Handler() http.Handler {
 
 	// Middleware chain
 	c := middleware.NewChain()
+	c = c.Append(middleware.Healthcheck("/ping", version.UserAgent()))
 	c = c.Append(middleware.NewHandler(log.Logger))
 	c = c.Append(middleware.AccessHandler(func(r *http.Request, status, size int, duration time.Duration) {
 		middleware.FromRequest(r).Info().
@@ -58,7 +59,6 @@ func (p *Proxy) Handler() http.Handler {
 			Str("pomerium-email", r.Header.Get(HeaderEmail)).
 			Msg("request")
 	}))
-	c = c.Append(middleware.Healthcheck("/ping", version.UserAgent()))
 	c = c.Append(middleware.SetHeaders(securityHeaders))
 	c = c.Append(middleware.RequireHTTPS)
 	c = c.Append(middleware.ForwardedAddrHandler("fwd_ip"))

scripts/kubernetes_gke.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# NOTE! This will create real resources on Google's cloud. Make sure you clean up any unused
+# resources to avoid being billed. For reference, this tutorial cost me <10 cents for a couple of hours.
+
+# create a cluster
+gcloud container clusters create pomerium
+# get cluster credentials os we can use kubctl locally
+gcloud container clusters get-credentials pomerium
+# create `pomerium` namespace
+kubectl create ns pomerium
+
+# create our cryptographically random keys
+kubectl create secret generic -n pomerium shared-secret --from-literal=shared-secret=$(head -c32 /dev/urandom | base64)
+kubectl create secret generic -n pomerium cookie-secret --from-literal=cookie-secret=$(head -c32 /dev/urandom | base64)
+
+# load TLS for pomerium services
+kubectl create secret generic -n pomerium certificate --from-literal=certificate=$(base64 -i cert.pem)
+kubectl create secret generic -n pomerium certificate-key --from-literal=certificate-key=$(base64 -i privkey.pem)
+
+# load  TLS to ingress
+kubectl create secret tls -n pomerium pomerium-tls --key privkey.pem --cert cert.pem
+
+#                       !!! IMPORTANT !!!
+#          YOU MUST CHANGE THE Identity Provider Client Secret
+#                       !!! IMPORTANT !!!
+# kubectl create secret generic -n pomerium idp-client-secret --from-literal=REPLACE_ME
+
+# Create the proxy & authenticate deployment
+kubectl create -f docs/docs/examples/kubernetes/authenticate.deploy.yml
+kubectl create -f docs/docs/examples/kubernetes/proxy.deploy.yml
+# Create the proxy & authenticate services
+kubectl apply -f docs/docs/examples/kubernetes/proxy.service.yml
+kubectl apply -f docs/docs/examples/kubernetes/authenticate.service.yml
+# Create and apply the Ingress; this is GKE specific
+kubectl apply -f docs/docs/examples/kubernetes/ingress.yml
+
+# When done, clean up by deleting the cluster!
+# gcloud container clusters delete pomerium