You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/reference/cli.md
+13-8Lines changed: 13 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,15 +4,15 @@
4
4
5
5
The python project {any}`edge-containers-cli` is installed as part of the Python section of the initial tutorial {any}`../tutorials/setup_workstation`. It provides a command line function `ec` with support for:
6
6
7
-
- deploying, managing and debugging IOCs and other application Instances
7
+
- deploying, managing and monitoring IOC and service instances
8
8
9
9
The CLI is just a thin wrapper around the underlying tools that do the real work:
10
10
11
11
```{eval-rst}
12
12
13
13
:kubectl: the command line interface to the Kubernetes APIs
14
14
:helm: the command line interface to the Kubernetes Helm package manager
15
-
:podman (or docker): CLIs for container engines
15
+
:podman/docker: CLIs for container engines
16
16
:git: the git version control system client
17
17
```
18
18
@@ -23,11 +23,16 @@ To see the available commands, run `ec --help`.
23
23
It may be instructive to understand the underlying tools and how they are being called. For this reason `ec` supports a `-v` option to show the underlying commands being executed. e.g.
24
24
25
25
```{raw} html
26
-
<pre>$ ec -v ps
27
-
<font color="#5F8787">kubectl get namespace p38-iocs -o name</font>
28
-
<font color="#5F8787">kubectl -n p38-iocs get pod -l is_ioc==True -o custom-columns=IOC_NAME:metadata.labels.app,VERSION:metadata.labels.ioc_version,STATE:status.phase,RESTARTS:status.containerStatuses[0].restartCount,STARTED:metadata.managedFields[0].time</font>
In this tutorial we will create a new {any}`ec-services-repo`.
6
6
7
-
All IOC Instances that we deploy will be grouped into domains and each
8
-
domain will have its own repository which defines those Instances.
9
-
Typically each beamline would have its own domain and
10
-
the accelerator would be split into a few functional domains.
7
+
All IOC Instances that we deploy will be grouped into repositories that define a set of IOC and service instances. Typically each beamline would have its own repository and the accelerator would be split by location or technical area.
11
8
12
-
In the case of Beamlines, the domain is named after the beamline itself. At DLS
9
+
In the case of Beamlines, the repo is named after the beamline itself. At DLS
13
10
we use the naming convention `blxxc` where `xx` is the beamline number,
14
11
and c is the class of beamline.
15
12
@@ -19,25 +16,18 @@ numbers and hyphens only are recommended for both domain names and
19
16
IOC names. This is a restriction that helm introduces for package names.
20
17
:::
21
18
22
-
We are going to create the test beamline repository `bl01t`.
23
-
When the project `bl01t` is pushed to GitHub, continuous integration will
24
-
verify that each of the IOCs in the beamline are valid by launching them
25
-
with basic configuration.
19
+
Here we are going to create the test beamline repository `bl01t`. When the project `bl01t` is pushed to GitHub, continuous integration (CI) will verify each of the IOC instances.
26
20
27
-
The tests on beamline repositories are basic at present. However the intention
28
-
is that eventually each device on a beamline will be simulated using
29
-
[Tickit](https://github.com/dls-controls/tickit) . Then Continuous
30
-
Integration will perform system tests for each IOC against simulated hardware.
21
+
This beamline repository will be made from a template that comes with a single example IOC and further steps in the following tutorials will teach you how to add your own.
31
22
32
-
Also note that each of these IOC instances will be launched using a
33
-
Generic IOC image. Ideally the CI for each Generic IOC should have already run
34
-
system tests against simulated (but not beamline specific) hardware.
35
-
36
-
This beamline repo will be taken from a template that comes with a single example
37
-
IOC and further steps in the following tutorials will teach you how to add your own.
23
+
:::{note}
24
+
If you are going to work in a shared environment then it is worth choosing
25
+
a different name for your test beamline and its associated PV prefixes. PVs
26
+
will be published on the local subnet by default so two people working on the
27
+
tutorials without doing this will clash. If you do this just remember to
28
+
substitute your beamline name for `bl01t` in the following instructions.
29
+
:::
38
30
39
-
For accelerator domains the approach described here will be identical. The
40
-
only difference is that IOC repos are split by domain rather than by beamline.
41
31
42
32
## To Start
43
33
@@ -52,135 +42,72 @@ You will also need to setup ssh keys to authenticate to github from git. See
52
42
53
43
## Create a New Repository
54
44
55
-
Here we will copy the beamline template repository and change its name to bl01t.
56
-
We will then step through the changes that are required to make it your own.
45
+
Here we will use the copy the ec services template repository to make a new beamline.
57
46
58
47
NOTE: for these tutorials we will use your personal GitHub Account to
59
48
store everything we do, all source repositories and container images. For
60
49
production, each facility will need its own policy for where to store these
61
-
assets. See `../explanations/workspacesitories`.
50
+
assets. See `../explanations/repositories`.
62
51
63
52
## Steps
64
53
65
-
1. Go to the template repository here:
66
-
<https://github.com/epics-containers/blxxi-template>. Click on the green
67
-
button `Use this template` and follow the instructions to create a new
68
-
repository in your own account and give it the name bl01t.
54
+
1. Go to your GitHub account home page. Click on 'Repositories' and then 'New', give your new repository the name `bl01t` plus a description, then click 'Create'.
69
55
70
56
If you are using an alternative to GitHub for your repositories then
71
57
see [these instructions] for an alternative approach.
72
58
73
-
2. Clone the template repo locally (substituting in your own GitHub Account).
59
+
1. From a command line with your virtual environment activated. Use copier to start to make a new repository like this:
60
+
61
+
```bash
62
+
pip install copier
63
+
# this will create the folder bl01t in the current directory
- The existing script code in blxxi-template is fine for this tutorial.
127
-
It checks to see if `ec` is available and installs it into a
128
-
virtual environment if not. It requires that you already have a
129
-
virtual environment set up. See [](python-setup) for details.
130
-
131
-
- SECTION 3:
132
-
133
-
- We are not using Kubernetes for the first few tutorials so you can
134
-
leave this section blank for now.
135
-
136
-
:::{note}
137
-
DLS Users: `ec` is already installed for you. So leave SECTION 2
138
-
blank. See {any}`ec` for details.
139
-
:::
140
-
141
-
### Change the IOC Name
142
-
143
-
The IOC name is
144
-
taken from the folder name under `iocs`. In this case we want to change
145
-
`blxxi-ea-ioc-01` to `bl01t-ea-ioc-01`.
146
-
147
-
```bash
148
-
cd iocs
149
-
mv blxxi-ea-ioc-01 bl01t-ea-ioc-01
150
-
```
151
-
152
-
### Change the Beamline Name in Services
153
-
154
-
There are two files in the `services/` directory that need to be changed. These
155
-
files are used to set up some beamline wide resources on each beamline domain.
156
-
At present they are only relevant to Kubernetes installations but we will change
157
-
then now so that bl01t is ready for Kubernetes when we get to that tutorial.
158
-
159
-
Open both files in `services/` and replace blxxi with bl01t.
160
-
161
-
TODO: add support for local docker installations of these services.
162
-
163
-
### Change the Beamline Name in the Helm Chart
164
-
165
-
The file `beamline-chart/values.yaml` contains the configuration values
166
-
for the helm chart that is used to deploy the beamline. You can change
167
-
the values `blxxi` to `bl01t` in here. But this will not be relevant until
168
-
we get to the Kubernetes tutorial when the deployment is done using helm.
169
-
170
101
## Wrapping Up
171
102
172
-
You should now have a working beamline repository. It contains a single
173
-
IOC Instance which is a non-functional example. In the following two
174
-
tutorials we will investigate the example and then create a real IOC Instance.
103
+
You should now have a working beamline repository. It contains a single IOC Instance which is a very basic example. In the following two tutorials we will investigate the example and then create a real IOC Instance.
175
104
176
-
You can now push the repository up to GitHub and give it a version tag like this:
105
+
You can now give your repository a version tag like this:
177
106
178
107
```bash
179
-
git add .
180
-
git commit -m "changed blxxi to bl01t"
181
-
git push
182
-
git tag 2024.1.1
183
-
git push origin 2024.1.1
108
+
# open a terminal in vscode: Menu -> Terminal -> New Terminal
109
+
git tag 2024.2.1
110
+
git push origin 2024.2.1
184
111
```
185
112
186
113
We use `CalVer` version numbers for beamline repositories and Generic IOCs.
@@ -191,7 +118,7 @@ CalVer is described here: <https://calver.org/> and is used where semantic
191
118
versioning is not appropriate because the repository contains a mix of
192
119
dependencies and does not have a clear API.
193
120
194
-
Note that 2024.1.1 represents the time that this tutorial was last updated.
121
+
Note that 2024.2.1 represents the time that this tutorial was last updated.
195
122
For completeness you could use the current year and month instead. You
196
123
are also free to choose your own versioning scheme as this is not enforced by
0 commit comments