documentation: fix uid and message returned to the Kubernetes apiserver (#3730)

* documentation: always return the `uid` to the Kubernetes apiserver

The Kubernetes API server will reject the answer from any webhook that
does not contain the `uid` present in the request [1]. Failing to do
so will not only result in a warning, but in the answer from the
webhook being ignored, and the request rejected [2].

[1] https://github.com/kubernetes/apiserver/blob/464eee4062a8f21f785e657b32b83f19d693af8d/pkg/admission/plugin/webhook/request/admissionreview.go#L52-L55
[2] https://github.com/kubernetes/apiserver/blob/464eee4062a8f21f785e657b32b83f19d693af8d/pkg/admission/plugin/webhook/validating/dispatcher.go#L236-L239

* documentation: rename `reason` to `message` on certain objects

When the object refers to an `AdmissionReview` from Kubernetes, what
OPA calls the `reason` is the `message` field.

* documentation: create `opa-server` secret in the `opa` namspace

Signed-off-by: Rafael Fernández López <rfernandezlopez@suse.com>

docs/content/kubernetes-introduction.md

@@ -233,7 +233,7 @@ sent back to the API Server.
   "response": {
     "allowed": false,
     "status": {
-      "reason": "container image refers to illegal registry (must be hooli.com)"
+      "message": "container image refers to illegal registry (must be hooli.com)"
     }
   }
 }

docs/content/kubernetes-primer.md

@@ -450,7 +450,7 @@ request:
     group: ''
     resource: pods
     version: v1
-  uid: bbfeef88-d98d-11e8-b280-080027868e77
+  uid: 8d836dfd-e0c0-4490-93ba-85ed4a04261e
   userInfo:
     groups:
     - system:masters
@@ -496,10 +496,13 @@ main = {
   "response": response,
 }
 
-default response = {"allowed": true}
+default uid = ""
+
+uid = input.request.uid
 
 response = {
     "allowed": false,
+    "uid": uid,
     "status": {
         "message": reason,
     },
@@ -507,6 +510,7 @@ response = {
     reason = concat(", ", admission.deny)
     reason != ""
 }
+else = {"allowed": true, "uid": uid}
 ```
 
 The `system.main` policy MUST generate an **AdmissionReview** object containing
@@ -525,6 +529,7 @@ response from OPA would be:
 apiVersion: admission.k8s.io/v1
 kind: AdmissionReview
 response:
+  uid: 8d836dfd-e0c0-4490-93ba-85ed4a04261e
   allowed: false
   status:
     message: "image fails to come from trusted registry: nginx"

docs/content/kubernetes-tutorial.md

@@ -100,7 +100,7 @@ openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out s
 Create a Secret to store the TLS credentials for OPA:
 
 ```bash
-kubectl create secret tls opa-server --cert=server.crt --key=server.key
+kubectl create secret tls opa-server --cert=server.crt --key=server.key --namespace opa
 ```
 
 Next, use the file below to deploy OPA as an admission controller.
@@ -251,7 +251,7 @@ data:
         "allowed": false,
         "uid": uid,
         "status": {
-            "reason": reason,
+            "message": reason,
         },
     } {
         reason = concat(", ", admission.deny)

plugins/logs/plugin_benchmark_test.go

@@ -127,7 +127,7 @@ const largeEvent = `{
 	  "response": {
 		"allowed": false,
 		"status": {
-		  "reason": "Resource Pod/demo/nginx includes container image 'nginx' from prohibited registry"
+		  "message": "Resource Pod/demo/nginx includes container image 'nginx' from prohibited registry"
 		}
 	  }
 	},