add ioc deploy and manage pages

Author: gilesknap

README.rst

@@ -35,7 +35,7 @@ management of IOCs.
 - Containers package generic IOC code and dependencies.
 - Kubernetes orchestrates the **Containers**.
 - Helm deploys IOCs to **Kubernetes**.
-- Repositories hold **container** images and **helm** charts
+- Repositories hold **Container** images and **Helm** charts
 - CI / CD generates the images, charts from source and delivers them
   to **Repositories**
 

docs/tutorials/add_ioc.rst renamed to docs/how-to/add_ioc.rst

@@ -47,7 +47,7 @@ About the documentation
     tutorials/setup_k8s
     tutorials/useful_k8s
     tutorials/create_beamline
-    tutorials/add_ioc
+    tutorials/deploy_example
     tutorials/manage_iocs
 
 .. toctree::
@@ -65,6 +65,7 @@ About the documentation
     :name: how-to
     :maxdepth: 1
 
+    how-to/add_ioc
     how-to/create_ioc
     how-to/generic_iocs
     how-to/debug

docs/index.rst

@@ -11,7 +11,9 @@ live with K8s IOCs. Kubernetes is very well suited to running web
 servers so this is a natural fit.
 
 There are a number of ways to support the current OPI solutions without
-breaking the repositories-only model. TODO: add a brief description of these.
+breaking the repositories-only model. The simplest approach is to extract
+the OPI files from the container running in Kubernetes with **kubectl cp**.
+Then keep a local cache and run the OPI code locally.
 
 
 Why have ioc-XXX repositories?

docs/reference/faq.rst

@@ -53,24 +53,13 @@ In a terminal use git to clone the repository by pasting in the URL you copied
 in the previous step::
 
 
-    [giles@gklinux2 tmp]$ git clone [email protected]:gilesknap/bl00i.git
-    Cloning into 'bl00i'...
-    remote: Enumerating objects: 22, done.
-    remote: Counting objects: 100% (22/22), done.
-    remote: Compressing objects: 100% (18/18), done.
-    remote: Total 22 (delta 0), reused 21 (delta 0), pack-reused 0
-    Receiving objects: 100% (22/22), 15.28 KiB | 15.28 MiB/s, done.
-    [giles@gklinux2 tmp]$
+    git clone [email protected]:gilesknap/bl00i.git
 
 Now test that CI is working by tagging the repo and pushing it back to github::
 
-
-    [giles@gklinux2 tmp]$ cd bl00i
-    (main) [giles@gklinux2 bl00i]$ git tag 0.1
-    (main) [giles@gklinux2 bl00i]$ git push origin 0.1
-    Total 0 (delta 0), reused 0 (delta 0)
-    To github.com:gilesknap/bl00i.git
-    * [new tag]         0.1 -> 0.1
+    cd bl00i
+    git tag 0.1
+    git push origin 0.1
 
 This will cause github CI to generate a helm chart for the example IOC and
 deliver it to the account packages repository.
@@ -87,3 +76,11 @@ Go to the code pane and click on the example Package circled below to see it.
 .. image:: ../images/github_package.png
     :align: center
 
+There will be one version of the package, with two tags:
+
+- the tag you set on the source
+- and the 'latest' tag
+
+
+.. image:: ../images/github_example_package.png
+    :align: center

docs/tutorials/create_beamline.rst

@@ -0,0 +1,99 @@
+Deploy The Example IOC
+======================
+
+Initial Setup
+-------------
+
+In this tutorial step we will deploy and interact with the example ioc
+that came with the beamline source template we used in the previous step.
+
+For this step it is assumed that you have Kubernetes set up and kubectl
+installed on your workstation. Also there is an epics-iocs namespace
+configured and your context is setup to default into that namespace. Finally
+helm must also be installed.
+
+For instructions on how to set up Kubernetes, kubectl and helm
+see `setup_kubernetes`.
+
+To save on typing the script kube-functions.sh provides some shell
+functions which are simply wrappers for kubectl and helm commands. To
+learn about the commands take a look at the script.
+
+Source kube-functions.sh into your shell as follows. NOTE: replace
+gilesknap with your account::
+
+    export K8S_HELM_REGISTRY=ghcr.io/gilesknap
+    wget -q https://raw.githubusercontent.com/epics-containers/k8s-epics-utils/main/epics-dev-image/home/bin/kube-functions.sh
+    source kube-functions.sh
+
+Deploy an IOC Version
+---------------------
+
+In the previous tutorial we pushed tag 0.1 to gilesknap/bl00i and this
+generated a helm chart at ghcr.io/gilesknap with tags 0.1 and latest.
+
+To deploy the helm chart into your cluster::
+
+    k8s-ioc deploy example 0.1
+
+
+Learning about Helm and Kubernetes Manifests
+--------------------------------------------
+
+It is instructive to see what helm is doing when you execute the above
+command.
+
+Helm uses templates to generate a set of YAML resources and applies them
+to the cluster using kubectl.
+
+We are using a helm library defined in
+https://github.com/epics-containers/helm-ioc-lib. You can see the templates
+it is using in its templates folder.
+
+The example ioc folder itself has a templates folder containing the ioc.yaml
+template. This includes all of the templates from helm-ioc-lib and
+also generates a ConfigMap resource from the files in the config folder.
+
+To see the YAML that helm is generating you can use the following commands::
+
+    cd bl00i
+    helm dependency update iocs/example/
+    helm template example iocs/example
+
+This is using the helm chart in your local filesystem rather than the one
+that we pushed to the registry so this is useful for your inner dev loop
+testing. You can also deploy directly from the local copy with this
+command::
+
+    helm upgrade --install example iocs/example
+
+This is recommended for testing only since you won't easily be able to track
+versions deployed in this way.
+
+Launching a GUI to interact with your IOC
+-----------------------------------------
+
+OPI screens are outside of the scope of this project for the moment see
+`no_opi`.
+
+However to make this example usable we have supplied some edm screens and
+will use a local edm container to display these. For this purpose you will
+require docker (or podman) installed on your workstation and your user
+will need to be in the docker group.
+
+See here https://docs.docker.com/engine/install/ for instructions for
+installing docker.
+
+To launch the GUI for the example IOC::
+
+    cd bl00i
+    ./opi/stexample-gui.sh
+
+The IOC is a simulated detector with a PVA plugin. It will be possible to
+run a PVA viewer to see the output of this IOC.
+
+The main screen of the edm OPI should look like this.
+
+
+.. image:: ../images/edm_pco.png
+    :align: center

