Merge pull request #70 from epics-containers/k8s-tutorials

gilesknap · web-flow · commit 949aafdca94a · 2024-01-12T14:40:21.000Z
Add some tutorials for Kubernetes
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -1,16 +1,10 @@
 {
-    "python.linting.pylintEnabled": false,
-    "python.linting.flake8Enabled": true,
-    "python.linting.mypyEnabled": true,
-    "python.linting.enabled": true,
     "python.testing.pytestArgs": [],
     "python.testing.unittestEnabled": false,
     "python.testing.pytestEnabled": true,
-    "python.formatting.provider": "black",
-    "python.languageServer": "Pylance",
     "editor.formatOnSave": true,
     "editor.codeActionsOnSave": {
-        "source.organizeImports": true
+        "source.organizeImports": "explicit"
     },
     "cSpell.words": [
         "Beamlines",
diff --git a/docs/user/explanations/ioc-source.rst b/docs/user/explanations/ioc-source.rst
@@ -0,0 +1,8 @@
+.. _ioc-source:
+
+Dev Container vs Runtime Container
+==================================
+
+TODO: explain how and why ioc-xxxx is mounted in dev container and what happens
+to the ioc folder.
+
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -22,11 +22,13 @@ side-bar.
             tutorials/ioc_changes1
             tutorials/ioc_changes2
             tutorials/ioc_changes3
+            tutorials/ioc_changes4
             tutorials/generic_ioc
             tutorials/debug_generic_ioc
             tutorials/test_generic_ioc
             tutorials/support_module
             tutorials/setup_k8s
+            tutorials/setup_k8s_new_beamline
             tutorials/rtems_setup
             tutorials/rtems_ioc
             tutorials/ibek
@@ -61,6 +63,7 @@ side-bar.
             explanations/kubernetes_cluster
             explanations/docs-structure
             explanations/repositories
+            explanations/ioc-source
 
         +++
 
diff --git a/docs/user/tutorials/dev_container.rst b/docs/user/tutorials/dev_container.rst
@@ -249,10 +249,10 @@ Adding the Beamline to the Workspace
 ------------------------------------
 
 To meaningfully test the Generic IOC we will need an instance to test it
-against. We will use the ``bl01t`` beamline that you already made. The container 
+against. We will use the ``bl01t`` beamline that you already made. The container
 has been configured to mount some useful local files from the user's home directory,
-including the parent folder of the workspace as ``/repos`` so we can work on 
-multiple peer projects. 
+including the parent folder of the workspace as ``/repos`` so we can work on
+multiple peer projects.
 
 In VSCode click the ``File`` menu and select ``Add Folder to Workspace``.
 Navigate to ``/repos`` and you will see all the peers of your ``ioc-adsimdetector``
@@ -320,6 +320,10 @@ host. i.e. the root folder under which your projects are all cloned):
      - WS
      - all peers to Generic IOC source repo
 
+.. _choose-ioc-instance:
+
+Choose the IOC Instance to Test
+-------------------------------
 
 Now that we have the beamline repo visible in our container we can
 easily supply some instance configuration to the Generic IOC.
diff --git a/docs/user/tutorials/ioc_changes1.rst b/docs/user/tutorials/ioc_changes1.rst
@@ -110,6 +110,11 @@ However all of the steps except for the ``ec`` command could have been done
 We choose not to have ``ec`` installed inside of the devcontainer because
 that would involve containers in containers which adds too much complexity.
 
+If you like working entirely from the vscode window you can open a terminal
+in vscode *outside* of the devcontainer. To do so, press ``Ctrl-Shift-P`` and
+choose the commnd ``Terminal: Create New Integrated Terminal (Local)``.
+This will open a terminal to the host. You can then run ``ec`` from there.
+
 Raw Startup Assets
 ------------------
 
diff --git a/docs/user/tutorials/ioc_changes2.rst b/docs/user/tutorials/ioc_changes2.rst
@@ -1,16 +1,127 @@
-Changing the Generic IOC
-========================
+Changing a Generic IOC Part 1
+=============================
+
+.. warning ::
+
+    This tutorial is a work in progress. It is not yet complete.
 
-This tutorial will make a simple change to the Generic IOC ``ioc-adsimdetector``.
-We will also update the IOC instance ``bl01t-ea-ioc-02`` use the new feature of
-the Generic IOC.
 This is a type 2 change from `ioc_change_types`.
 
-We are going to add an additional support module to the Generic IOC and then
-use it to add a new record to the IOC instance to use this new support.
+The changes that you can make in an IOC instance are limited to what
+the author of the associated Generic IOC has made configurable.
+Therefore you will
+occasionally need to update the Generic IOC that your instance is using.
+Some of the reasons for doing this are:
+
+- Update one or more support modules to new versions
+- Add additional support such as autosave or iocStats
+- For ibek generated IOC instances, you may need to add or change functionality
+  in the support YAML file.
+
+This tutorial will make some changes to the generic IOC ``ioc-adsample``.
+This Generic IOC is a simplified copy of ``ioc-adsimdetector`` tailored for
+use in these tutorials.
+
+For this exercise we will initially work locally inside the ``ioc-adsample``
+developer container.
+
+At the end we will push the changes and see the CI build a new version of the
+generic IOC container image. This allows for the demonstration of:
+
+- Deploying an IOC instance using a new image published by the CI
+- Showing how to do a Pull Request back to the original repository.
+
+For this exercise we will be using an example IOC Instance to test our changes.
+Instead of working with a beamline repository, we will use the example ioc instance
+that comes with ``ioc-adsample``. It is a good idea for Generic IOC authors to
+include an example IOC Instance in their repository for testing changes in
+isolation.
+
+
+Preparation
+-----------
+
+Because we want to push our changes we will first make a fork of the
+``ioc-adsample`` repository. We will then clone our fork locally and
+make the changes there.
+
+To make a fork go to
+`ioc-adsample <https://github.com/epics-containers/ioc-adsample>`_
+and click the ``Fork`` button in the top right corner. This will create a fork
+of the repository under your own GitHub account.
+
+Now, clone the fork, build the container image locally and open the
+developer container:
+
+.. code-block:: console
+
+    git clone git@github.com:<YOUR GITHUB ACCOUNT NAME>/ioc-adsample.git
+    cd ioc-adsample
+    ./build
+    code .
+    # click the green button in the bottom left corner of vscode and select
+    # "Reopen in Container"
+
+The ``build`` script does two things.
+
+- it fetches the git submodule called ``ibek-support``. This submodule is shared
+  between all the EPICS IOC container images and contains the support YAML files
+  that tell ``ibek`` how to build support modules inside the container
+  environment.
+- it builds the Generic IOC container image locally.
+
+.. note::
+
+    The ``build`` script is a convenience script that is provided in the
+    Generic IOC Template project. It is exactly equivalent to cloning
+    with ``--recursive`` flag and then running ``ec dev build``.
+
+Verify the Example IOC Instance is working
+------------------------------------------
+
+When a new Generic IOC developer container is opened, there are two things
+that need to be done before you can run an IOC instance inside of it.
+
+- Build the IOC source code
+- Select an IOC instance definition to run
+
+The folder ``ioc`` inside of the ``ioc-adsample`` is where the IOC source code
+is created and built. When you open the developer container, this folder does
+not yet exist. The following command will create it and build the IOC:
+
+.. code-block:: console
+
+    ec ioc build
+
+The IOC instance definition is a YAML file that tells ``ibek`` what the runtime
+assets (ie. EPICS DB and startup script) should look like. Previous tutorials
+selected the IOC instance definition from a beamline repository. In this case
+we will use the example IOC instance that comes with ``ioc-adsample``. The
+following command will select the example IOC instance:
+
+.. code-block:: console
+
+    ibek dev instance /epics/ioc-adsample/ioc_examples/bl01t-ea-ioc-02
+
+In an earlier tutorial when learning about the dev container, we manually
+performed this step, see `choose-ioc-instance`. The above command does
+exactly the same thing: removes the existing config folder in ``/epics/ioc``
+and symlinks in the chosen IOC instance definition's ``config`` folder.
+
+Now  run the IOC:
+
+.. code-block:: console
+
+    ibek dev run
+
+You should see a iocShell prompt and no error messages above.
+
+.. note::
 
-For this exercise all changes will be local so you will not need to make a
-fork of ``ioc-adsimdetector``. The next tutorial will show how to a new
-Generic IOC and we will look at the Generic IOC CI at that time.
+    The ``ec ioc build`` command required to re-create the IOC source code.
+    This is even though the container you are using already had the IOC
+    source code built by its Dockerfile (``ioc-adsample/Dockerfile``
+    contains the same command).
 
-TODO: WIP.
+    For a detailed explanation of why this is the case see
+    `ioc-source`
diff --git a/docs/user/tutorials/ioc_changes3.rst b/docs/user/tutorials/ioc_changes3.rst
@@ -1,12 +1,9 @@
-Making a new Support Module
-===========================
+Changing a Generic IOC Part 2
+=============================
 
-This tutorial will create a new Generic IOC for a new support module. We will
-then create a new IOC Instance that uses this new support module.
-This is a type 3 change from `ioc_change_types`.
+This is a type 2 change from `ioc_change_types`.
+
+This tutorial will change the support yaml used by a generic IOC.
 
-This exercise will create a new Stream Device support module that implements
-a very simple ASCII protocol. So simple that we will be able to test it
-by typing into a telnet session.
 
 TODO: WIP.
diff --git a/docs/user/tutorials/ioc_changes4.rst b/docs/user/tutorials/ioc_changes4.rst
@@ -0,0 +1,12 @@
+Making a new Support Module
+===========================
+
+This tutorial will create a new Generic IOC for a new support module. We will
+then create a new IOC Instance that uses this new support module.
+This is a type 3 change from `ioc_change_types`.
+
+This exercise will create a new Stream Device support module that implements
+a very simple ASCII protocol. So simple that we will be able to test it
+by typing into a telnet session.
+
+TODO: WIP.
diff --git a/docs/user/tutorials/notes.md b/docs/user/tutorials/notes.md
@@ -0,0 +1,50 @@
+Things to write about in the coming chapters.
+=============================================
+
+ioc_changes1.rst - simple change to an IOC instance
+---------------------------------------------------
+done
+
+ioc_changes2.rst - simple change to a generic IOC
+-------------------------------------------------
+
+Use a fork of ioc-sampledetector
+to update the version number of adsimdetector and to add dev-iocstats
+(ioc-sampledetector is copy of ioc-adsimdetector with some changes -
+deviocstats is removed and it is using an earlier version of adsimdetector
+support)
+
+- push and run the CI
+- verify a local instance can use resulting image
+  - add dev-iocstats and update generic IOC version number
+- do a pull request back to ec
+
+ioc_changes3.rst - a change to ibek-support
+-------------------------------------------
+
+Add some kind of additional feature into ioc-adsampledetector
+maybe something from one of the ADCore plugins
+
+- requires forking and updating ibek-support
+- also update ioc-sampledetector to ue the new ibek-support
+- verify a local instance can use resulting image
+- do a pull request back to ec
+
+
+generic_ioc.rst - make a new generic IOC
+----------------------------------------
+
+This will involve creating a new support module from scratch and
+making a generic IOC for it.
+
+The support module will be a very basic stream device.
+
+Note that the generic IOC comes first because it provides the development
+environment for the support module.
+
+IMPORTANT: this serves as a how-to for if you already have a support module
+and want to make a generic IOC for it.
+TODO: maybe it is worth having a seperate how-to for and existing areadetector
+support module because this will be a common use case and we can use
+ioc-adsimdetector as the template (I made it a template for this reason).
+
diff --git a/docs/user/tutorials/setup_k8s.rst b/docs/user/tutorials/setup_k8s.rst
diff --git a/docs/user/tutorials/setup_k8s_new_beamline.rst b/docs/user/tutorials/setup_k8s_new_beamline.rst
diff --git a/docs/user/tutorials/setup_workstation.rst b/docs/user/tutorials/setup_workstation.rst
