Split documentation

docs/examples/external-auth/README.md

@@ -0,0 +1,75 @@
+# External Authentication
+
+### Overview
+
+The `auth-url` and `auth-signin` annotations allow you to use an external
+authentication provider to protect your Ingress resources.
+
+(Note, this annotation requires `nginx-ingress-controller v0.9.0` or greater.)
+
+### Key Detail
+
+This functionality is enabled by deploying multiple Ingress objects for a single host.
+One Ingress object has no special annotations and handles authentication.
+
+Other Ingress objects can then be annotated in such a way that require the user to
+authenticate against the first Ingress's endpoint, and can redirect `401`s to the
+same endpoint.
+
+Sample:
+
+```yaml
+...
+metadata:
+  name: application
+  annotations:
+    "ingress.kubernetes.io/auth-url": "https://$host/oauth2/auth"
+    "ingress.kubernetes.io/auth-signin": "https://$host/oauth2/sign_in"
+...
+```
+
+### Example: OAuth2 Proxy + Kubernetes-Dashboard
+
+This example will show you how to deploy [`oauth2_proxy`](https://github.com/bitly/oauth2_proxy)
+into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using github as oAuth2 provider
+
+#### Prepare
+
+1. Install the kubernetes dashboard
+
+```console
+kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.5.0.yaml
+```
+
+2. Create a custom Github OAuth application https://github.com/settings/applications/new
+
+![Register OAuth2 Application](images/register-oauth-app.png)
+
+- Homepage URL is the FQDN in the Ingress rule, like `https://foo.bar.com`
+- Authorization callback URL is the same as the base FQDN plus `/oauth2`, like `https://foo.bar.com/oauth2`
+
+![Register OAuth2 Application](images/register-oauth-app-2.png)
+
+3. Configure oauth2_proxy values in the file oauth2-proxy.yaml with the values:
+
+- OAUTH2_PROXY_CLIENT_ID with the github `<Client ID>`
+- OAUTH2_PROXY_CLIENT_SECRET with the github `<Client Secret>`
+- OAUTH2_PROXY_COOKIE_SECRET with value of `python -c 'import os,base64; print base64.b64encode(os.urandom(16))'`      
+
+4. Customize the contents of the file dashboard-ingress.yaml:
+
+Replace `__INGRESS_HOST__` with a valid FQDN and `__INGRESS_SECRET__` with a Secret with a valid SSL certificate.
+
+5. Deploy the oauth2 proxy and the ingress rules running:
+
+```console
+$ kubectl create -f oauth2-proxy.yaml,dashboard-ingress.yaml
+```
+
+Test the oauth integration accessing the configured URL, like `https://foo.bar.com`
+
+![Register OAuth2 Application](images/github-auth.png)
+
+![Github authentication](images/oauth-login.png)
+
+![Kubernetes dashboard](images/dashboard.png)

docs/examples/external-auth/dashboard-ingress.yaml

@@ -0,0 +1,38 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  annotations:
+    ingress.kubernetes.io/auth-signin: https://$host/oauth2/start
+    ingress.kubernetes.io/auth-url: https://$host/oauth2/auth
+  name: external-auth-oauth2
+  namespace: kube-system
+spec:
+  rules:
+  - host: __INGRESS_HOST__
+    http:
+      paths:
+      - backend:
+          serviceName: kubernetes-dashboard
+          servicePort: 80
+        path: /
+
+---
+
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  name: oauth2-proxy
+  namespace: kube-system
+spec:
+  rules:
+  - host: __INGRESS_HOST__
+    http:
+      paths:
+      - backend:
+          serviceName: oauth2-proxy
+          servicePort: 4180
+        path: /oauth2
+  tls:
+  - hosts:
+    - __INGRESS_HOST__
+    secretName: __INGRESS_SECRET__

docs/examples/external-auth/oauth2-proxy.yaml

@@ -0,0 +1,56 @@
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  labels:
+    k8s-app: oauth2-proxy
+  name: oauth2-proxy
+  namespace: kube-system
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      k8s-app: oauth2-proxy
+  template:
+    metadata:
+      labels:
+        k8s-app: oauth2-proxy
+    spec:
+      containers:
+      - args:
+        - --provider=github
+        - --email-domain=*
+        - --upstream=file:///dev/null
+        - --http-address=0.0.0.0:4180
+        # Register a new application
+        # https://github.com/settings/applications/new
+        env:
+        - name: OAUTH2_PROXY_CLIENT_ID
+          value: <Client ID>
+        - name: OAUTH2_PROXY_CLIENT_SECRET
+          value: <Client Secret>
+        # python -c 'import os,base64; print base64.b64encode(os.urandom(16))'
+        - name: OAUTH2_PROXY_COOKIE_SECRET
+          value: SECRET
+        image: docker.io/colemickens/oauth2_proxy:latest
+        imagePullPolicy: Always
+        name: oauth2-proxy
+        ports:
+        - containerPort: 4180
+          protocol: TCP
+
+---
+
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    k8s-app: oauth2-proxy
+  name: oauth2-proxy
+spec:
+  ports:
+  - name: http
+    port: 4180
+    protocol: TCP
+    targetPort: 4180
+  selector:
+    k8s-app: oauth2-proxy