complete kubernetes docs + added openshift

deployments/README.md

@@ -34,7 +34,9 @@ As described above, `docker` is a great tool for smaller deployments, where you
 
 ## 4. RedHat Ansible and OpenShift
 
-To be written
+If you running an alternative distribution such as RedHat OpenShift, things will work out exactly as mentioned before with the `Kubernetes` deployment. You'll have all the benefints of RedHat OpenShift on top. One of the things we provide here is an Ansible playbook to deploy the Kerberos Agent in the OpenShift cluster.
+
+> Learn more [about Kerberos Agent in OpenShift with Ansible](https://github.com/kerberos-io/agent/tree/master/deployments/ansible-openshift).
 
 ## 5. Kerberos Factory
 

deployments/ansible-openshift/README.md

@@ -1,5 +1,45 @@
-# Deploy to a Red Hat OpenShift cluster using ansible
+# Deploy to a RedHat OpenShift cluster with Ansible
 
-Eithin this directory you'll find an Ansible playbook to install a Kerberos Agent to an existing OpenShift cluster. By providing the cluster url, username and password, you will be able to create several resources in your cluster.
+Kubernetes is great, but you might love OpenShift even more. In this directory you'll find some resources to deploy your Kerberos Agent in an OpenShift cluster using Ansible playbook. We'll review the different tasks of the Ansible playbook step by step; find the complete `playbook.yaml` here.
 
-    ansible-playbook  -e '{"oc_cluster_url":"https://api.j5z0adui.westeurope.aroapp.io:6443", "oc_username":"kubeadmin", "oc_password":"xxx"}' playbook.yml 
+## Variabeles
+
+We'll have a few `variables` in our `playbook.yml` that will help us to setup secure connection with the OpenShift cluster. We need the `cluster_url` and the `username` and `password` of the OpenShift cluster. If you don't know where to find this, you can find this in the OpenShift web ui.
+
+    vars:
+    - oc_cluster_url: ""
+    - oc_username: ""
+    - oc_password: ""
+
+## Tasks
+
+Once we have supplied the `variables` we will define following tasks:
+
+    - name: Print Variables
+    - name: Try to login to OCP cluster
+    - name: Create a Namespace
+    - name: Create a Persistent volume claim
+    - name: Deploy Kerberos Agent
+    - name: Expose Kerberos Agent
+
+1. Print variables: this is a validation step, where we make sure we have the correct variables supplied to the `ansible-playbook` command. This confirms we are using the right credentials to setup a secure connection with the OpenShift cluster.
+
+2. Setup a connection with OpenShift using the defined variabeles. If successfull an `api_key` will become available in the `k8s_auth_result` variable. This variabele will be used with every subsequent operation against the OpenShift cluster.
+
+3. A best practice is to isolate your workloads in namespaces. Therefore we'll create a new namespace in our OpenShift cluster.
+
+4. (Optional) Create a persistent volume to persist the configuration file and recordings in a volume.
+
+5. Deploy Kerberos Agent through a `deployment`.
+
+6. Expose the Kerberos Agent web interface through a `LoadBalancer`; public internet accessible IP address.
+
+## Run the playbook
+
+Now you understand what is happening in the playbook, let's run it. Make sure you have `ansible` install on your `host` or `deploy` machine.
+
+Specify the `environment` input variable as a `JSON` with all required variables defined in step 1. Reference the `playbook.yml` file and execute.
+
+    ansible-playbook  -e '{"oc_cluster_url":"https://api.j5z0adui.westeurope.aroapp.io:6443", "oc_username":"kubeadmin", "oc_password":"xxx"}' playbook.yml
+
+If everything runs as expected you should see you Kerberos Agent deployed, together with an assigned public ip address. Paste the ip address in your browser, the Kerberos Agent web interface will show up. You can use [the default username and password to sign-in](https://github.com/kerberos-io/agent#access-the-kerberos-agent), or if changed to your own (which is recommended).

deployments/kubernetes/README.md

@@ -39,3 +39,73 @@ When the deployment and service is created successfully, you should see somethin
     replicaset.apps/agent-7c75c4dbcf   1         1         1       20s
 
 When copying the `EXTERNAL-IP` and pasting it in your browser, you should see the Kerberos Agent user interface. You can use [the default username and password to sign-in](https://github.com/kerberos-io/agent#access-the-kerberos-agent), or if changed to your own (which is recommended).
+
+## Configure with volumes
+
+Just like with `docker`, you can also attach `volumes` to the Kerberos Agent deployment, by creating a `Persistent Volume` and mount it to a specific directory.
+
+Depending on where and how you are hosting the Kubernetes cluster, you may need to create a new `storageClass` or use a predefined `storageClass` from your cloud provider (Azure, GCP, AWS, ..). Have a look at `deployment-agent-volume.yml` to review a complete example.
+
+    template:
+    metadata:
+        labels:
+        app: agent
+    spec:
+        volumes:
+        - name: kerberos-data
+            persistentVolumeClaim:
+            claimName: kerberos-data
+        ...
+        containers:
+        - name: agent
+          image: kerberos/agent:latest
+          volumeMounts:
+            - name: kerberos-data
+              mountPath: /home/agent/data/config
+              subPath: config
+        ...
+
+## Expose with Ingress
+
+In the first example `deployment-agent.yml` we are using a `LoadBalancer` to expose the Kerberos Agent user interface; as shown below. If you are a bit more experienced with Kubernetes, you will know there are other `service types` as well.
+
+    ---
+    apiVersion: v1
+    kind: Service
+    ...
+    type: LoadBalancer
+    ports:
+        - port: 80
+    ...
+
+An alternative to `LoadBalancer` is `Ingress`. By leveraging an ingress such as `ingress-nginx` or `traefik` you setup a gateway (single point of contact), through which all communication to your apps (services) will flow.
+
+A huge benefit (there are many others), is that you only allocate 1 public IP address for all your services. So instead of creating a `LoadBalancer` and thus a public IP address for every agent, you will create an `Ingress` service for each agent. Review the complete example at `deployment-agent-with-ingress.yml`.
+
+    apiVersion: networking.k8s.io/v1
+    kind: Ingress
+    metadata:
+    name: agent-ingress
+    labels:
+        name: agent-ingress
+    annotations:
+        kubernetes.io/ingress.class: nginx
+        kubernetes.io/tls-acme: "true"
+        nginx.ingress.kubernetes.io/ssl-redirect: "true"
+        cert-manager.io/cluster-issuer: "letsencrypt-prod"
+    spec:
+    tls:
+        - hosts:
+            - "myagent.kerberos.io"
+        secretName: agent-secret
+    rules:
+    - host: myagent.kerberos.io
+        http:
+        paths:
+        - pathType: Prefix
+            path: "/"
+            backend:
+            service:
+                name: agent-svc
+                port:
+                number: 80