Merge pull request #18 from epics-containers/dev

add tutorials 09 10

Author: gilesknap

.vscode/settings.json

@@ -16,7 +16,9 @@
         "Beamlines",
         "blxxi",
         "blxxt",
+        "GRAPHICSMAGICK",
         "klogout",
+        "Magick",
         "MVME"
     ]
 }

docs/user/explanations/kubernetes_cluster.rst

@@ -68,11 +68,11 @@ Overview
 
 Argus is the production DLS cluster. It comprises 22 bare metal worker nodes, with a 3 node control plane that runs in VMs. The control plane nodes run the K8s master processes such as the API server, controller manager etc. Each control plane node runs an etcd backend.
 
-.. image:: ../images/clusterHA.png
+.. figure:: ../images/clusterHA.png
 
 To load balance across the K8s API running on the control plane nodes, there is a haproxy load balancer. The DNS endpoint argus.api.diamond.ac.uk (which all nodes use as the main API endpoint) points to a single haproxy IP. The IP is HA by virtue of a pair of VMs that both run haproxy, bind on all IPs, and use VRRP/keepalived to make sure the IP is always up. Haproxy has the 3 control plane nodes as a target backend.
 
-.. image:: ../images/kubeadm-ha-topology-stacked-etcd.png
+.. figure:: ../images/kubeadm-ha-topology-stacked-etcd.png
 
 The cluster uses Kubeadm to deploy the K8s control plane in containers. It is provided by K8s upstream, and is architecturally similar to Rancher Kubernetes Engine (RKE). Kubeadm supports upgrades/downgrades and easy provisioning of nodes. The cluster is connected using Weave as the CNI. Weave is the only CNI tested that passes Broadcast/Unicast/Multicast (BUM) traffic through the iptables that control network access for pods. Metallb is used as a component to support K8s loadBalancer Service objects. Ingress nginx from nginxinc is used as an ingress controller. Logs are collected from the stdout of all pods using a fluentd daemonset which ships logs to a centralized graylog server. Cluster authentication is via KeyCloak.
 
@@ -81,7 +81,7 @@ The cluster sits in one rack, with a top of rack (TOR) switch/router connecting
 
 **One of the Argus racks**
 
-.. image:: ../images/argus3.jpg
+.. figure:: ../images/argus3.jpg
 
 The cluster is built and managed using Ansible. Heavy use of the k8s module enables direct installation of K8s components by talking directly to the K8s API using the k8s module. Ansible also configures the haproxy API load balancer. Prometheus_operator provides the monitoring stack.
 

docs/user/explanations/net_protocols.rst

@@ -48,17 +48,13 @@ Initially we looked into workarounds to these issues. For example the
 diagram below shows a 'ca-forwarder' that sits on the EPICS client subnet
 and forwards requests to IOCs in the cluster.
 
-.. image:: ../images/caforwarder.png
-    :width: 1500px
-    :align: center
+.. figure:: ../images/caforwarder.png
 
 However this 2nd diagram shows why this approach fails when the client is in
 the cluster itself.
 
 
-.. image:: ../images/cabackwarder.png
-    :width: 1500px
-    :align: center
+.. figure:: ../images/cabackwarder.png
 
 The conclusion of this study was that workarounds were fiddly and needed to be
 implemented on a per protocol basis, plus there is no guarantee that there

docs/user/explanations/repos.rst

@@ -0,0 +1,9 @@
+What is the /repos Folder?
+==========================
+
+TODO: explain why we have a /repos folder and how it is
+mounted and synced with a the host to enable inside/outside
+access when debugging and testing container builds.
+
+
+.. figure:: ../images/repos_folder.png

docs/user/how-to/useful_k8s.rst

@@ -133,8 +133,7 @@ First you will need install `docker for WSL`_.
 You will also require an `X11 Server for Windows`_. When you run the server
 choose the option **Disable Access Control** as follows:
 
-.. image:: ../images/vcxsrv.png
-    :align: center
+.. figure:: ../images/vcxsrv.png
 
 The networking for docker on WSL will not broadcast between containers so
 you need to use EPICS_CA_ADDR_LIST to get edm to see the example IOC

docs/user/images/ghcr.png

@@ -57,6 +57,7 @@ side-bar.
             explanations/docs-structure
             explanations/repositories
             explanations/cli-tools
+            explanations/repos
 
         +++