Create a Kubernetes Beamline#

Warning

DLS users: beamlines and accelerators are set up through the internal developer guide at https://dev-guide.diamond.ac.uk/epics-containers/, not these public cluster steps. Follow along on your own test cluster only.

So far the tutorials have deployed IOCs to the local podman instance on your workstation with docker compose. This tutorial creates a services repository that deploys into a Kubernetes cluster instead, using Helm.

By the end you will have:

  • a services repo, t02-services, generated from services-template-helm;

  • the shared beamline services t02-epics-pvcs and t02-epics-opis running in your cluster;

  • the ec CLI configured to deploy and manage services in your namespace.

The worked example uses the domain t02 (beamline bl02t) and the namespace t02-beamline created in Set up a Kubernetes Cluster. Substitute your own names throughout.

Note

A Helm/Kubernetes services repo has the same shape as the docker compose one from Create a Beamline Services Repository: a services/ folder with one deployable unit per subfolder. The difference is that each unit is a Helm chart (a Chart.yaml plus a values.yaml) rather than a compose.yaml, and services/values.yaml holds the defaults shared by every chart.

Prerequisites#

Scaffold the services repo#

Generate the repo from the template with copier (the flow mirrors Create a Beamline Services Repository):

copier copy https://github.com/epics-containers/services-template-helm t02-services

Answer the prompts as follows for a local k3s cluster:

Prompt

Worked-example answer

domain

t02

description

(accept default — t02 IOC Instances and Services)

location

bl02t

cluster_name

local (any lower-case name for your cluster)

cluster_namespace

t02-beamline

git_platform

github.com

gateway

No (k3s uses host networking — see below)

athena_services

(leave blank)

logging_url

Skip

Note

The template defines copier migration scripts that run when you later bring the repo up to a newer template version with copier update. Those scripts require the --trust flag, i.e. copier update --trust.

Create the repo on GitHub (new) named t02-services, then commit and push:

cd t02-services
git init -b main
git add .
git commit -m "initial commit"
git remote add origin https://github.com/<your-account>/t02-services
git push -u origin main

Configure the ec CLI#

ec wraps helm and kubectl to deploy and manage services. Install it if you do not have it already, then source the generated environment.sh from inside the repo:

# install ec if needed (see the workstation setup)
uv tool install edge-containers-cli
# from inside the t02-services directory:
source ./environment.sh

environment.sh configures ec for this repo by exporting:

export EC_CLI_BACKEND=K8S                                  # deploy with Helm/kubectl
export EC_TARGET=t02-beamline                              # your namespace
export EC_SERVICES_REPO=https://github.com/<your-account>/t02-services
export EC_LOG_URL=                                         # central log server (blank)

It also checks that ec is installed and enables shell completion. For the full command and environment-variable reference see edge-containers-cli.

Deploy the shared services#

Every beamline namespace needs two shared services, both generated by the template:

  • t02-epics-pvcs — persistent volumes where IOCs store autosave files, generated GUIs and other data.

  • t02-epics-opis — an nginx server that serves those GUI files.

ec deploys a service at a git tag of the repo, so tag the current state first:

git tag 2026.7.1
git push origin 2026.7.1

Then deploy each service at that tag (-v prints the underlying helm/kubectl commands):

ec -v deploy t02-epics-pvcs 2026.7.1
ec -v deploy t02-epics-opis 2026.7.1

Note

On a local k3s cluster the template sets hostNetwork: true (in services/values.yaml), so Channel Access reaches your workstation directly and no gateway is needed. Clusters that forbid host networking — including DLS personal namespaces — instead run a Channel Access gateway; answer Yes to the gateway prompt to have the template generate one.

Check the deployment#

List what is running in your namespace:

ec ps

 name             label     version    ready   deployed
 t02-epics-pvcs   service   2026.7.1   True    2026-07-01T09:10:00Z
 t02-epics-opis   service   2026.7.1   True    2026-07-01T09:11:00Z

Run ec --help to explore the other commands (ec logs, ec exec, ec monitor, ec stop/start/delete).

Note

When something will not start, inspect the underlying resources with kubectl describe pod <name>, or browse them in the Kubernetes dashboard (see Set up the Kubernetes dashboard (optional) for the local-cluster install).

Next steps#