Skip to content

Commit 389e71a

Browse files
gilesknapgilesknap
committed
first draft of structure
1 parent 3825343 commit 389e71a

16 files changed

+289
-146
lines changed

‎CONTRIBUTING.rst

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,27 @@
11
Contributing
22
============
33

4-
Contributions and issues are most welcome! All issues and pull requests are
5-
handled through github on the `epics-containers repository`_. Also, please check for
6-
any existing issues before filing a new one. If you have a great idea but it
7-
involves big changes, please file a ticket before making a pull request! We
8-
want to make sure you don't spend your time coding something that might not fit
9-
the scope of the project.
4+
Contributions and issues are most welcome! All issues and pull requests for
5+
the documentation or for the ideas expressed in the epics-containers
6+
organization are handled through github on the `k8s-epics-docs repository`_.
107

11-
.. _epics-containers repository: https://github.com/epics-containers/k8s-epics-docs/issues
8+
Report issues for generic iocs etc. in their own repos.
9+
10+
.. _k8s-epics-docs repository: https://github.com/epics-containers/k8s-epics-docs/issues
1211

1312
Running the tests
1413
-----------------
1514

15+
This module contains no code but running the tests does verify the sphinx
16+
documentation.
17+
1618
To get the source source code and run the unit tests, run::
1719

1820
$ git clone git://github.com/epics-containers/k8s-epics-docs.git
19-
$ cd k8s_epics_docs
21+
$ cd k8s-epics-docs
2022
$ pipenv install --dev
2123
$ pipenv run tests
2224

23-
While 100% code coverage does not make a library bug-free, it significantly
24-
reduces the number of easily caught bugs! Please make sure coverage remains the
25-
same or is improved by a pull request!
26-
2725
Code Styling
2826
------------
2927

@@ -69,3 +67,8 @@ You can build the docs from the project directory by running::
6967
$ pipenv run docs
7068
$ firefox build/html/index.html
7169

70+
The documentation is automatically built and published on github pages when
71+
this repo is pushed to main or with a tag.
72+
73+
See https://epics-containers.github.io/k8s-epics-docs/
74+

‎README.rst

Lines changed: 10 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,10 @@
1-
epics-containers Organization Documentation
2-
===========================================
1+
epics-containers
2+
================
33

44
|docs_ci| |license|
55

6-
epics-containers is an experimental area for trying ideas for managing
7-
EPICS IOCs in a kubernetes cluster.
8-
9-
This will include a full implemtation of all the IOCs for the test beamline
10-
BL45P at Diamond Light Source.
11-
12-
The organization includes container images for generic iocs and
13-
these might also be used independently of kubernetes.
6+
epics-containers is an experimental GitHub organizaion to try out ideas
7+
for managing EPICS IOCs in a Kubernetes cluster.
148

159
============== ==============================================================
1610
Docs Source https://github.com/epics-containers/k8s-epics-docs
@@ -19,11 +13,13 @@ Documentation https://epics-containers.github.io/k8s-epics-docs/
1913

2014
An important principal of the approach presented here is that an IOC container
2115
image represents a 'generic' IOC. The generic IOC image is used for all
22-
IOC instances that connect to a give class of device.
16+
IOC instances that connect to a given class of device.
2317

24-
An IOC instance will use a generic IOC image plus some configuration that
25-
will bootstrap the unique properties of the instance. In nearly all cases the
26-
configuration need only be a single IOC boot script.
18+
An IOC instance runs in a container that bases its
19+
filesystem on a generic IOC image.
20+
In addition the instance has configuration mapped into the
21+
container that will bootstrap the unique properties of that instance.
22+
In most cases the configuration need only be a single IOC boot script.
2723

2824
This approach reduces the number of images required and saves disk. It also
2925
makes for simple configuration management.

‎docs/explanations/net_protocols.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Channel Access and Other Protocols
2+
==================================
3+
4+
explanations of the challenges and solutions
5+
6+
**TODO**

‎docs/explanations/strategy.rst

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
Kubernetes for EPICS IOCs strategy
22
==================================
33

