Merge pull request kubernetes#3978 from aledbf/ca-cert-docs

Fix CA certificate example docs

docs/examples/PREREQUISITES.md

@@ -24,7 +24,7 @@ Note: If using CA Authentication, described below, you will need to sign the ser
 ## Client Certificate Authentication
 
 CA Authentication also known as Mutual Authentication allows both the server and client to verify each others
-identity via a common CA. 
+identity via a common CA.
 
 We have a CA Certificate which we obtain usually from a Certificate Authority and use that to sign
 both our server certificate and client certificate. Then every time we want to access our backend, we must
@@ -33,17 +33,26 @@ pass the client certificate.
 These instructions are based on the following [blog](https://medium.com/@awkwardferny/configuring-certificate-based-mutual-authentication-with-kubernetes-ingress-nginx-20e7e38fdfca)
 
 **Generate the CA Key and Certificate:**
-$ openssl req -x509 -sha256 -newkey rsa:4096 -keyout ca.key -out ca.crt -days 356 -nodes -subj '/CN=My Cert Authority'
+
+```console
+openssl req -x509 -sha256 -newkey rsa:4096 -keyout ca.key -out ca.crt -days 356 -nodes -subj '/CN=My Cert Authority'
+```
 
 **Generate the Server Key, and Certificate and Sign with the CA Certificate:**
-$ openssl req -new -newkey rsa:4096 -keyout server.key -out server.csr -nodes -subj '/CN=mydomain.com'
-$ openssl x509 -req -sha256 -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt
+
+```console
+openssl req -new -newkey rsa:4096 -keyout server.key -out server.csr -nodes -subj '/CN=mydomain.com'
+openssl x509 -req -sha256 -days 365 -in server.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out server.crt
+```
 
 **Generate the Client Key, and Certificate and Sign with the CA Certificate:**
-$ openssl req -new -newkey rsa:4096 -keyout client.key -out client.csr -nodes -subj '/CN=My Client'
-$ openssl x509 -req -sha256 -days 365 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 02 -out client.crt
 
-Once this is complete you can continue to follow the instructions [here](./auth/client-certs/README.md)
+```console
+openssl req -new -newkey rsa:4096 -keyout client.key -out client.csr -nodes -subj '/CN=My Client'
+openssl x509 -req -sha256 -days 365 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 02 -out client.crt
+```
+
+Once this is complete you can continue to follow the instructions [here](./auth/client-certs/README.md#creating-certificate-secrets)
 
 ## Test HTTP Service
 

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

@@ -7,15 +7,18 @@ Before getting started you must have the following Certificates Setup:
 2. Server Certificate(Signed by CA) and Key (CN should be equal the hostname you will use)
 3. Client Certificate(Signed by CA) and Key
 
-For more details on the generation process, checkout the Prerequisite [docs](../../PREREQUISITES.md).
+For more details on the generation process, checkout the Prerequisite [docs](../../PREREQUISITES.md#client-certificate-authentication).
 
 You can have as many certificates as you want. If they're in the binary DER format, you can convert them as the following:
+
 ```bash
-$ openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem
+openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem
 ```
+
 Then, you can concatenate them all in only one file, named 'ca.crt' as the following:
+
 ```bash
-$ cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt
+cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt
 ```
 
 **Note:** Make sure that the Key Size is greater than 1024 and Hashing Algorithm(Digest) is something better than md5
@@ -28,22 +31,23 @@ Authentication to work properly.
 
 1. You can create a secret containing just the CA certificate and another
     Secret containing the Server Certificate which is Signed by the CA.
+
     ```bash
-    $ kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt
-    $ kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key
+    kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt
+    kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key
     ```
 
 2. You can create a secret containing CA certificate along with the Server
     Certificate, that can be used for both TLS and Client Auth.
+
     ```bash
-    $ kubectl create secret generic ca-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key --from-file=ca.crt=ca.crt
+    kubectl create secret generic ca-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key --from-file=ca.crt=ca.crt
     ```
-    
+
 Note: The CA Certificate must contain the trusted certificate authority chain to verify client certificates.
-    
+
 ## Setup Instructions
 
 1. Add the annotations as provided in the [ingress.yaml](ingress.yaml) example to your own ingress resources as required.
 2. Test by performing a curl against the Ingress Path without the Client Cert and expect a Status Code 400.
 3. Test by performing a curl against the Ingress Path with the Client Cert and expect a Status Code 200.
-

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

@@ -11,20 +11,19 @@ metadata:
     # Specify an error page to be redirected to verification errors
     nginx.ingress.kubernetes.io/auth-tls-error-page: "http://www.mysite.com/error-cert.html"
     # Specify if certificates are passed to upstream server
-    nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "false"
+    nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
   name: nginx-test
   namespace: default
 spec:
   rules:
-  - host: ingress.test.com
+  - host: mydomain.com
     http:
       paths:
       - backend:
-          serviceName: http-svc:80
+          serviceName: http-svc
           servicePort: 80
         path: /
   tls:
   - hosts:
-    - ingress.test.com
+    - mydomain.com
     secretName: tls-secret
-