Skip to content

Commit 518fec0

Browse files
gilesknapgilesknap
committed
structure review and add explanation intro
1 parent e0573d9 commit 518fec0

File tree

12 files changed

+188
-79
lines changed

12 files changed

+188
-79
lines changed

‎README.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ epics-containers is an experimental GitHub organizaion to try out ideas
77
for managing EPICS IOCs in a Kubernetes cluster.
88

99
============== ==============================================================
10-
Docs Source https://github.com/epics-containers/k8s-epics-docs
11-
Documentation https://epics-containers.github.io/k8s-epics-docs/
10+
Docs Source https://github.com/epics-containers/epics-containers.github.io
11+
Documentation https://epics-containers.github.io
1212
============== ==============================================================
1313

1414

‎docs/_templates/layout.html

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,6 @@
88
}
99
</style>
1010
{{ super() }}
11-
<!-- Include Index in the sidebar -->
12-
<!-- https://stackoverflow.com/a/37843854 -->
13-
<a href="{{pathto('genindex.html', 1)}}">Index</a>
1411
<!-- Include all versions of the docs -->
1512
<!-- https://holzhaus.github.io/sphinx-multiversion/master/templates.html -->
1613
{% if versions %}

‎docs/explanations/introduction.rst

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
Essential Concepts
2+
==================
3+
4+
Overview
5+
--------
6+
7+
Kubernetes for EPICS IOCs provides the means to deploy and manage IOCs using
8+
modern industry standard approaches.
9+
10+
This page briefly describes the required concepts and technologies.
11+
12+
13+
Concepts
14+
--------
15+
16+
Generic IOCs and instances
17+
~~~~~~~~~~~~~~~~~~~~~~~~~~
18+
19+
An important principal of the approach presented here is that an IOC container
20+
image represents a 'generic' IOC. The generic IOC image is used for all
21+
IOC instances that connect to a given class of device.
22+
23+
An IOC instance runs in a container that bases its
24+
filesystem on a generic IOC image.
25+
In addition the instance has configuration mapped into the
26+
container that will bootstrap the unique properties of that instance.
27+
In most cases the configuration need only be a single IOC boot script.
28+
29+
This approach reduces the number of images required and saves disk. It also
30+
makes for simple configuration management.
31+
32+
Throughout this documentation we will use the terms Generic IOC and
33+
IOC Instance. The word IOC without this context is ambiguous.
34+
35+
Repositories
36+
~~~~~~~~~~~~
37+
38+
Another important principal is that all of the assets required to manage a
39+
set of IOCs for a beamline are held in repositories.
40+
41+
These repositories all maintain their own history and version information.
42+
43+
Thus all configuration management is done
44+
via these repositories and no special locations in
45+
the local filesystem are required
46+
(The legacy approach at DLS relied heavily on
47+
know locations in the filesystem).
48+
49+
In the epics-containers examples all 3 repositories are held in the same
50+
github organization. This is nicely contained and means that only one set
51+
of credentials is required to access all the resources.
52+
53+
There are many alternative services for storing these repositories, both
54+
in the cloud and on premises. Below we list the choices we have tested
55+
during proof of concept.
56+
57+
The 3 repositories are as follows:
58+
59+
- **Source Repository** This not only holds the source but also provides the
60+
Continuous Integration actions for testing, building and publishing to
61+
the following 2 repositories. These have been tested
62+
during proof of concept:
63+
64+
- github
65+
- gitlab (on prem)
66+
67+
- **An image registry** that holds the generic IOC container images and their
68+
dependencies. The following have been tested during proof of concept:
69+
70+
- github packages
71+
- dockerhub
72+
- Google Cloud Container Registry
73+
74+
- **A helm chart registry**. This is where the definitions of IOC instances
75+
are stored. They are in the form of a helm chart which describes to
76+
Kubernetes the resources needed to spin up the IOC.
77+
The following have been tested during proof of concept:
78+
79+
- github packages
80+
- Google Cloud Artifact Registry
81+
82+
Continuous Integration
83+
~~~~~~~~~~~~~~~~~~~~~~
84+
85+
Our examples all use continuous integration to get from pushed source
86+
to the published images / helm charts.
87+
88+
This allows us to maintain a clean code base that is continually tested for
89+
integrity and also to maintain a direct relationship between source code tags
90+
and the tags of their built resources.
91+
92+
There are these types of CI:
93+
94+
:Generic IOC repos:
95+
- builds a generic IOC container image
96+
- runs some tests against that image
97+
- publishes the image to github packages (only if the commit is tagged)
98+
99+
:beamline repos:
100+
- builds a helm chart from each ioc definition
101+
(TODO ibek will do this - at present the charts are hand coded)
102+
- TODO: IOCs which are unchanged should not be published again
103+
- publishes the charts to github packages (only if the commit is tagged)
104+
105+
:helm library repo:
106+
- builds the helm chart
107+
- publishes it to github packages (only if the commit is tagged)
108+
109+
Industry Standard Technologies
110+
------------------------------
111+
112+
Images and Containers
113+
~~~~~~~~~~~~~~~~~~~~~
114+
**TODO**
115+
116+
Kubernetes
117+
~~~~~~~~~~
118+
**TODO**
119+
120+
Helm
121+
~~~~
122+
**TODO**
123+
124+
Additional Tools
125+
----------------
126+
127+
k8s-epics-utils
128+
~~~~~~~~~~~~~~~
129+
**TODO**
130+
131+
Ibek
132+
~~~~
133+
**TODO**
134+

