add Create a Beamline Repository

Author: gilesknap

README.rst

@@ -29,17 +29,35 @@ Organization   https://github.com/epics-containers
 Overview
 ========
 
-.. include:: overview.rst
+Kubernetes for EPICS IOCs applies modern industry standards to the
+management of IOCs.
 
-This diagram shows how the assets combine to create a running IOC on a
+- Containers package generic IOC code and dependencies.
+- Kubernetes orchestrates the **Containers**.
+- Helm deploys IOCs to **Kubernetes**.
+- Repositories hold **container** images and **helm** charts
+- CI / CD generates the images, charts from source and delivers them
+  to **Repositories**
+
+Below we show how these assets combine to create a running IOC on a
 Kubernetes worker node.
 
 .. image:: images/example.png
     :width: 1500px
     :align: center
 
-- The Helm Chart defines an IOC instance: IMAGE + STARTUP SCRIPT + K8S DEPLOYMENT​
-- The entire definition of the P45 beamline is held in https://github.com/orgs/epics-containers/packages
+- The Helm Chart defines an IOC instance as:
+
+  - An image reference for generic IOC binaries
+  - A startup Script for the unique IOC instance
+  - K8S resource YAML to describe resources to the Kubernetes cluster
+
+- The entire definition of the the example P45 beamline is held in this
+  github organization:
+
+  - Helm Charts: https://github.com/orgs/epics-containers/packages
+  - IOC Images: https://github.com/orgs/epics-containers/packages
+  - BL45P IOC sources: https://github.com/epics-containers/bl45p
 
 ..
     Anything below this line is used when viewing README.rst and will be replaced

docs/explanations/introduction.rst

@@ -4,7 +4,7 @@ Essential Concepts
 Overview
 --------
 
-.. include:: overview.rst
+.. include:: ../overview.rst
 
 See below for more detail on each of these.
 

docs/explanations/overview.rst

@@ -45,6 +45,7 @@ About the documentation
     :maxdepth: 1
 
     tutorials/setup_k8s
+    tutorials/useful_k8s
     tutorials/create_beamline
     tutorials/add_ioc
     tutorials/manage_iocs

docs/index.rst

@@ -0,0 +1,21 @@
+Kubernetes for EPICS IOCs applies modern industry standards to the management
+of IOCs.
+
+There are 5 themes to this strategy:
+
+:Containers​:
+  Package IOC software and execute it in a lightweight virtual environment​.
+
+:Kubernetes​:
+  Centrally orchestrate all IOCs at a facility.
+
+:Helm Charts​:
+  Deploy IOCs into Kubernetes with version management​.
+
+:Repositories​:
+  Source, container and helm repositories manage all of the above assets.
+  No shared file systems required.​
+
+:Continuous Integration / Delivery:
+  Source repositories automatically build containers, helm charts and
+  deliver them to repositories.

docs/overview.rst

@@ -1,3 +1,89 @@
 Create a beamline repository
 ============================
-Todo - will have a template repo for this
+
+In this tutorial we will create a new beamline source repository on github.
+
+This is where the definitions of IOCs for a beamline will be held. Continuous
+integration will generate helm charts for each IOC and push them to
+your account's package repository.
+
+The beamline will come with an example IOC and further steps in the
+tutorial will teach you how to add your own.
+
+
+To Start
+--------
+
+For this exercise you will require a github user account or organization in
+which to place the new repo. If you do not have one then follow GitHub's
+`instructions`_.
+
+Log in to your account by going here https://github.com/login.
+
+.. _instructions: https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account
+
+Create a repository
+-------------------
+
+Navigate to the beamline template repo here https://github.com/epics-containers/blxx-template
+
+Click on 'Use This Template'. Choose a name and description for your repo.
+Click 'Create Repository From Template'.
+
+.. image:: ../images/create_repo.png
+    :align: center
+
+This will create your new repository and take you to its Code panel.
+
+Now Click on 'Code' and copy the SSH or HTTPS link presented. This depends on
+how you will authenticate to github. HTTPS will ask you for your user name
+and password for all transactions. To setup SSH authentication see `about ssh`_
+
+.. _about ssh: https://docs.github.com/en/[email protected]/github/authenticating-to-github/connecting-to-github-with-ssh/about-ssh
+
+
+Clone and Tag the Repository
+----------------------------
+
+For the remainder of the tutorial the examples will use the ssh URL for
+the account gilesknap and the repository name bl00i. Please substitute in
+your own details.
+
+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]$
+
+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
+
+This will cause github CI to generate a helm chart for the example IOC and
+deliver it to the account packages repository.
+
+To watch the progress go to the Actions Panel for your project.
+
+.. image:: ../images/github_actions.png
+    :align: center
+
+Once the CI completes you should have a helm chart delivered in your packages.
+Go to the code pane and click on the example Package circled below to see it.
+
+
+.. image:: ../images/github_package.png
+    :align: center
+

docs/overview.rst

@@ -65,4 +65,5 @@ Execute this on the workstation::
 Completed
 ~~~~~~~~~
 That's it. You now have installed the necessary software to start experimenting
-with IOCs on Kubernetes.
+with IOCs on Kubernetes.
+

docs/tutorials/create_beamline.rst

@@ -0,0 +1,64 @@
+
+Useful Kubernetes Additions
+===========================
+
+Install the Kubernetes Dashboard
+--------------------------------
+
+The dashboard gives you a nice GUI for exploring and controlling your cluster.
+It is very useful for new users to get an understanding of what Kubernetes
+has to offer.
+
+Execute this on your workstation:
+
+.. code-block:: bash
+
+    GITHUB_URL=https://github.com/kubernetes/dashboard/releases
+    VERSION_KUBE_DASHBOARD=$(curl -w '%{url_effective}' -I -L -s -S ${GITHUB_URL}/latest -o /dev/null | sed -e 's|.*/||')
+    kubectl create -f https://raw.githubusercontent.com/kubernetes/dashboard/${VERSION_KUBE_DASHBOARD}/aio/deploy/recommended.yaml
+
+Then create the admin user and role by creating dashboard-admin.yaml containing:
+
+.. code-block:: yaml
+
+    apiVersion: v1
+    kind: ServiceAccount
+    metadata:
+    name: admin-user
+    namespace: kubernetes-dashboard
+    ---
+    apiVersion: rbac.authorization.k8s.io/v1
+    kind: ClusterRoleBinding
+    metadata:
+    name: admin-user
+    roleRef:
+    apiGroup: rbac.authorization.k8s.io
+    kind: ClusterRole
+    name: cluster-admin
+    subjects:
+    - kind: ServiceAccount
+    name: admin-user
+    namespace: kubernetes-dashboard
+
+get a token for the user::
+
+    kubectl create -f dashboard-admin.yaml
+    kubectl -n kubernetes-dashboard describe secret admin-user-token | grep '^token'
+
+Finally, start a proxy and goto the Dashboard URL, use the above token to log in::
+
+    kubectl proxy &
+    browse to http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy
+
+
+Add a Raspberry Pi to the cluster
+---------------------------------
+
+For a Raspberry Pi you need a couple of extra settings to get K3S running.
+
+You need the following changes before installing::
+
+    sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
+    # edit /boot/cmdline and make sure the single line contains:
+    #  cgroup_memory=1 cgroup_enable=memory
+    sudo reboot