Updates and extends client cert documentation (#2105)

Updates and extends the documentation about enabling client certificate authentication.

docs/examples/README.md

@@ -21,6 +21,7 @@ Name | Description | Complexity Level
 Name | Description | Complexity Level
 -----| ----------- | ----------------
 [Basic auth](auth/basic/README.md) | password protect your website | nginx | Intermediate
+[Client certificate authentication](auth/client-certs/README.md) | secure your website with client certificate authentication | nginx | Intermediate
 [External auth plugin](external-auth/README.md) | defer to an external auth service | Intermediate
 
 ## Customization

docs/examples/auth/client-certs/README.md

@@ -0,0 +1,11 @@
+# Client Certificate Authentication
+
+It is possible to enable Client Certificate Authentication using additional annotations in the Ingress.
+
+## Setup instructions
+1. Create a file named `ca.crt` containing the trusted certificate authority chain (all ca certificates in PEM format) to verify client certificates. 
+ 
+2. Create a secret from this file:
+`kubectl create secret generic auth-tls-chain --from-file=ca.crt --namespace=default`
+
+3. Add the annotations as provided in the [ingress.yaml](ingress.yaml) example to your ingress object.

docs/examples/auth/client-certs/ingress.yaml

@@ -0,0 +1,30 @@
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  annotations:
+    # Enable client certificate authentication
+    nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
+    # Create the secret containing the trusted ca certificates with `kubectl create secret generic auth-tls-chain --from-file=ca.crt --namespace=default`
+    nginx.ingress.kubernetes.io/auth-tls-secret: "default/auth-tls-chain"
+    # Specify the verification depth in the client certificates chain
+    nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
+    # Specify an error page to be redirected to on verification errors
+    nginx.ingress.kubernetes.io/auth-tls-error-page: "http://www.mysite.com/error-cert.html"
+    # Specify if certificates are be passed to upstream server
+    nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "false"
+  name: nginx-test
+  namespace: default
+spec:
+  rules:
+  - host: ingress.test.com
+    http:
+      paths:
+      - backend:
+          serviceName: http-svc:80
+          servicePort: 80
+        path: /
+  tls:
+  - hosts:
+    - ingress.test.com
+    secretName: tls-secret
+

docs/examples/auth/client-certs/nginx-tls-auth.yaml

@@ -1,25 +0,0 @@
-apiVersion: extensions/v1beta1
-kind: Ingress
-metadata:
-  annotations:
-    # Create this with kubectl create secret generic caingress --from-file=ca.crt --namespace=default
-    nginx.ingress.kubernetes.io/auth-tls-secret: "default/caingress"
-    nginx.ingress.kubernetes.io/auth-tls-verify-depth: "3"
-    nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
-    auth-tls-error-page: "http://www.mysite.com/error-cert.html"
-  name: nginx-test
-  namespace: default
-spec:
-  rules:
-  - host: ingress.test.com
-    http:
-      paths:
-      - backend:
-          serviceName: http-svc:80
-          servicePort: 80
-        path: /
-  tls:
-  - hosts:
-    - ingress.test.com
-    secretName: tls-secret
-