‎docs/explanations/strategy.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
1-
Kubernetes for EPICS IOCs strategy
2-
==================================
1+
Kubernetes for EPICS IOCs
2+
=========================
33

44
**TODO** this page will draw from presentation slides
5+
**TODO** it will use pretty diagrams to explain how all the pieces fit together
56

67
Hopefully using https://github.com/dbrnz/pptx2svg/tree/main/pptx2svg or some
78
other conversion utility and keep the PPTX in the repo.

‎docs/explanations/whats_in.rst

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,16 @@ e.g.
8282
containers from. e.g. ioc-pmac, ioc-adaravis
8383

8484
:k8s:
85-
this prefix is for utilities and documentation repositories.
85+
this prefix is for utilities repositories.
8686

8787
:helm:
8888
this prefix is for definitions of helm charts or helm chart libraries
89+
90+
:bl:
91+
this prefix is for the example beamline repositories e.g. bl45p. Note
92+
that when tagged commit is pushed to these repositories, they will
93+
generate a helm chart per ioc defined in the beamline. These helm charts
94+
are also pushed to the packages registry.
95+
e.g.
96+
97+
- https://github.com/epics-containers/bl45p/pkgs/container/bl45p-mo-ioc-01

‎docs/how-to/create_ioc.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Create a new generic IOC image
2+
==============================
3+
Todo - will have a template repo for this

‎docs/index.rst

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,27 +44,30 @@ About the documentation
4444
:name: tutorials
4545
:maxdepth: 1
4646

47-
tutorials/introduction
4847
tutorials/setup_k8s
48+
tutorials/create_beamline
49+
tutorials/add_ioc
4950
tutorials/manage_iocs
5051

5152
.. toctree::
5253
:caption: Explanations
5354
:name: explanations
5455
:maxdepth: 1
5556

56-
explanations/whats_in
57+
explanations/introduction
5758
explanations/strategy
59+
explanations/whats_in
5860
explanations/net_protocols
5961

6062
.. toctree::
6163
:caption: How-to Guides
6264
:name: how-to
6365
:maxdepth: 1
6466

65-
how-to/kubernetes_cluster
67+
how-to/create_ioc
6668
how-to/generic_iocs
6769
how-to/debug
70+
how-to/kubernetes_cluster
6871

6972
.. rst-class:: no-margin-after-ul
7073

@@ -77,4 +80,3 @@ About the documentation
7780
reference/cli
7881
reference/contributing
7982

80-
* :ref:`genindex`

‎docs/tutorials/add_ioc.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Add an IOC instance to a beamline
2+
=================================
3+
Todo

‎docs/tutorials/create_beamline.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Create a beamline repository
2+
============================
3+
Todo - will have a template repo for this

‎docs/tutorials/introduction.rst

Lines changed: 0 additions & 47 deletions
This file was deleted.

0 commit comments

Comments
 (0)