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
-

docs/user-guide/annotations.md

@@ -139,9 +139,9 @@ To enable consistent hashing for a backend:
 
 This configuration setting allows you to control the value for host in the following statement: `proxy_set_header Host $host`, which forms part of the location block.  This is useful if you need to call the upstream server by something other than `$host`.
 
-### Certificate Authentication
+### Client Certificate Authentication
 
-It's possible to enable Certificate-Based Authentication (Mutual Authentication) using additional annotations in Ingress Rule.
+It is possible to enable Client Certificate Authentication using additional annotations in Ingress Rule.
 
 The annotations are:
 ```
@@ -175,7 +175,7 @@ nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream
 Indicates if the received certificates should be passed or not to the upstream server.
 By default this is disabled.
 
-Please check the [tls-auth](../examples/auth/client-certs/README.md) example.
+Please check the [client-certs](../examples/auth/client-certs/README.md) example.
 
 **Important:**