4-
Todo
4+
**TODO** this page will draw from presentation slides
5+
6+
Hopefully using https://github.com/dbrnz/pptx2svg/tree/main/pptx2svg or some
7+
other conversion utility and keep the PPTX in the repo.
58

‎docs/explanations/whats_in.rst

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
epics-containers Contents
2+
=========================
3+
4+
The epics-containers organization contains the following elements.
5+
6+
Example Beamline
7+
----------------
8+
9+
By way of example we will include a full implementation of the
10+
test beamline BL45P at Diamond Light Source.
11+
12+
The benefit of this is that it will be live and constantly kept up to date with
13+
the latest developments. Also proven to work (**TODO** ref documentation on the
14+
DLS beamline Kubernetes infrastructure)
15+
16+
The downside is that it will only serve as an example; those without access
17+
to the beamline will not be able to run the code without getting errors.
18+
19+
**TODO**: supply a demo beamline that is based purely on simulated devices
20+
so that anyone can experiment with Kubernetes for EPICS IOCs.
21+
22+
23+
Production generic IOCs
24+
-----------------------
25+
26+
The generic IOC container images supplied here are intended for general use.
27+
All EPICS modules included in these images are vanilla versions direct from
28+
their official repositories with no changes as far as possible.
29+
30+
A great benefit of using containers is that you can adjust the container
31+
environment to suit the software instead of needing to modify the software to
32+
suit your organizations infrastructure.
33+
34+
Therefore there is a real possibility that multiple facilities can use the
35+
same images with all the economies of scale that this implies.
36+
37+
These generic images are intended to be used in production at DLS once the
38+
Beamline Kubernetes infrastructure is rolled out.
39+
40+
41+
Utilities
42+
---------
43+
44+
The repository k8s-epics-utils contains scripts simplifying the
45+
managing IOCs using helm and kubectl. It also contains a personal
46+
container for developers, this allows a developer to work on the support
47+
modules and IOCs without installing anything on their desktop except docker.
48+
49+
50+
Packages in the Organization
51+
----------------------------
52+
53+
In addition to source repositories the epics-containers organization also hosts
54+
the container images and helm charts that it generates. See
55+
https://github.com/orgs/epics-containers/packages for the packages registry
56+
that stores these.
57+
58+
59+
Naming Convention for Repositories
60+
----------------------------------
61+
62+
The following naming conventions help identify the source repositories. Note
63+
that where a repository generates an image the image will have the same name.
64+
65+
:epics:
66+
this prefix is for images that are nodes in the network of
67+
image dependencies.
68+
e.g. epics-base, epics-adcore
69+
70+
:iocs:
71+
this prefix is for images that are leaves in the network of
72+
image dependencies. These are the images which IOC instances make
73+
containers from. e.g. ioc-pmac, ioc-adaravis
74+
75+
:k8s:
76+
this prefix is for utilities and documentation repos.

‎docs/how-to/debug.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Debug an IOC instance locally
2+
=============================
3+
Todo
4+
5+
Debug an IOC instance in Kubernetes
6+
===================================
7+
Todo

‎docs/how-to/generic_iocs.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Run an IOC without Kubernetes
2+
=============================
3+
4+
**TODO**

‎docs/how-to/kubernetes_cluster.rst

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Central Kubernetes Cluster Config
2+
=================================
3+
4+
**TODO** this section will give details of the topology and special
5+
configuration used by the DLS argus cluster to enable running
6+
IOCs on a Beamline.
7+
8+
Brief Overview of DLS Argus cluster
9+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10+
11+
Beamline Local Cluster Nodes
12+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
13+
14+
hostNetwork = true
15+
~~~~~~~~~~~~~~~~~~
16+
17+
Namespaces and Permissions
18+
~~~~~~~~~~~~~~~~~~~~~~~~~~
19+
20+
Taints and Tolerances
21+
~~~~~~~~~~~~~~~~~~~~~

‎docs/how-to/manage_iocs.rst

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

‎docs/how-to/setup_k8s.rst

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

0 commit comments

Comments
 (0)