add more explanation text

Author: gilesknap

docs/explanations/introduction.rst

@@ -5,11 +5,88 @@ Overview
 --------
 
 Kubernetes for EPICS IOCs provides the means to deploy and manage IOCs using
-modern industry standard approaches.
+modern industry standard approaches. The same approaches used by the large
+majority of micro-service and SOA applications.
 
 This page briefly describes the required concepts and technologies.
 
 
+Industry Standard Technologies
+------------------------------
+
+Images and Containers
+~~~~~~~~~~~~~~~~~~~~~
+Containers provide the means to package up IOC software and execute it
+in a lightweight virtual environment. This includes saving the packages
+into public or private image registries such as DockerHub or Google Cloud
+Registry.
+
+The Open Container Initiative (OCI) defines the set container services
+and their APIs such that container images can be interchanged between
+different frameworks.
+
+Thus, in this project we develop, build and test our container images
+using docker or podman but the images can be run under Kubernetes' own
+container runtime.
+
+This article does a good job of explaining the relationship between docker /
+containers and Kubernetes https://semaphoreci.com/blog/kubernetes-vs-docker
+
+Perhaps the best outcome of using containers is that you can alter the
+environment inside the container to suit the IOC code, instead of altering the
+code to suit your infrastructure. At DLS, this means that we are able to use
+vanilla EPICS base and support modules. We no longer require our own
+forks of these repositories.
+
+
+Kubernetes
+~~~~~~~~~~
+https://kubernetes.io/
+
+Kubernetes easily and efficiently manages containers across clusters of hosts.​
+
+It builds upon 15 years of experience of running production workloads at
+Google, combined with best-of-breed ideas and practices from the community​,
+since it was open-sourced in 2014.
+
+Today it is by far the dominant orchestration technology for containers.
+
+In this project we use Kubernetes to provide a standard way of implementing
+these features:
+
+- Auto start IOCs when servers come up​
+- Manually Start and Stop IOCs​
+- Monitor IOC status and versions​
+- Deploy versioned IOCs to the beamline​
+- Rollback to a previous IOC version​
+- Allocate the server which runs an IOC​
+- View the current log ​
+- View historical logs (via graylog)​
+- Connect to an IOC and interact with its shell
+- debug an ioc by starting a bash shell inside it's container
+- etc.
+
+
+Helm
+~~~~
+https://helm.sh/
+
+Helm is the most popular package manager for Kubernetes applications​.
+
+The packages are called Helm Charts​. They contain templated YAML files to
+define a set of resources to apply to a Kubernetes cluster​.
+
+Helm has functions to deploy Charts to a cluster and manage multiple versions
+of the chart within the cluster​.
+
+It also supports registries for storing version history of charts,
+much like docker.
+
+In this project we use Helm Charts to define and deploy IOC instances. Each
+beamline has its own Helm Repository which stores current and historical
+version of its IOC instances.
+
+
 Concepts
 --------
 
@@ -110,29 +187,38 @@ There are these types of CI:
     - builds the sphinx docs
     - publishes it to github.io pages
 
-Industry Standard Technologies
-------------------------------
+Scope
+-----
+This project currently targets the low hanging fruit of x86_64 Linux Soft
+IOCs only.
 
-Images and Containers
-~~~~~~~~~~~~~~~~~~~~~
-**TODO**
+Other linux architectures could be added to the Kubernetes cluster.
 
-Kubernetes
-~~~~~~~~~~
-**TODO**
+In future it is entirely possible that Windows IOCs could also be supported
+since Kubernetes supports mixed OS clusters. This would be needed
+because windows containers require a windows host.
+
+Hard IOCs will not be supported in their current form. Perhaps there is a
+future possibility of turning hard IOCs remote devices.
 
-Helm
-~~~~
-**TODO**
 
 Additional Tools
 ----------------
 
 k8s-epics-utils
 ~~~~~~~~~~~~~~~
-**TODO**
+The project k9s-epics utils contains a script to add simple command
+line functions for deploying and monitoring IOCs.
+
+It also provides a Dockerfile for building a personal developer image
+allowing a developer to work on support modules or IOCs anywhere.
+
+See the repository documentation (TODO)
 
 Ibek
 ~~~~
-**TODO**
+IOC Builder for EPICS and Kubernetes provides a way to generate an IOC
+helm chart from a YAML description of the IOC.
 
+TODO: this is in early development and not yet included in the epics-containers
+Organization.