docs/tutorials/deploy_example.rst

@@ -1,26 +1,63 @@
-Deploy and Manage IOCs
-======================
+Manage IOCs
+===========
 
-Deploy an IOC Version
----------------------
-**Todo**
+IOCs running in Kubernetes can be managed using the kubectl command.
 
-Rollback an IOC
----------------
-(within K8s using helm and simply by doing another deploy)
-**Todo**
+The script kube-functions.sh that we used in `deploy_example` provides some
+shortcuts for common operations. Look inside the script to learn the
+underlying kubectl commands being used.
 
 Starting and Stopping IOCs
 --------------------------
-**Todo**
+
+To stop / start  the example IOC::
+
+    k8s-ioc stop example
+    k8s-ioc start example
 
 Monitoring and interacting with an IOC shell
 --------------------------------------------
-**Todo**
+
+To attach to the ioc shell::
+
+    k8s-ioc attach example
+
+Use the command sequence ^P^Q to detach or ^D to detach and restart the IOC.
+
+To run a bash shell inside the IOC container::
+
+    k8s-ioc exec example
+
+This is a minimal ubuntu distribution. To get access to useful utility commands
+use the following::
+
+    busybox sh
+    busybox  # shows the set of commands now available
+
+Also note that the following folders may be of interest:
+
+=============== ==============================================================
+ioc code        /epics/ioc
+support modules /epics/support
+epics binaries  /epics/epics-base
+=============== ==============================================================
+
 
 Logging
 -------
-**Todo**
+
+To get the current logs for the example IOC::
+
+    k8s-ioc log example
+
+Monitor your beamline IOCs
+
+    k8s-ioc monitor blxxi
+
+Note that the beamline is called blxxi rather than bl00i. To change the
+beamline name that your IOC deploys to you would need to edit
+bl00i/iocs/example/values.yaml, push the changes and execute deploy again.
+
 
 
 

docs/tutorials/manage_iocs.rst

@@ -20,6 +20,8 @@ If you prefer to investigate other implementations there are also:
   - microk8s https://microk8s.io/
   - minikube https://minikube.sigs.k8s.io/docs/start/
 
+For k3s documentation see https://k3s.io/.
+
 Installation Steps
 ------------------
 
@@ -31,17 +33,27 @@ Execute this command on your server to set up the cluster master
 
     curl -sfL https://get.k3s.io | sh -
 
-Install kubectl on the workstation from which you will be managing the cluster
-(workstation==server if you have one machine only)::
+Install kubectl
+~~~~~~~~~~~~~~~
+
+Kubectl is the command line tool for interacting with your cluster. If you
+have a separate workstation then you can install it there. If you only have one
+machine then server==workstation.
+
+On the workstation install the binary::
 
     curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
     sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
+    source <(kubectl completion bash)
+
+The last step adds command line completion and is worth adding to your profile.
 
-Go to the server machine and copy over the kubectl configuration to your
-workstation::
+From the server machine copy over the k3s kubectl configuration::
 
     sudo scp  /etc/rancher/k3s/k3s.yaml <YOUR_ACCOUNT>@<YOUR_WORKSTATION>:.kube/config
-    # edit the file .kube/config replacing 127.0.0.1 with your server IP Address
+
+If you do have separate workstation then edit the file .kube/config replacing
+127.0.0.1 with your server's IP Address.
 
 
 Create an epics IOCs namespace and context
@@ -53,6 +65,32 @@ From the workstation execute the following::
     kubectl config set-context epics-iocs --namespace=epics-iocs --user=default --cluster=default
     kubectl config use-context epics-iocs
 
+Create a service account to run the IOCs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create the account::
+
+    kubectl apply -f - <<EOF
+    apiVersion: v1
+    kind: ServiceAccount
+    metadata:
+        name: epics-iocs-priv
+    EOF
+
+Generate a login token for the account::
+
+    kubectl apply -f - <<EOF
+    apiVersion: v1
+    kind: Secret
+    metadata:
+        name: epics-iocs-priv-secret
+        annotations:
+            kubernetes.io/service-account.name: epics-iocs-priv
+    type: kubernetes.io/service-account-token
+    EOF
+
+.. _setup_helm:
+
 Install helm
 ~~~~~~~~~~~~
 
@@ -67,3 +105,9 @@ Completed
 That's it. You now have installed the necessary software to start experimenting
 with IOCs on Kubernetes.
 
+To remove everything you have installed above and clean up the disk space
+simply use this command::
+
+    k3s-uninstall.sh
+
+If you are interested in looking at the k3s files see **/var/lib/rancher/k3s/**.