docs: refactor sections, consolidate examples (#1164)

examples/kubernetes/httpbin.yml

@@ -0,0 +1,37 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: httpbin
+  labels:
+    app: httpbin
+spec:
+  type: NodePort
+  ports:
+    - name: http
+      port: 8000
+      targetPort: 80
+  selector:
+    app: httpbin
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: httpbin
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: httpbin
+      version: v1
+  template:
+    metadata:
+      labels:
+        app: httpbin
+        version: v1
+    spec:
+      containers:
+        - image: docker.io/kennethreitz/httpbin
+          imagePullPolicy: IfNotPresent
+          name: httpbin
+          ports:
+            - containerPort: 80

examples/kubernetes/ingress.nginx.yml

@@ -0,0 +1,37 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  name: pomerium-ingress
+  annotations:
+    kubernetes.io/ingress.class: "nginx"
+    # kubernetes.io/tls-acme: "true"
+    # certmanager.k8s.io/issuer: "letsencrypt-prod"
+    # nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
+    # nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
+    # nginx.ingress.kubernetes.io/proxy-buffer-size: "16k"
+    # to avoid ingress routing, enable
+    # nginx.ingress.kubernetes.io/ssl-passthrough: "true"
+
+spec:
+  tls:
+    - secretName: pomerium-tls
+      hosts:
+        - "*.corp.beyondperimeter.com"
+        - "authenticate.corp.beyondperimeter.com"
+
+  rules:
+    - host: "*.corp.beyondperimeter.com"
+      http:
+        paths:
+          - paths:
+            backend:
+              serviceName: pomerium-proxy-service
+              servicePort: http
+
+    - host: "authenticate.corp.beyondperimeter.com"
+      http:
+        paths:
+          - paths:
+            backend:
+              serviceName: pomerium-authenticate-service
+              servicePort: http

examples/kubernetes/ingress.yml

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

examples/kubernetes/istio/gateway.yml

@@ -0,0 +1,41 @@
+apiVersion: networking.istio.io/v1alpha3
+kind: Gateway
+metadata:
+  name: internal-gateway
+  namespace: istio-system
+spec:
+  selector:
+    istio: ingressgateway
+  servers:
+  - port:
+      number: 443
+      protocol: HTTPS
+      name: https-default
+    tls:
+      mode: SIMPLE
+      serverCertificate: "sds"
+      privateKey: "sds"
+      credentialName: internal-cert
+    hosts:
+    - *.yourcompany.com
+---
+apiVersion: cert-manager.io/v1alpha2
+kind: Certificate
+metadata:
+  name: internal-cert
+  namespace: istio-system
+spec:
+  secretName: internal-cert
+  issuerRef:
+    name: self-signed-issuer
+    kind: ClusterIssuer
+  commonName: *.yourcompany.com
+  dnsNames:
+    - *.yourcompany.com
+---
+apiVersion: cert-manager.io/v1alpha2
+kind: ClusterIssuer
+metadata:
+  name: self-signed-issuer
+spec:
+  selfSigned: {}

examples/kubernetes/istio/grafana.ini.yml

@@ -0,0 +1,12 @@
+grafana.ini:
+  users:
+    allow_sign_up: false
+    auto_assign_org: true
+    auto_assign_org_role: Editor
+  auth.proxy:
+    enabled: true
+    header_name: X-Pomerium-Claim-Email
+    header_property: username
+    auto_sign_up: true
+    sync_ttl: 60
+    enable_login_token: false

examples/kubernetes/istio/pomerium-helm-values.yml

@@ -0,0 +1,13 @@
+config:
+  insecure: true
+  policy:
+    - from: https://grafana.yourcompany.com
+      to: "http://prometheus-grafana.monitoring.svc.cluster.local"
+      timeout: 30s
+      allowed_domains:
+        - yourcompany.com
+ingress:
+  enabled: false
+
+extraEnv:
+  JWT_CLAIMS_HEADERS: email

examples/kubernetes/istio/service-entry.yml

@@ -0,0 +1,14 @@
+apiVersion: networking.istio.io/v1alpha3
+kind: ServiceEntry
+metadata:
+  name: external-idp
+  namespace: pomerium
+spec:
+  hosts:
+    - yourcompany.okta.com
+  location: MESH_EXTERNAL
+  ports:
+    - number: 443
+      name: https
+      protocol: TLS
+  resolution: DNS

examples/kubernetes/istio/virtual-services.yml

@@ -0,0 +1,34 @@
+apiVersion: networking.istio.io/v1beta1
+kind: VirtualService
+metadata:
+  name: grafana-virtual-service
+  namespace: pomerium
+spec:
+  gateways:
+    - istio-system/internal-gateway
+  hosts:
+    - grafana.yourcompany.com
+  http:
+    - route:
+        - destination:
+            host: pomerium-proxy
+            port:
+              number: 80
+---
+apiVersion: networking.istio.io/v1beta1
+kind: VirtualService
+metadata:
+  name: authenticate-virtual-service
+  namespace: pomerium
+spec:
+  gateways:
+    - istio-system/internal-gateway
+  hosts:
+    - authenticate.yourcompany.com
+  http:
+    - route:
+        - destination:
+            host: pomerium-authenticate
+            port:
+              number: 80
+---

examples/kubernetes/kubernetes-config.yaml

@@ -0,0 +1,24 @@
+# Main configuration flags : https://www.pomerium.io/docs/reference/reference/
+insecure_server: true
+grpc_insecure: true
+address: ":80"
+grpc_address: ":80"
+
+authenticate_service_url: https://authenticate.corp.beyondperimeter.com
+authorize_service_url: http://pomerium-authorize-service.default.svc.cluster.local
+cache_service_url: http://pomerium-cache-service.default.svc.cluster.local
+
+override_certificate_name: "*.corp.beyondperimeter.com"
+
+idp_provider: google
+idp_client_id: REPLACE_ME.apps.googleusercontent.com
+idp_client_secret: "REPLACE_ME"
+# Required for group data
+# https://www.pomerium.com/configuration/#identity-provider-service-account
+idp_service_account: YOUR_SERVICE_ACCOUNT
+
+policy:
+  - from: https://httpbin.corp.beyondperimeter.com
+    to: http://httpbin.default.svc.cluster.local:8000
+    allowed_domains:
+      - gmail.com

examples/kubernetes/kubernetes_gke.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# NOTE! This will create real resources on Google GCP. Make sure you clean up any unused
+# resources to avoid being billed.
+# For reference, this tutorial cost ~10 cents for a couple of hours.
+# NOTE! You must change the identity provider client secret setting in your config file!
+
+echo "=> creating cluster"
+gcloud container clusters create pomerium --num-nodes 3 --region us-west2
+
+echo "=> get cluster credentials so we can use kubctl locally"
+gcloud container clusters get-credentials pomerium --region us-west2
+
+echo "=> create config from kubernetes-config.yaml which we will mount"
+kubectl create configmap config --from-file="config.yaml"="kubernetes-config.yaml"
+
+echo "=> create our random shared-secret and cookie-secret keys as envars"
+kubectl create secret generic shared-secret --from-literal=shared-secret=$(head -c32 /dev/urandom | base64)
+kubectl create secret generic cookie-secret --from-literal=cookie-secret=$(head -c32 /dev/urandom | base64)
+
+echo "=> initiliaze secrets for TLS wild card for service use"
+kubectl create secret generic certificate \
+	--from-literal=certificate=$(base64 -i "$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer")
+kubectl create secret generic certificate-key \
+	--from-literal=certificate-key=$(base64 -i "$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key")
+
+echo "=> load TLS to ingress"
+kubectl create secret tls pomerium-tls \
+	--key "$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key" \
+	--cert "$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer"
+
+echo "=> deploy pomerium proxy, authorize, and authenticate"
+kubectl apply -f pomerium-proxy.yml
+kubectl apply -f pomerium-authenticate.yml
+kubectl apply -f pomerium-authorize.yml
+kubectl apply -f pomerium-cache.yml
+
+echo "=> deploy our test app, httpbin"
+kubectl apply -f httpbin.yml
+
+echo "=> deploy the GKE specific ingress"
+kubectl apply -f ingress.yml
+
+# Alternatively, nginx-ingress can be used
+# kubectl apply -f ingress.nginx.yml
+
+# When done, clean up by deleting the cluster!
+# gcloud container clusters delete pomerium

examples/kubernetes/kubernetes_nginx.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+echo "=> create config from kubernetes-config.yaml which we will mount"
+kubectl create configmap config --from-file="config.yaml"="kubernetes-config.yaml"
+
+echo "=> create our random shared-secret and cookie-secret keys as envars"
+kubectl create secret generic shared-secret --from-literal=shared-secret=$(head -c32 /dev/urandom | base64)
+kubectl create secret generic cookie-secret --from-literal=cookie-secret=$(head -c32 /dev/urandom | base64)
+
+echo "=> deploy pomerium proxy, authorize, and authenticate"
+kubectl apply -f pomerium-proxy.yml
+kubectl apply -f pomerium-authenticate.yml
+kubectl apply -f pomerium-authorize.yml
+
+echo "=> deploy our test app, httpbin"
+kubectl apply -f httpbin.yml
+
+echo "=> deploy nginx-ingress"
+kubectl apply -f ingress.yml

examples/kubernetes/pomerium-authenticate.yml

@@ -0,0 +1,69 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: pomerium-authenticate-service
+spec:
+  ports:
+    - port: 80
+      name: http
+  selector:
+    app: pomerium-authenticate
+  type: NodePort
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: pomerium-authenticate
+  labels:
+    app: pomerium-authenticate
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: pomerium-authenticate
+  template:
+    metadata:
+      labels:
+        app: pomerium-authenticate
+    spec:
+      containers:
+        - image: pomerium/pomerium:master
+          name: pomerium-authenticate
+          args:
+            - --config=/etc/pomerium/config.yaml
+          ports:
+            - containerPort: 80
+              name: http
+              protocol: TCP
+          env:
+            - name: SERVICES
+              value: authenticate
+            - name: SHARED_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: shared-secret
+                  key: shared-secret
+            - name: COOKIE_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: cookie-secret
+                  key: cookie-secret
+          readinessProbe:
+            httpGet:
+              path: /ping
+              port: 80
+              scheme: HTTP
+          livenessProbe:
+            httpGet:
+              path: /ping
+              port: 80
+              scheme: HTTP
+            initialDelaySeconds: 5
+            timeoutSeconds: 1
+          volumeMounts:
+            - mountPath: /etc/pomerium/
+              name: config
+      volumes:
+        - name: config
+          configMap:
+            name: config

examples/kubernetes/pomerium-authorize.yml

@@ -0,0 +1,63 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: pomerium-authorize-service
+spec:
+  ports:
+    - port: 80
+      name: grpc
+  selector:
+    app: pomerium-authorize
+  type: ClusterIP
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: pomerium-authorize
+  labels:
+    app: pomerium-authorize
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: pomerium-authorize
+  template:
+    metadata:
+      labels:
+        app: pomerium-authorize
+    spec:
+      containers:
+        - image: pomerium/pomerium:master
+          name: pomerium-authorize
+          args:
+            - --config=/etc/pomerium/config.yaml
+          ports:
+            - containerPort: 80
+              name: grpc
+              protocol: TCP
+          env:
+            - name: SERVICES
+              value: authorize
+            - name: SHARED_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: shared-secret
+                  key: shared-secret
+          readinessProbe:
+            tcpSocket:
+              port: 80
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          livenessProbe:
+            tcpSocket:
+              port: 80
+            initialDelaySeconds: 15
+            periodSeconds: 20
+
+          volumeMounts:
+            - mountPath: /etc/pomerium/
+              name: config
+      volumes:
+        - name: config
+          configMap:
+            name: config

examples/kubernetes/pomerium-cache.yml

@@ -0,0 +1,64 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: pomerium-cache-service
+spec:
+  clusterIP: None # cache is a headless service!
+  ports:
+    - port: 80
+      name: grpc
+  selector:
+    app: pomerium-cache
+  type: ClusterIP
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: pomerium-cache
+  labels:
+    app: pomerium-cache
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: pomerium-cache
+  template:
+    metadata:
+      labels:
+        app: pomerium-cache
+    spec:
+      containers:
+        - image: pomerium/pomerium:master
+          name: pomerium-cache
+          args:
+            - --config=/etc/pomerium/config.yaml
+          ports:
+            - containerPort: 80
+              name: grpc
+              protocol: TCP
+          env:
+            - name: SERVICES
+              value: cache
+            - name: SHARED_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: shared-secret
+                  key: shared-secret
+          readinessProbe:
+            tcpSocket:
+              port: 80
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          livenessProbe:
+            tcpSocket:
+              port: 80
+            initialDelaySeconds: 15
+            periodSeconds: 20
+
+          volumeMounts:
+            - mountPath: /etc/pomerium/
+              name: config
+      volumes:
+        - name: config
+          configMap:
+            name: config

examples/kubernetes/pomerium-proxy.yml

@@ -0,0 +1,71 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: pomerium-proxy-service
+spec:
+  ports:
+    - port: 80
+      protocol: TCP
+      name: http
+      targetPort: http
+  selector:
+    app: pomerium-proxy
+  type: NodePort
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: pomerium-proxy
+  labels:
+    app: pomerium-proxy
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: pomerium-proxy
+  template:
+    metadata:
+      labels:
+        app: pomerium-proxy
+    spec:
+      containers:
+        - image: pomerium/pomerium:master
+          name: pomerium-proxy
+          args:
+            - --config=/etc/pomerium/config.yaml
+          ports:
+            - containerPort: 80
+              name: http
+              protocol: TCP
+          env:
+            - name: SERVICES
+              value: proxy
+            - name: SHARED_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: shared-secret
+                  key: shared-secret
+            - name: COOKIE_SECRET
+              valueFrom:
+                secretKeyRef:
+                  name: cookie-secret
+                  key: cookie-secret
+          readinessProbe:
+            httpGet:
+              path: /ping
+              port: 80
+              scheme: HTTP
+          livenessProbe:
+            httpGet:
+              path: /ping
+              port: 80
+              scheme: HTTP
+            initialDelaySeconds: 10
+            timeoutSeconds: 1
+          volumeMounts:
+            - mountPath: /etc/pomerium/
+              name: config
+      volumes:
+        - name: config
+          configMap:
+            name: config

examples/kubernetes/values.yaml

@@ -0,0 +1,31 @@
+authenticate:
+  idp:
+    provider: "google"
+    clientID: YOUR_CLIENT_ID
+    clientSecret: YOUR_SECRET
+    # Required for group data
+    # https://www.pomerium.com/configuration/#identity-provider-service-account
+    serviceAccount: YOUR_SERVICE_ACCOUNT 
+  service:
+    annotations:
+      cloud.google.com/app-protocols: '{"https":"HTTPS"}'
+
+proxy:
+  service:
+    annotations:
+      cloud.google.com/app-protocols: '{"https":"HTTPS"}'
+
+service:
+  type: NodePort
+
+config:
+  rootDomain: corp.beyondperimeter.com
+  policy:
+    - from: https://hello.corp.beyondperimeter.com
+      to: http://nginx.default.svc.cluster.local:80
+      allowed_domains:
+        - gmail.com
+
+ingress:
+  annotations:
+    kubernetes.io/ingress.allow-http: "false"