|
| 1 | +The Environment Configuration File |
| 2 | +================================== |
| 3 | + |
| 4 | +``environment.sh`` is a configuration file that is provided in each domain |
| 5 | +(beamline or accelerator) repository. It is used to set up the environment |
| 6 | +such that the ``epics-containers-cli`` will interact with the correct |
| 7 | +cluster (or local server if you are not using Kubernetes). |
| 8 | + |
| 9 | +An important part of creating a new domain repository is to edit the |
| 10 | +``environment.sh`` so that it suits the domain you are targetting. |
| 11 | + |
| 12 | +There are 3 sections to the file as follows: |
| 13 | + |
| 14 | +Environment Variables Setup |
| 15 | +--------------------------- |
| 16 | + |
| 17 | +The first section defines a number of environment variables. These should |
| 18 | +be adjusted to suit your domain. The variables are as follows: |
| 19 | + |
| 20 | + |
| 21 | +Required Variables |
| 22 | +~~~~~~~~~~~~~~~~~~ |
| 23 | + |
| 24 | +- **EC_REGISTRY_MAPPING**: defines a mapping between git source repositories and |
| 25 | + container repositories. This is used to determine where a Generic IOC |
| 26 | + container image is pushed to (or pulled from). If you are using GitHub then |
| 27 | + you could use the following value: |
| 28 | + |
| 29 | + - ``EC_REGISTRY_MAPPING='github.com=ghcr.io'`` |
| 30 | + |
| 31 | + Which means containers whose source repository is at: |
| 32 | + |
| 33 | + - ``GitHub/organisation/my_generic_ioc`` |
| 34 | + |
| 35 | + will be pushed to: |
| 36 | + |
| 37 | + - ``ghcr.io/organisation/my_generic_ioc:VERSION``. |
| 38 | + |
| 39 | + You can have multiple mappings if needed by separating them with a space. |
| 40 | + |
| 41 | +- **EC_NAMESPACE**: defines the namespace in a Kubernetes Cluster that your IOC |
| 42 | + Instances will be deployed to. When you come to set up a cluster you will |
| 43 | + need to create a namespace for your domain. This is the name you should |
| 44 | + use here. If you are not using Kubernetes then you can leave this as |
| 45 | + ``EC_NAMESPACE=`` and this will deploy IOC Instances to the local server's |
| 46 | + docker or podman instance. |
| 47 | + |
| 48 | +- **EC_DOMAIN_REPO**: this is a link back to the repository that defines this |
| 49 | + domain. For example the bl38p reference beamline repository uses |
| 50 | + `` [email protected]:epics-containers/bl38p.git``. This variable |
| 51 | + is used by ``ec`` to fetch versioned IOC Instance from the repo and deploy |
| 52 | + time. |
| 53 | + |
| 54 | + |
| 55 | +Optional Variables |
| 56 | +~~~~~~~~~~~~~~~~~~ |
| 57 | + |
| 58 | +- **EC_LOG_URL**: if you have a centralized logging service with a web UI then |
| 59 | + you can set this variable to the URL of the web UI. This will then be |
| 60 | + displayed when the command ``ec ioc log-history <ioc-name>`` is run. The |
| 61 | + ioc name is added to the URL using ``{ioc-name}`` as a placeholder e.g. |
| 62 | + |
| 63 | + - ``EC_LOG_URL='https://graylog2.diamond.ac.uk/search?rangetype=relative&fields`` |
| 64 | + ``=message%2Csource&width=1489&highlightMessage=&relative=172800&q=pod_name%3A`` |
| 65 | + ``{ioc_name}*'`` |
| 66 | + |
| 67 | +- **EC_CONTAINER_CLI**: this sets the name of the container CLI to use. supported |
| 68 | + options are ``podman`` or ``docker``. If not set then ``ec`` will try to |
| 69 | + determine which one to use. You would only need this variable if you have |
| 70 | + both podman and docker installed and you want to use one over the other, or |
| 71 | + if you want to use a different container CLI such as ``singularity``. |
| 72 | + IMPORTANT: the application you reference must have docker compatible CLI |
| 73 | + (at least for common functions). |
| 74 | + |
| 75 | +- **EC_DEBUG**: causes the ``ec`` command to output debug information for all |
| 76 | + commands. For more targetted debugging you can use ``ec -d ...``. |
| 77 | + |
| 78 | +Installation of ``ec`` |
| 79 | +---------------------- |
| 80 | + |
| 81 | +The second section of the ``environment.sh`` file is used to install the |
| 82 | +``ec`` command by pip installing the ``epics-containers-cli`` package. The |
| 83 | +``blxxi-template`` project comes with a suggested way of doing this, but |
| 84 | +it would probably be best to have ``ec`` installed globally on your |
| 85 | +workstation and then omit this section from your ``environment.sh`` files. |
| 86 | + |
| 87 | +Perhaps the simplest way to achieve this is to install ``ec`` into your user |
| 88 | +space using the following command: |
| 89 | + |
| 90 | +.. code:: bash |
| 91 | +
|
| 92 | + pip install --user epics-containers-cli |
| 93 | +
|
| 94 | +Then add the following to your ``.bashrc`` file: |
| 95 | + |
| 96 | +.. code:: bash |
| 97 | +
|
| 98 | + export PATH=$PATH:$HOME/.local/bin |
| 99 | +
|
| 100 | +Connecting to a Namespace on your Kubernetes Cluster |
| 101 | +---------------------------------------------------- |
| 102 | + |
| 103 | +The third section of the ``environment.sh`` sets up how the ``kubectl`` command |
| 104 | +will connect to a namespace on your Kubernetes cluster. This usually involves |
| 105 | +setting the ``KUBECONFIG`` environment variable to point to a file that contains |
| 106 | +the cluster configuration. |
| 107 | + |
| 108 | +When we set up a cluster in the tutorials we will create a namespace for your |
| 109 | +and discuss how to update ``environment.sh`` to connect to it. |
| 110 | + |
| 111 | +If you are connecting to your own facility's cluster then you will need to |
| 112 | +ask your admins for the correct configuration. |
| 113 | + |
| 114 | +If you are not using Kubernetes then you can leave this section out. |
| 115 | + |
| 116 | +.. note:: |
| 117 | + |
| 118 | + DLS users: the module system is used to connect us to each beamline/accelerator |
| 119 | + cluster. The example ``environment.sh`` file in ``bl38p`` shows how to do this |
| 120 | + see https://github.com/epics-containers/bl38p/blob/main/environment.sh |
| 121 | + |
| 122 | +One other thing that is useful is to set up command line completion for the |
| 123 | +Kubernetes tools ``kubectl`` and ``helm``. See the end of the bl38p |
| 124 | +``environment.sh`` file for an example of how to do this at |
| 125 | +https://github.com/epics-containers/bl38p/blob/main/environment.sh. |
| 126 | + |
| 127 | + |
| 128 | + |
0 commit comments