Skip to content

Commit c96e1e8

Browse files
gilesknapgilesknap
committed
add README
1 parent ba2046a commit c96e1e8

File tree

6 files changed

+106
-44
lines changed

6 files changed

+106
-44
lines changed

‎README.rst

Lines changed: 20 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,32 @@
1-
k8s_epics_docs
2-
===========================
1+
epics-containers Organization Documentation
2+
===========================================
33

4-
|code_ci| |docs_ci| |coverage| |pypi_version| |license|
4+
|docs_ci| |license|
55

6-
This is where you should write a short paragraph that describes what your module does,
7-
how it does it, and why people should use it.
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.
814

915
============== ==============================================================
10-
PyPI ``pip install k8s_epics_docs``
11-
Source code https://github.com/epics-containers/k8s-epics-docs
16+
Docs Source https://github.com/epics-containers/k8s-epics-docs
1217
Documentation https://epics-containers.github.io
1318
============== ==============================================================
1419

15-
This is where you should put some images or code snippets that illustrate
16-
some relevant examples. If it is a library then you might put some
17-
introductory code here:
18-
19-
.. code:: python
20-
21-
from k8s_epics_docs import HelloClass
22-
23-
hello = HelloClass("me")
24-
print(hello.format_greeting())
25-
26-
Or if it is a commandline tool then you might put some example commands here::
27-
28-
k8s_epics_docs person --times=2
20+
An important principal of the approach presented here is that an IOC container
21+
image represents a 'generic' IOC. The generic IOC image is used for all
22+
IOC instances that connect to a give class of device.
2923

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.
3027

31-
.. |code_ci| image:: https://github.com/epics-containers/k8s-epics-docs/workflows/Code%20CI/badge.svg?branch=master
32-
:target: https://github.com/epics-containers/k8s-epics-docs/actions?query=workflow%3A%22Code+CI%22
33-
:alt: Code CI
28+
This approach reduces the number of images required and saves disk. It also
29+
makes for simple configuration management.
3430

3531
.. |docs_ci| image:: https://github.com/epics-containers/k8s-epics-docs/workflows/Docs%20CI/badge.svg?branch=master
3632
:target: https://github.com/epics-containers/k8s-epics-docs/actions?query=workflow%3A%22Docs+CI%22

‎docs/how-to/accomplish-a-task.rst

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

‎docs/how-to/manage_iocs.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
Create a new generic IOC image
2+
==============================
3+
Todo
4+
5+
Create a beamline repository
6+
============================
7+
Todo
8+
9+
Add an IOC instance to a beamline
10+
=================================
11+
Todo
12+
13+
Debug an IOC instance locally
14+
=============================
15+
16+
Debug an IOC instance in Kubernetes
17+
===================================
18+
Todo

‎docs/how-to/setup_k8s.rst

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
Set up a lightwieght Kubernetes Cluster for experimentation
2+
===========================================================
3+
4+
# Intro
5+
This is a very easy set of instructions for setting up a Kubernetes cluster
6+
ready to deploy epics IOCs.
7+
8+
It has been tested on Ubuntu 20.10 and Raspbian Buster.
9+
10+
Give it a try, K3S provides a good uninstaller that will clean up your system
11+
if you decide to back out.
12+
13+
If you prefer to investigate other implementations there are also:
14+
15+
- kind https://kind.sigs.k8s.io/docs/user/quick-start/
16+
- microk8s https://microk8s.io/
17+
- minikube https://minikube.sigs.k8s.io/docs/start/
18+
19+
# Installation Steps
20+
21+
## Install K3S lightweight Kubernetes
22+
Execute this command on your server to set up the cluster master (aka K3S Server node):
23+
```
24+
curl -sfL https://get.k3s.io | sh -
25+
```
26+
27+
Install kubectl on the workstation from which you will be managing the cluster
28+
(workstation==server if you have one machine only)
29+
```
30+
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
31+
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
32+
```
33+
Go to the server machine and copy over the kubectl configuration to your
34+
workstation
35+
```
36+
sudo scp /etc/rancher/k3s/k3s.yaml <YOUR_ACCOUNT>@<YOUR_WORKSTATION>:.kube/config
37+
# edit the file .kube/config replacing 127.0.0.1 with your server IP Address
38+
```
39+
40+
## Create an epics IOCs namespace and context
41+
From the workstation execute the following:
42+
```
43+
kubectl create namespace epics-iocs
44+
kubectl config set-context epics-iocs --namespace=epics-iocs --user=default --cluster=default
45+
kubectl config use-context epics-iocs
46+
```
47+
48+
## Install helm
49+
Execute this on the workstation:
50+
```
51+
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3
52+
bash get_helm.sh
53+
```

‎docs/reference/cli.rst

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,23 @@ The underlying tools used are:
1111
- kubectl: https://kubernetes.io/docs/tasks/tools/
1212
- helm: https://helm.sh/docs/intro/install/
1313

14+
All the functions described below are simply shortcuts for helm and
15+
kubectl commands.
16+
1417
To enable the scripts you must have helm and kubectl installed and be
15-
authenticated to your kubernetes cluster. Then source the script:
18+
authenticated to your kubernetes cluster. You must also have enabled a
19+
kubectl context that connects to the kubernetes namespace in which you
20+
deploy your IOCs.
21+
22+
Declare the URL of your HELM registry and source kube-functions.sh to add
23+
the k8s-iocs function to your shell:
1624

17-
-
25+
- export K8S_HELM_REGISTRY=ghcr.io/epics-containers
26+
- wget https://raw.githubusercontent.com/epics-containers/k8s-epics-utils/main/epics-dev-image/home/bin/kube-functions.sh
27+
- source kube-functions.sh
1828

19-
The k8s-iocs shell function can perform the following opertions. In all cases
20-
these are simply shortcuts for helm and kubectl commands.
29+
The k8s-iocs shell function can perform the following opertions. Note that
30+
the command k8s-iocs with no parameters will print this list.
2131

2232
usage:
2333
k8s-ioc <command> <options>

‎tests/test_boilerplate_removed.py

Lines changed: 1 addition & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,6 @@
77
import pytest
88

99

10-
def test_module_description(setupcfg):
11-
if "One line description of your module" in setupcfg["description"]:
12-
raise AssertionError(
13-
"Please change description in ./setup.cfg "
14-
"to be a one line description of your module"
15-
)
16-
17-
1810
def assert_not_contains_text(path, text, explanation):
1911
with open(path, "r") as f:
2012
contents = f.read().replace("\n", " ")
@@ -39,7 +31,7 @@ def test_changed_README():
3931
# Docs
4032
def test_docs_ref_api_changed():
4133
assert_not_contains_text(
42-
"docs/reference/api.rst",
34+
"docs/reference/cli.rst",
4335
"You can mix verbose text with docstring and signature",
4436
"to introduce the API for your module",
4537
)

0 commit comments

Comments
 (0)