From 8cae3f27bb5c9e7471e1ca6de7b047037385c26a Mon Sep 17 00:00:00 2001 From: bobby <1544881+desimone@users.noreply.github.com> Date: Thu, 30 Jul 2020 11:02:14 -0700 Subject: [PATCH] docs: refactor sections, consolidate examples (#1164) --- docs/.vuepress/config.js | 27 ++- docs/.vuepress/public/_redirects | 14 +- docs/configuration/examples.md | 171 ------------------ docs/docs/quick-start/binary.md | 4 +- docs/docs/quick-start/from-source.md | 2 +- docs/docs/quick-start/helm.md | 4 +- docs/docs/quick-start/kubernetes.md | 2 +- docs/docs/quick-start/readme.md | 6 +- docs/{recipes => guides}/ad-guard.md | 0 docs/{recipes => guides}/argo.md | 0 docs/{recipes => guides}/cloud-run.md | 0 .../img/adguard-dashboard.png | Bin .../img/adguard-router-setup.png | Bin .../img/cloud-run/cloudrun-domains.png | Bin .../img/cloud-run/cloudrun-overview.png | Bin .../img/cloud-run/headers.png | Bin .../img/cloud-run/hello-direct.png | Bin .../img/cloud-run/hello-signin.png | Bin .../img/cloud-run/hello-success.png | Bin .../img/k8s-dashboard-login.png | Bin .../img/k8s-fresh-dashboard.png | Bin .../img/k8s-fwd-auth-example.mp4 | Bin .../img/k8s-proxied-example.mp4 | Bin .../img/k8s-tesla-hacked.png | Bin .../mtls/01-chrome-settings-certificates.png | Bin .../img/mtls/02-import-client-certificate.png | Bin .../mtls/03-enter-certificate-password.png | Bin .../img/mtls/04-certificate-list.png | Bin .../img/mtls/05-select-client-certificate.png | Bin .../img/vscode-helloworld.png | Bin .../img/vscode-pomerium.png | Bin docs/guides/istio.md | 39 ++++ .../kubernetes-dashboard.md | 6 +- docs/{recipes => guides}/kubernetes.md | 0 docs/{recipes => guides}/local-oidc.md | 0 docs/{recipes => guides}/mtls.md | 0 docs/{recipes => guides}/readme.md | 0 docs/{recipes => guides}/tiddlywiki.md | 2 +- docs/{recipes => guides}/vs-code-server.md | 0 .../img/auth-flow-diagram.svg | 0 .../img/certificates-ssl-report.png | Bin .../certificates-valid-secure-certificate.png | Bin .../img/jaeger.png | Bin .../img/pomerium-user-impersonation.mp4 | Bin .../img/security-headers.png | Bin docs/{configuration => reference}/readme.md | 2 +- .../config/config.example.env | 0 .../config/config.example.yaml | 0 .../config/config.minimal.env | 0 .../config/config.minimal.yaml | 0 .../config/policy.example.yaml | 0 .../docker/autocert.docker-compose.yml | 0 .../docker/basic.docker-compose.yml | 0 .../docker/nginx.docker-compose.yml | 0 .../examples => examples}/helm/helm_gke.sh | 0 .../kubernetes/httpbin.yml | 0 .../kubernetes/ingress.nginx.yml | 0 .../kubernetes/ingress.yml | 0 .../kubernetes/istio/gateway.yml | 0 .../kubernetes/istio/grafana.ini.yml | 0 .../kubernetes/istio/pomerium-helm-values.yml | 0 .../kubernetes/istio/service-entry.yml | 0 .../kubernetes/istio/virtual-services.yml | 0 .../kubernetes/kubernetes-config.yaml | 0 .../kubernetes/kubernetes_gke.sh | 0 .../kubernetes/kubernetes_nginx.sh | 0 .../kubernetes/pomerium-authenticate.yml | 0 .../kubernetes/pomerium-authorize.yml | 0 .../kubernetes/pomerium-cache.yml | 0 .../kubernetes/pomerium-proxy.yml | 0 .../kubernetes/values.yaml | 0 .../yml/dashboard-forwardauth.ingress.yaml | 0 .../yml/dashboard-proxied.ingress.yaml | 0 .../yml/letsencrypt-prod.yaml | 0 74 files changed, 85 insertions(+), 194 deletions(-) delete mode 100644 docs/configuration/examples.md rename docs/{recipes => guides}/ad-guard.md (100%) rename docs/{recipes => guides}/argo.md (100%) rename docs/{recipes => guides}/cloud-run.md (100%) rename docs/{recipes => guides}/img/adguard-dashboard.png (100%) rename docs/{recipes => guides}/img/adguard-router-setup.png (100%) rename docs/{recipes => guides}/img/cloud-run/cloudrun-domains.png (100%) rename docs/{recipes => guides}/img/cloud-run/cloudrun-overview.png (100%) rename docs/{recipes => guides}/img/cloud-run/headers.png (100%) rename docs/{recipes => guides}/img/cloud-run/hello-direct.png (100%) rename docs/{recipes => guides}/img/cloud-run/hello-signin.png (100%) rename docs/{recipes => guides}/img/cloud-run/hello-success.png (100%) rename docs/{recipes => guides}/img/k8s-dashboard-login.png (100%) rename docs/{recipes => guides}/img/k8s-fresh-dashboard.png (100%) rename docs/{recipes => guides}/img/k8s-fwd-auth-example.mp4 (100%) rename docs/{recipes => guides}/img/k8s-proxied-example.mp4 (100%) rename docs/{recipes => guides}/img/k8s-tesla-hacked.png (100%) rename docs/{recipes => guides}/img/mtls/01-chrome-settings-certificates.png (100%) rename docs/{recipes => guides}/img/mtls/02-import-client-certificate.png (100%) rename docs/{recipes => guides}/img/mtls/03-enter-certificate-password.png (100%) rename docs/{recipes => guides}/img/mtls/04-certificate-list.png (100%) rename docs/{recipes => guides}/img/mtls/05-select-client-certificate.png (100%) rename docs/{recipes => guides}/img/vscode-helloworld.png (100%) rename docs/{recipes => guides}/img/vscode-pomerium.png (100%) create mode 100644 docs/guides/istio.md rename docs/{recipes => guides}/kubernetes-dashboard.md (98%) rename docs/{recipes => guides}/kubernetes.md (100%) rename docs/{recipes => guides}/local-oidc.md (100%) rename docs/{recipes => guides}/mtls.md (100%) rename docs/{recipes => guides}/readme.md (100%) rename docs/{recipes => guides}/tiddlywiki.md (96%) rename docs/{recipes => guides}/vs-code-server.md (100%) rename docs/{configuration => reference}/img/auth-flow-diagram.svg (100%) rename docs/{configuration => reference}/img/certificates-ssl-report.png (100%) rename docs/{configuration => reference}/img/certificates-valid-secure-certificate.png (100%) rename docs/{configuration => reference}/img/jaeger.png (100%) rename docs/{configuration => reference}/img/pomerium-user-impersonation.mp4 (100%) rename docs/{configuration => reference}/img/security-headers.png (100%) rename docs/{configuration => reference}/readme.md (99%) rename {docs/configuration/examples => examples}/config/config.example.env (100%) rename {docs/configuration/examples => examples}/config/config.example.yaml (100%) rename {docs/configuration/examples => examples}/config/config.minimal.env (100%) rename {docs/configuration/examples => examples}/config/config.minimal.yaml (100%) rename {docs/configuration/examples => examples}/config/policy.example.yaml (100%) rename {docs/configuration/examples => examples}/docker/autocert.docker-compose.yml (100%) rename {docs/configuration/examples => examples}/docker/basic.docker-compose.yml (100%) rename {docs/configuration/examples => examples}/docker/nginx.docker-compose.yml (100%) rename {docs/configuration/examples => examples}/helm/helm_gke.sh (100%) rename {docs/configuration/examples => examples}/kubernetes/httpbin.yml (100%) rename {docs/configuration/examples => examples}/kubernetes/ingress.nginx.yml (100%) rename {docs/configuration/examples => examples}/kubernetes/ingress.yml (100%) rename {docs/configuration/examples => examples}/kubernetes/istio/gateway.yml (100%) rename {docs/configuration/examples => examples}/kubernetes/istio/grafana.ini.yml (100%) rename {docs/configuration/examples => examples}/kubernetes/istio/pomerium-helm-values.yml (100%) rename {docs/configuration/examples => examples}/kubernetes/istio/service-entry.yml (100%) rename {docs/configuration/examples => examples}/kubernetes/istio/virtual-services.yml (100%) rename {docs/configuration/examples => examples}/kubernetes/kubernetes-config.yaml (100%) rename {docs/configuration/examples => examples}/kubernetes/kubernetes_gke.sh (100%) rename {docs/configuration/examples => examples}/kubernetes/kubernetes_nginx.sh (100%) rename {docs/configuration/examples => examples}/kubernetes/pomerium-authenticate.yml (100%) rename {docs/configuration/examples => examples}/kubernetes/pomerium-authorize.yml (100%) rename {docs/configuration/examples => examples}/kubernetes/pomerium-cache.yml (100%) rename {docs/configuration/examples => examples}/kubernetes/pomerium-proxy.yml (100%) rename {docs/configuration/examples => examples}/kubernetes/values.yaml (100%) rename {docs/recipes => examples}/yml/dashboard-forwardauth.ingress.yaml (100%) rename {docs/recipes => examples}/yml/dashboard-proxied.ingress.yaml (100%) rename {docs/recipes => examples}/yml/letsencrypt-prod.yaml (100%) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index f884bf101..b9c746572 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -42,8 +42,8 @@ module.exports = { lastUpdated: "Last Updated", nav: [ { text: "Documentation", link: "/docs/" }, - { text: "Configuration", link: "/configuration/" }, - { text: "Recipes", link: "/recipes/" }, + { text: "Reference", link: "/reference/" }, + { text: "Guides", link: "/guides/" }, { text: "Enterprise", link: "/enterprise/" }, { text: "v0.9.x", // current tagged version @@ -143,14 +143,25 @@ module.exports = { ], }, ], - "/recipes/": [ + "/guides/": [ { - title: "Recipes", + title: "Guides", type: "group", collapsable: false, sidebarDepth: 1, - children: ["", "ad-guard", "cloud-run", "vs-code-server", "kubernetes", "argo", "mtls", "local-oidc", "tiddlywiki"], + children: [ + "", + "ad-guard", + "argo", + "cloud-run", + "istio", + "kubernetes", + "local-oidc", + "mtls", + "tiddlywiki", + "vs-code-server", + ], }, ], "/enterprise/": [ @@ -162,13 +173,13 @@ module.exports = { children: [""], }, ], - "/configuration/": [ + "/reference/": [ { - title: "Configuration", + title: "", type: "group", collapsable: false, sidebarDepth: 1, - children: ["", "examples"], + children: [""], }, ], }, diff --git a/docs/.vuepress/public/_redirects b/docs/.vuepress/public/_redirects index d59882d46..b37c63e60 100644 --- a/docs/.vuepress/public/_redirects +++ b/docs/.vuepress/public/_redirects @@ -2,6 +2,9 @@ /docs/reference/reference.html /configuration/ /docs/configuration/ /configuration/ +/configuration/ /reference/ + + /community/ /docs/community/ /community/index.html /docs/community/ /community/contributing /docs/community/contributing.html @@ -13,7 +16,6 @@ /docs/reference/examples.html /configuration/examples.html -/reference/ /docs/reference/reference.html /guide/ /docs/quick-start/ /guide/kubernetes.html /docs/quick-start/kubernetes.html /guide/kubernetes /docs/quick-start/kubernetes.html @@ -21,3 +23,13 @@ /guide/synology.html /docs/quick-start/synology.html /docs/examples.html /recipes/ /docs/examples /recipes/ + +/recipes/ /guides/ +/recipes/ad-guard.html /guides/ad-guard.html +/recipes/argo.html /guides/argo.html +/recipes/cloud-run.html /guides/cloud-run.html +/recipes/istio.html /guides/istio.html +/recipes/kubernetes.html /guides/kubernetes.html +/recipes/local-oidc.html /guides/local-oidc.html +/recipes/mtls.html /guides/mtls.html +/recipes/vs-code-server.html /guides/vs-code-server.html \ No newline at end of file diff --git a/docs/configuration/examples.md b/docs/configuration/examples.md deleted file mode 100644 index 83f8119fa..000000000 --- a/docs/configuration/examples.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: Examples -lang: en-US -sidebarDepth: 2 -meta: - - name: keywords - content: pomerium community help bugs updates features -description: >- - This document describes how you users can stay up to date with pomerium, - report issues, get help, and suggest new features. ---- - -# Examples - -A collection of copy-and-paste-able configurations for various types of clouds, use-cases, and deployments. These files can also be found in the git repository in the `docs/configuration/examples/` directory. - -:::tip - -Remember to set your identity provider settings and to generate new secret keys! - -::: - -[[toc]] - -## Settings - -### Configuration File - -<<< @/docs/configuration/examples/config/config.example.yaml - -### Environmental Variables - -<<< @/docs/configuration/examples/config/config.example.env - -## 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 `./bin/pomerium -config config.yaml` - -## 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. - -### All-in-One - -- Minimal container-based configuration. -- Docker and Docker-Compose based. -- Runs a single container for all pomerium services -- Routes default to on-premise [httpbin]. - -Customize for your identity provider run `docker-compose up -f basic.docker-compose.yml` - -#### basic.docker-compose.yml - -<<< @/docs/configuration/examples/docker/basic.docker-compose.yml - -### Distinct Services - -- Docker and Docker-Compose based. -- Uses pre-configured built-in nginx load balancer -- Runs separate containers for each service -- Routes default to on-premise [helloworld], and [httpbin]. - -Customize for your identity provider run `docker-compose up -f nginx.docker-compose.yml` - -#### nginx.docker-compose.yml - -<<< @/docs/configuration/examples/docker/nginx.docker-compose.yml - -## Helm - -- HTTPS (TLS) between client, load balancer, and services -- gRPC requests are routed behind the load balancer -- Routes default to hosted version of httpbin.org -- Includes installer script -- Pomerium serves on HTTPS and your ingress controller may need an annotation to - connect properly - -### GKE - -- Uses Google Kubernetes Engine's built-in ingress to do [HTTPS load balancing] - -<<< @/docs/configuration/examples/helm/helm_gke.sh - -### Kubernetes - -- Uses Google Kubernetes Engine's built-in ingress to do [HTTPS load balancing] -- HTTPS (TLS) between client, load balancer, and services -- gRPC requests are routed behind the load balancer -- Routes default to hosted version of httpbin.org -- Includes installer script - -#### kubernetes_gke - -<<< @/docs/configuration/examples/kubernetes/kubernetes_gke.sh - -#### kubernetes-config.yaml - -<<< @/docs/configuration/examples/kubernetes/kubernetes-config.yaml - -#### pomerium-authenticate.yml - -<<< @/docs/configuration/examples/kubernetes/pomerium-authenticate.yml - -#### pomerium-authorize.yml - -<<< @/docs/configuration/examples/kubernetes/pomerium-authorize.yml - -#### pomerium-proxy.yml - -<<< @/docs/configuration/examples/kubernetes/pomerium-proxy.yml - -#### pomerium-cache.yml - -<<< @/docs/configuration/examples/kubernetes/pomerium-cache.yml - - -#### ingress.yml - -<<< @/docs/configuration/examples/kubernetes/ingress.yml - -[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 - -## Istio - -[istio]: https://github.com/istio/istio -[certmanager]: https://github.com/jetstack/cert-manager -[grafana]: https://github.com/grafana/grafana - -- Istio provides mutual TLS via sidecars and to make Istio play well with Pomerium we need to disable TLS on the Pomerium side. -- We need to provide Istio with information on how to route requests via Pomerium to their destinations. -- The following example shows how to make Grafana's [auth proxy](https://grafana.com/docs/grafana/latest/auth/auth-proxy) work with Pomerium inside of an Istio mesh. - -#### Gateway - -We are using the standard istio-ingressgateway that comes configured with Istio and attach a Gateway to it that deals with a subset of our ingress traffic based on the Host header (in this case `*.yourcompany.com`). This is the Gateway to which we will later attach VirtualServices for more granular routing decisions. Along with the Gateway, because we care about TLS, we are using Certmanager to provision a self-signed certificate (see Certmanager [docs](https://cert-manager.io/docs) for setup instructions). - -<<< @/docs/configuration/examples/kubernetes/istio/gateway.yml - -#### Virtual Services - -Here we are configuring two Virtual Services. One to route from the Gateway to the Authenticate service and one to route from the Gateway to the Pomerium Proxy, which will route the request to Grafana according to the configured Pomerium policy. - -<<< @/docs/configuration/examples/kubernetes/istio/virtual-services.yml - -#### Service Entry - -If you are enforcing mutual TLS in your service mesh you will need to add a ServiceEntry for your identity provider so that Istio knows not to expect a mutual TLS connection with, for example `https://yourcompany.okta.com`. - -<<< @/docs/configuration/examples/kubernetes/istio/service-entry.yml - -#### Pomerium Configuration - -For this example we're using the Pomerium Helm chart with the following `values.yaml` file. Things to note here are the `insecure` flag, where we are disabling TLS in Pomerium in favor of the Istio-provided TLS via sidecars. Also note the `extaEnv` arguments where we are asking Pomerium to extract the email property from the JWT and pass it on to Grafana in a header called `X-Pomerium-Claim-Email`. We need to do this because Grafana does not know how to read the Pomerium JWT but its auth-proxy authentication method can be configured to read user information from headers. The policy document contains a single route that will send all requests with a host header of `https://grafana.yourcompany.com` to the Grafana instance running in the monitoring namespace. We disable ingress because we are using the Istio ingressgateway for ingress traffic and don't need the Pomerium helm chart to create ingress objects for us. - -<<< @/docs/configuration/examples/kubernetes/istio/pomerium-helm-values.yml - -#### Grafana ini - -On the Grafana side we are using the Grafana Helm chart and what follows is the relevant section of the `values.yml` file. The most important thing here is that we need to tell Grafana from which request header to grab the username. In this case that's `X-Pomerium-Claim-Email` because we will be using the user's email (provided by your identity provider) as their username in Grafana. For all the configuration options check out the Grafana documentation about its auth-proxy authentication method. - -<<< @/docs/configuration/examples/kubernetes/istio/grafana.ini.yml diff --git a/docs/docs/quick-start/binary.md b/docs/docs/quick-start/binary.md index bec9e60af..95b103d01 100644 --- a/docs/docs/quick-start/binary.md +++ b/docs/docs/quick-start/binary.md @@ -27,13 +27,13 @@ Pomerium supports setting [configuration variables] using both environmental var Create a config file (`config.yaml`). This file will be used to determine Pomerium's configuration settings, routes, and access-policies. Consider the following example: -<<< @/docs/configuration/examples/config/config.minimal.yaml +<<< @/examples/config/config.minimal.yaml ### Environmental Variables As mentioned above, Pomerium supports mixing and matching configuration. For example, we can specify our secret values and domains certificates as [environmental configuration variables], and set the rest as part of the configuration file. -<<< @/docs/configuration/examples/config/config.minimal.env +<<< @/examples/config/config.minimal.env ## Run diff --git a/docs/docs/quick-start/from-source.md b/docs/docs/quick-start/from-source.md index 9fbf7335f..0b7bad1d1 100644 --- a/docs/docs/quick-start/from-source.md +++ b/docs/docs/quick-start/from-source.md @@ -57,7 +57,7 @@ Pomerium supports setting [configuration variables] using both environmental var Create a config file (`config.yaml`). This file will be use to determine Pomerium's configuration settings, routes, and access-policies. Consider the following example: -<<< @/docs/configuration/examples/config/config.minimal.yaml +<<< @/examples/config/config.minimal.yaml ## Run diff --git a/docs/docs/quick-start/helm.md b/docs/docs/quick-start/helm.md index ab942613a..9d62d94be 100644 --- a/docs/docs/quick-start/helm.md +++ b/docs/docs/quick-start/helm.md @@ -27,9 +27,9 @@ In addition to sharing many of the same features as the Kubernetes quickstart gu Download and modify the following helm_gke.sh script and values file to match your [identity provider] and [TLS certificates] settings. -<<<@/docs/configuration/examples/helm/helm_gke.sh +<<<@/examples/helm/helm_gke.sh -<<<@/docs/configuration/examples/kubernetes/values.yaml +<<<@/examples/kubernetes/values.yaml ## Run diff --git a/docs/docs/quick-start/kubernetes.md b/docs/docs/quick-start/kubernetes.md index 8ce12edc8..c552be909 100644 --- a/docs/docs/quick-start/kubernetes.md +++ b/docs/docs/quick-start/kubernetes.md @@ -31,7 +31,7 @@ cd $HOME/pomerium/docs/configuration/examples/kubernetes Edit [./kubernetes_gke.sh] making sure to change the identity provider secret value to match your [identity provider] and [TLS certificates] settings. -<<<@/docs/configuration/examples/kubernetes/kubernetes_gke.sh +<<<@/examples/kubernetes/kubernetes_gke.sh ## Run diff --git a/docs/docs/quick-start/readme.md b/docs/docs/quick-start/readme.md index 94011fc74..d1c1ac0ce 100644 --- a/docs/docs/quick-start/readme.md +++ b/docs/docs/quick-start/readme.md @@ -22,7 +22,7 @@ In the following quick-start, we'll create a minimal but complete environment fo Create a [configuration file] (e.g `config.yaml`) for defining Pomerium's configuration settings, routes, and access-policies. Consider the following example: -<<< @/docs/configuration/examples/config/config.minimal.yaml +<<< @/examples/config/config.minimal.yaml Ensure the `docker-compose.yml` contains the correct path to your `config.yaml`. @@ -36,7 +36,7 @@ Download the following `docker-compose.yml` file and modify it to: - mount your `config.yaml` [configuration file] - Set `autocert_use_staging` to `false` once you have finished testing -<<< @/docs/configuration/examples/docker/autocert.docker-compose.yml +<<< @/examples/docker/autocert.docker-compose.yml Please note that you should use a persistent volume to store certificate data, or you may exhaust your domain quota on Let's Encrypt. @@ -48,7 +48,7 @@ Download the following `docker-compose.yml` file and modify it to: - mount your [TLS certificates] - mount your `config.yaml` [configuration file] -<<< @/docs/configuration/examples/docker/basic.docker-compose.yml +<<< @/examples/docker/basic.docker-compose.yml ## Run diff --git a/docs/recipes/ad-guard.md b/docs/guides/ad-guard.md similarity index 100% rename from docs/recipes/ad-guard.md rename to docs/guides/ad-guard.md diff --git a/docs/recipes/argo.md b/docs/guides/argo.md similarity index 100% rename from docs/recipes/argo.md rename to docs/guides/argo.md diff --git a/docs/recipes/cloud-run.md b/docs/guides/cloud-run.md similarity index 100% rename from docs/recipes/cloud-run.md rename to docs/guides/cloud-run.md diff --git a/docs/recipes/img/adguard-dashboard.png b/docs/guides/img/adguard-dashboard.png similarity index 100% rename from docs/recipes/img/adguard-dashboard.png rename to docs/guides/img/adguard-dashboard.png diff --git a/docs/recipes/img/adguard-router-setup.png b/docs/guides/img/adguard-router-setup.png similarity index 100% rename from docs/recipes/img/adguard-router-setup.png rename to docs/guides/img/adguard-router-setup.png diff --git a/docs/recipes/img/cloud-run/cloudrun-domains.png b/docs/guides/img/cloud-run/cloudrun-domains.png similarity index 100% rename from docs/recipes/img/cloud-run/cloudrun-domains.png rename to docs/guides/img/cloud-run/cloudrun-domains.png diff --git a/docs/recipes/img/cloud-run/cloudrun-overview.png b/docs/guides/img/cloud-run/cloudrun-overview.png similarity index 100% rename from docs/recipes/img/cloud-run/cloudrun-overview.png rename to docs/guides/img/cloud-run/cloudrun-overview.png diff --git a/docs/recipes/img/cloud-run/headers.png b/docs/guides/img/cloud-run/headers.png similarity index 100% rename from docs/recipes/img/cloud-run/headers.png rename to docs/guides/img/cloud-run/headers.png diff --git a/docs/recipes/img/cloud-run/hello-direct.png b/docs/guides/img/cloud-run/hello-direct.png similarity index 100% rename from docs/recipes/img/cloud-run/hello-direct.png rename to docs/guides/img/cloud-run/hello-direct.png diff --git a/docs/recipes/img/cloud-run/hello-signin.png b/docs/guides/img/cloud-run/hello-signin.png similarity index 100% rename from docs/recipes/img/cloud-run/hello-signin.png rename to docs/guides/img/cloud-run/hello-signin.png diff --git a/docs/recipes/img/cloud-run/hello-success.png b/docs/guides/img/cloud-run/hello-success.png similarity index 100% rename from docs/recipes/img/cloud-run/hello-success.png rename to docs/guides/img/cloud-run/hello-success.png diff --git a/docs/recipes/img/k8s-dashboard-login.png b/docs/guides/img/k8s-dashboard-login.png similarity index 100% rename from docs/recipes/img/k8s-dashboard-login.png rename to docs/guides/img/k8s-dashboard-login.png diff --git a/docs/recipes/img/k8s-fresh-dashboard.png b/docs/guides/img/k8s-fresh-dashboard.png similarity index 100% rename from docs/recipes/img/k8s-fresh-dashboard.png rename to docs/guides/img/k8s-fresh-dashboard.png diff --git a/docs/recipes/img/k8s-fwd-auth-example.mp4 b/docs/guides/img/k8s-fwd-auth-example.mp4 similarity index 100% rename from docs/recipes/img/k8s-fwd-auth-example.mp4 rename to docs/guides/img/k8s-fwd-auth-example.mp4 diff --git a/docs/recipes/img/k8s-proxied-example.mp4 b/docs/guides/img/k8s-proxied-example.mp4 similarity index 100% rename from docs/recipes/img/k8s-proxied-example.mp4 rename to docs/guides/img/k8s-proxied-example.mp4 diff --git a/docs/recipes/img/k8s-tesla-hacked.png b/docs/guides/img/k8s-tesla-hacked.png similarity index 100% rename from docs/recipes/img/k8s-tesla-hacked.png rename to docs/guides/img/k8s-tesla-hacked.png diff --git a/docs/recipes/img/mtls/01-chrome-settings-certificates.png b/docs/guides/img/mtls/01-chrome-settings-certificates.png similarity index 100% rename from docs/recipes/img/mtls/01-chrome-settings-certificates.png rename to docs/guides/img/mtls/01-chrome-settings-certificates.png diff --git a/docs/recipes/img/mtls/02-import-client-certificate.png b/docs/guides/img/mtls/02-import-client-certificate.png similarity index 100% rename from docs/recipes/img/mtls/02-import-client-certificate.png rename to docs/guides/img/mtls/02-import-client-certificate.png diff --git a/docs/recipes/img/mtls/03-enter-certificate-password.png b/docs/guides/img/mtls/03-enter-certificate-password.png similarity index 100% rename from docs/recipes/img/mtls/03-enter-certificate-password.png rename to docs/guides/img/mtls/03-enter-certificate-password.png diff --git a/docs/recipes/img/mtls/04-certificate-list.png b/docs/guides/img/mtls/04-certificate-list.png similarity index 100% rename from docs/recipes/img/mtls/04-certificate-list.png rename to docs/guides/img/mtls/04-certificate-list.png diff --git a/docs/recipes/img/mtls/05-select-client-certificate.png b/docs/guides/img/mtls/05-select-client-certificate.png similarity index 100% rename from docs/recipes/img/mtls/05-select-client-certificate.png rename to docs/guides/img/mtls/05-select-client-certificate.png diff --git a/docs/recipes/img/vscode-helloworld.png b/docs/guides/img/vscode-helloworld.png similarity index 100% rename from docs/recipes/img/vscode-helloworld.png rename to docs/guides/img/vscode-helloworld.png diff --git a/docs/recipes/img/vscode-pomerium.png b/docs/guides/img/vscode-pomerium.png similarity index 100% rename from docs/recipes/img/vscode-pomerium.png rename to docs/guides/img/vscode-pomerium.png diff --git a/docs/guides/istio.md b/docs/guides/istio.md new file mode 100644 index 000000000..32dce609b --- /dev/null +++ b/docs/guides/istio.md @@ -0,0 +1,39 @@ +## Istio + +[istio]: https://github.com/istio/istio +[certmanager]: https://github.com/jetstack/cert-manager +[grafana]: https://github.com/grafana/grafana + +- Istio provides mutual TLS via sidecars and to make Istio play well with Pomerium we need to disable TLS on the Pomerium side. +- We need to provide Istio with information on how to route requests via Pomerium to their destinations. +- The following example shows how to make Grafana's [auth proxy](https://grafana.com/docs/grafana/latest/auth/auth-proxy) work with Pomerium inside of an Istio mesh. + +#### Gateway + +We are using the standard istio-ingressgateway that comes configured with Istio and attach a Gateway to it that deals with a subset of our ingress traffic based on the Host header (in this case `*.yourcompany.com`). This is the Gateway to which we will later attach VirtualServices for more granular routing decisions. Along with the Gateway, because we care about TLS, we are using Certmanager to provision a self-signed certificate (see Certmanager [docs](https://cert-manager.io/docs) for setup instructions). + +<<< @/examples/kubernetes/istio/gateway.yml + +#### Virtual Services + +Here we are configuring two Virtual Services. One to route from the Gateway to the Authenticate service and one to route from the Gateway to the Pomerium Proxy, which will route the request to Grafana according to the configured Pomerium policy. + +<<< @/examples/kubernetes/istio/virtual-services.yml + +#### Service Entry + +If you are enforcing mutual TLS in your service mesh you will need to add a ServiceEntry for your identity provider so that Istio knows not to expect a mutual TLS connection with, for example `https://yourcompany.okta.com`. + +<<< @/examples/kubernetes/istio/service-entry.yml + +#### Pomerium Configuration + +For this example we're using the Pomerium Helm chart with the following `values.yaml` file. Things to note here are the `insecure` flag, where we are disabling TLS in Pomerium in favor of the Istio-provided TLS via sidecars. Also note the `extaEnv` arguments where we are asking Pomerium to extract the email property from the JWT and pass it on to Grafana in a header called `X-Pomerium-Claim-Email`. We need to do this because Grafana does not know how to read the Pomerium JWT but its auth-proxy authentication method can be configured to read user information from headers. The policy document contains a single route that will send all requests with a host header of `https://grafana.yourcompany.com` to the Grafana instance running in the monitoring namespace. We disable ingress because we are using the Istio ingressgateway for ingress traffic and don't need the Pomerium helm chart to create ingress objects for us. + +<<< @/examples/kubernetes/istio/pomerium-helm-values.yml + +#### Grafana ini + +On the Grafana side we are using the Grafana Helm chart and what follows is the relevant section of the `values.yml` file. The most important thing here is that we need to tell Grafana from which request header to grab the username. In this case that's `X-Pomerium-Claim-Email` because we will be using the user's email (provided by your identity provider) as their username in Grafana. For all the configuration options check out the Grafana documentation about its auth-proxy authentication method. + +<<< @/examples/kubernetes/istio/grafana.ini.yml \ No newline at end of file diff --git a/docs/recipes/kubernetes-dashboard.md b/docs/guides/kubernetes-dashboard.md similarity index 98% rename from docs/recipes/kubernetes-dashboard.md rename to docs/guides/kubernetes-dashboard.md index 7112cd07b..651ef74d1 100644 --- a/docs/recipes/kubernetes-dashboard.md +++ b/docs/guides/kubernetes-dashboard.md @@ -155,7 +155,7 @@ Now that cert-manager is installed, we need to make one more configuration to be $ kubectl apply -f docs/recipes/yml/letsencrypt-prod.yaml ``` -<<< @/docs/recipes/yml/letsencrypt-prod.yaml +<<< @/examples/yml/letsencrypt-prod.yaml And confirm your issuer is set up correctly. @@ -301,13 +301,13 @@ Now we just need to tell external traffic how to route everything by deploying t $kubectl apply -f docs/recipes/yml/dashboard-forwardauth.ingress.yaml ``` -<<< @/docs/recipes/yml/dashboard-forwardauth.ingress.yaml +<<< @/examples/yml/dashboard-forwardauth.ingress.yaml ```sh $kubectl apply -f docs/recipes/yml/dashboard-proxied.ingress.yaml ``` -<<< @/docs/recipes/yml/dashboard-proxied.ingress.yaml +<<< @/examples/yml/dashboard-proxied.ingress.yaml And finally, check that the ingresses are up and running. diff --git a/docs/recipes/kubernetes.md b/docs/guides/kubernetes.md similarity index 100% rename from docs/recipes/kubernetes.md rename to docs/guides/kubernetes.md diff --git a/docs/recipes/local-oidc.md b/docs/guides/local-oidc.md similarity index 100% rename from docs/recipes/local-oidc.md rename to docs/guides/local-oidc.md diff --git a/docs/recipes/mtls.md b/docs/guides/mtls.md similarity index 100% rename from docs/recipes/mtls.md rename to docs/guides/mtls.md diff --git a/docs/recipes/readme.md b/docs/guides/readme.md similarity index 100% rename from docs/recipes/readme.md rename to docs/guides/readme.md diff --git a/docs/recipes/tiddlywiki.md b/docs/guides/tiddlywiki.md similarity index 96% rename from docs/recipes/tiddlywiki.md rename to docs/guides/tiddlywiki.md index 359a6f72b..b4dc4e9d4 100644 --- a/docs/recipes/tiddlywiki.md +++ b/docs/guides/tiddlywiki.md @@ -14,7 +14,7 @@ This guide covers using Pomerium to add authentication and authorization to an i ## What is TiddlyWiki on Node.js -TiddlyWiki is a personal wiki and a non-linear notebook for organising and sharing complex information. It is available in two forms: +TiddlyWiki is a personal wiki and a non-linear notebook for organizing and sharing complex information. It is available in two forms: - a single HTML page - [a Node.js application](https://www.npmjs.com/package/tiddlywiki) diff --git a/docs/recipes/vs-code-server.md b/docs/guides/vs-code-server.md similarity index 100% rename from docs/recipes/vs-code-server.md rename to docs/guides/vs-code-server.md diff --git a/docs/configuration/img/auth-flow-diagram.svg b/docs/reference/img/auth-flow-diagram.svg similarity index 100% rename from docs/configuration/img/auth-flow-diagram.svg rename to docs/reference/img/auth-flow-diagram.svg diff --git a/docs/configuration/img/certificates-ssl-report.png b/docs/reference/img/certificates-ssl-report.png similarity index 100% rename from docs/configuration/img/certificates-ssl-report.png rename to docs/reference/img/certificates-ssl-report.png diff --git a/docs/configuration/img/certificates-valid-secure-certificate.png b/docs/reference/img/certificates-valid-secure-certificate.png similarity index 100% rename from docs/configuration/img/certificates-valid-secure-certificate.png rename to docs/reference/img/certificates-valid-secure-certificate.png diff --git a/docs/configuration/img/jaeger.png b/docs/reference/img/jaeger.png similarity index 100% rename from docs/configuration/img/jaeger.png rename to docs/reference/img/jaeger.png diff --git a/docs/configuration/img/pomerium-user-impersonation.mp4 b/docs/reference/img/pomerium-user-impersonation.mp4 similarity index 100% rename from docs/configuration/img/pomerium-user-impersonation.mp4 rename to docs/reference/img/pomerium-user-impersonation.mp4 diff --git a/docs/configuration/img/security-headers.png b/docs/reference/img/security-headers.png similarity index 100% rename from docs/configuration/img/security-headers.png rename to docs/reference/img/security-headers.png diff --git a/docs/configuration/readme.md b/docs/reference/readme.md similarity index 99% rename from docs/configuration/readme.md rename to docs/reference/readme.md index c78b1a4b4..5def8fc0b 100644 --- a/docs/configuration/readme.md +++ b/docs/reference/readme.md @@ -844,7 +844,7 @@ The connection string that server will use to connect to storage backend. Policy contains route specific settings, and access control details. If you are configuring via POLICY environment variable, just the contents of the policy needs to be passed. If you are configuring via file, the policy should be present under the policy key. For example, -<<< @/docs/configuration/examples/config/policy.example.yaml +<<< @/examples/config/policy.example.yaml Policy routes are checked in the order they appear in the policy, so more specific routes should appear before less specific routes. For example: diff --git a/docs/configuration/examples/config/config.example.env b/examples/config/config.example.env similarity index 100% rename from docs/configuration/examples/config/config.example.env rename to examples/config/config.example.env diff --git a/docs/configuration/examples/config/config.example.yaml b/examples/config/config.example.yaml similarity index 100% rename from docs/configuration/examples/config/config.example.yaml rename to examples/config/config.example.yaml diff --git a/docs/configuration/examples/config/config.minimal.env b/examples/config/config.minimal.env similarity index 100% rename from docs/configuration/examples/config/config.minimal.env rename to examples/config/config.minimal.env diff --git a/docs/configuration/examples/config/config.minimal.yaml b/examples/config/config.minimal.yaml similarity index 100% rename from docs/configuration/examples/config/config.minimal.yaml rename to examples/config/config.minimal.yaml diff --git a/docs/configuration/examples/config/policy.example.yaml b/examples/config/policy.example.yaml similarity index 100% rename from docs/configuration/examples/config/policy.example.yaml rename to examples/config/policy.example.yaml diff --git a/docs/configuration/examples/docker/autocert.docker-compose.yml b/examples/docker/autocert.docker-compose.yml similarity index 100% rename from docs/configuration/examples/docker/autocert.docker-compose.yml rename to examples/docker/autocert.docker-compose.yml diff --git a/docs/configuration/examples/docker/basic.docker-compose.yml b/examples/docker/basic.docker-compose.yml similarity index 100% rename from docs/configuration/examples/docker/basic.docker-compose.yml rename to examples/docker/basic.docker-compose.yml diff --git a/docs/configuration/examples/docker/nginx.docker-compose.yml b/examples/docker/nginx.docker-compose.yml similarity index 100% rename from docs/configuration/examples/docker/nginx.docker-compose.yml rename to examples/docker/nginx.docker-compose.yml diff --git a/docs/configuration/examples/helm/helm_gke.sh b/examples/helm/helm_gke.sh similarity index 100% rename from docs/configuration/examples/helm/helm_gke.sh rename to examples/helm/helm_gke.sh diff --git a/docs/configuration/examples/kubernetes/httpbin.yml b/examples/kubernetes/httpbin.yml similarity index 100% rename from docs/configuration/examples/kubernetes/httpbin.yml rename to examples/kubernetes/httpbin.yml diff --git a/docs/configuration/examples/kubernetes/ingress.nginx.yml b/examples/kubernetes/ingress.nginx.yml similarity index 100% rename from docs/configuration/examples/kubernetes/ingress.nginx.yml rename to examples/kubernetes/ingress.nginx.yml diff --git a/docs/configuration/examples/kubernetes/ingress.yml b/examples/kubernetes/ingress.yml similarity index 100% rename from docs/configuration/examples/kubernetes/ingress.yml rename to examples/kubernetes/ingress.yml diff --git a/docs/configuration/examples/kubernetes/istio/gateway.yml b/examples/kubernetes/istio/gateway.yml similarity index 100% rename from docs/configuration/examples/kubernetes/istio/gateway.yml rename to examples/kubernetes/istio/gateway.yml diff --git a/docs/configuration/examples/kubernetes/istio/grafana.ini.yml b/examples/kubernetes/istio/grafana.ini.yml similarity index 100% rename from docs/configuration/examples/kubernetes/istio/grafana.ini.yml rename to examples/kubernetes/istio/grafana.ini.yml diff --git a/docs/configuration/examples/kubernetes/istio/pomerium-helm-values.yml b/examples/kubernetes/istio/pomerium-helm-values.yml similarity index 100% rename from docs/configuration/examples/kubernetes/istio/pomerium-helm-values.yml rename to examples/kubernetes/istio/pomerium-helm-values.yml diff --git a/docs/configuration/examples/kubernetes/istio/service-entry.yml b/examples/kubernetes/istio/service-entry.yml similarity index 100% rename from docs/configuration/examples/kubernetes/istio/service-entry.yml rename to examples/kubernetes/istio/service-entry.yml diff --git a/docs/configuration/examples/kubernetes/istio/virtual-services.yml b/examples/kubernetes/istio/virtual-services.yml similarity index 100% rename from docs/configuration/examples/kubernetes/istio/virtual-services.yml rename to examples/kubernetes/istio/virtual-services.yml diff --git a/docs/configuration/examples/kubernetes/kubernetes-config.yaml b/examples/kubernetes/kubernetes-config.yaml similarity index 100% rename from docs/configuration/examples/kubernetes/kubernetes-config.yaml rename to examples/kubernetes/kubernetes-config.yaml diff --git a/docs/configuration/examples/kubernetes/kubernetes_gke.sh b/examples/kubernetes/kubernetes_gke.sh similarity index 100% rename from docs/configuration/examples/kubernetes/kubernetes_gke.sh rename to examples/kubernetes/kubernetes_gke.sh diff --git a/docs/configuration/examples/kubernetes/kubernetes_nginx.sh b/examples/kubernetes/kubernetes_nginx.sh similarity index 100% rename from docs/configuration/examples/kubernetes/kubernetes_nginx.sh rename to examples/kubernetes/kubernetes_nginx.sh diff --git a/docs/configuration/examples/kubernetes/pomerium-authenticate.yml b/examples/kubernetes/pomerium-authenticate.yml similarity index 100% rename from docs/configuration/examples/kubernetes/pomerium-authenticate.yml rename to examples/kubernetes/pomerium-authenticate.yml diff --git a/docs/configuration/examples/kubernetes/pomerium-authorize.yml b/examples/kubernetes/pomerium-authorize.yml similarity index 100% rename from docs/configuration/examples/kubernetes/pomerium-authorize.yml rename to examples/kubernetes/pomerium-authorize.yml diff --git a/docs/configuration/examples/kubernetes/pomerium-cache.yml b/examples/kubernetes/pomerium-cache.yml similarity index 100% rename from docs/configuration/examples/kubernetes/pomerium-cache.yml rename to examples/kubernetes/pomerium-cache.yml diff --git a/docs/configuration/examples/kubernetes/pomerium-proxy.yml b/examples/kubernetes/pomerium-proxy.yml similarity index 100% rename from docs/configuration/examples/kubernetes/pomerium-proxy.yml rename to examples/kubernetes/pomerium-proxy.yml diff --git a/docs/configuration/examples/kubernetes/values.yaml b/examples/kubernetes/values.yaml similarity index 100% rename from docs/configuration/examples/kubernetes/values.yaml rename to examples/kubernetes/values.yaml diff --git a/docs/recipes/yml/dashboard-forwardauth.ingress.yaml b/examples/yml/dashboard-forwardauth.ingress.yaml similarity index 100% rename from docs/recipes/yml/dashboard-forwardauth.ingress.yaml rename to examples/yml/dashboard-forwardauth.ingress.yaml diff --git a/docs/recipes/yml/dashboard-proxied.ingress.yaml b/examples/yml/dashboard-proxied.ingress.yaml similarity index 100% rename from docs/recipes/yml/dashboard-proxied.ingress.yaml rename to examples/yml/dashboard-proxied.ingress.yaml diff --git a/docs/recipes/yml/letsencrypt-prod.yaml b/examples/yml/letsencrypt-prod.yaml similarity index 100% rename from docs/recipes/yml/letsencrypt-prod.yaml rename to examples/yml/letsencrypt-prod.yaml