Prepare
Install Helm 3 and clone epik8s-chart. For deployment, your cluster also needs Kubernetes access, ArgoCD, the required platform services, and an IOC image accessible from the cluster.
THE EPIK8S GUIDEEPICS + K8S
EPICS + K8S
= EPIK8S
A practical path from beamline configuration to running EPICS IOCs: start with a read-only render, understand the components, then operate them with confidence.
01Quick startPreview a beamline configuration02ArchitectureHow the pieces fit03ManualAdd, deploy and troubleshoot
01 / EPIK8S
Quick start
This example checks how the current epik8s-chart turns a beamline description into an ArgoCD Application. It does not touch a cluster. The sample IP 192.0.2.10 is documentation data; replace it before any real deployment.
Describe one IOC
Set beamline, namespace, and epicsConfiguration.iocs in a YAML file. Choose a template and device fields that match an ibek-templates fixture. Use pinned image and chart revisions for a real beamline.
Preview the generated resources
Run Helm locally, inspect the resulting demo-ps01-ioc ArgoCD Application, and check the emitted values. The example below was rendered against the current chart source.
Example values
beamline: demo
namespace: demo
targetRevision: main
epicsConfiguration:
name: epics-configuration
address_list: ""
max_array_bytes: "10000000"
services: {}
iocs:
ps01:
name: ps01
template: ocem
devtype: modbusps
devgroup: mag
iocprefix: DEMO:MAG:OCEM
ps:
current: {max: 100}
voltage: {max: 16}
devices:
- name: PS01
ip: 192.0.2.10Render without deploying
git clone https://github.com/infn-epics/epik8s-chart.git
helm template demo ./epik8s-chart \
-f demo-values.yaml > rendered.yaml
# Inspect the Application for this IOC
rg 'demo-ps01-ioc|kind: Application' rendered.yamlThe example file is downloadable here. It renders a ConfigMap and an ArgoCD Application; it does not prove the hardware, image, networking, or services are ready.
Next step
For a real installation, place reviewed values in a beamline repository, point its ArgoCD Application to the chart and values, then sync in ArgoCD after checking the generated diff. Follow the beamline repository’s deployment convention; the umbrella chart creates child Applications for IOCs and services.
Questo esempio verifica come l’attuale epik8s-chart trasforma la descrizione di una beamline in un’Application ArgoCD. Non modifica alcun cluster. L’IP 192.0.2.10 è solo dimostrativo: sostituiscilo prima di una distribuzione reale.
Prepara l’ambiente
Installa Helm 3 e clona epik8s-chart. Per distribuire servono anche accesso a Kubernetes, ArgoCD, i servizi di piattaforma richiesti e un’immagine IOC raggiungibile dal cluster.
Descrivi un IOC
Imposta beamline, namespace e epicsConfiguration.iocs in YAML. Scegli template e campi del dispositivo in base a un esempio di ibek-templates. Per una beamline reale, fissa le versioni dell’immagine e dei chart.
Controlla le risorse generate
Esegui Helm in locale, esamina l’Application ArgoCD demo-ps01-ioc e i valori generati. L’esempio è stato verificato con il sorgente attuale del chart.
Valori di esempio
beamline: demo
namespace: demo
targetRevision: main
epicsConfiguration:
name: epics-configuration
address_list: ""
max_array_bytes: "10000000"
services: {}
iocs:
ps01:
name: ps01
template: ocem
devtype: modbusps
devgroup: mag
iocprefix: DEMO:MAG:OCEM
ps:
current: {max: 100}
voltage: {max: 16}
devices:
- name: PS01
ip: 192.0.2.10Rendering senza distribuire
git clone https://github.com/infn-epics/epik8s-chart.git
helm template demo ./epik8s-chart \
-f demo-values.yaml > rendered.yaml
# Controlla l'Application dell'IOC
rg 'demo-ps01-ioc|kind: Application' rendered.yamlIl file di esempio è scaricabile qui. Genera una ConfigMap e un’Application ArgoCD; non verifica hardware, immagine, rete o servizi.
Passo successivo
Per una vera installazione, salva i valori revisionati in un repository di beamline, configura l’Application ArgoCD per chart e valori, poi sincronizza dopo aver controllato la differenza generata. Segui le convenzioni del repository della beamline: il chart principale crea Application figlie per IOC e servizi.
02 / EPIK8S
Architecture
Beamline YAML
→epik8s-chart
→ArgoCD
→ioc-chart
→IOC runtime
Built in collaboration with Diamond Light Source
EPIK8S is the INFN implementation of the epics-containers framework developed at Diamond Light Source. The shared approach to containerized IOCs and IBEK informs this architecture; use the upstream documentation alongside the INFN repositories.
In collaborazione con Diamond Light Source
EPIK8S è l’implementazione INFN del framework epics-containers sviluppato a Diamond Light Source. L’approccio condiviso agli IOC containerizzati e a IBEK contribuisce a questa architettura; consulta la documentazione originale insieme ai repository INFN.
The beamline values define IOCs, soft IOCs, services, applications, and cron jobs. epik8s-chart emits an ArgoCD Application per component. For hardware IOCs, ioc-chart creates the workload and passes its values to the generic INFN IOC runtime image. Its Jinja templates produce ibek YAML; ibek generates the EPICS startup script and database.
Beamline repository
Owns deploy/values*.yaml, device inventory, optional custom IOC configuration, and local operations policy.
epik8s-chart
Creates child Applications, merges iocDefaults with IOC entries, and carries common beamline values into each deployment.
ioc-chart + runtime
Deploys the IOC pod, ConfigMap, networking and mounts. The image contains the compiled support modules and templates.
Platform layer
epik8s-platform describes shared networking, storage, monitoring and backend services. It has cluster-specific prerequisites and must be planned separately.
The complete source explanation lives in the IOC architecture guide. This site is a navigable overview; use the repositories as the source of truth for exact values and versions.
I valori della beamline definiscono IOC, soft IOC, servizi, applicazioni e job pianificati. epik8s-chart genera un’Application ArgoCD per componente. Per gli IOC hardware, ioc-chart crea il workload e passa i valori all’immagine IOC INFN generica. I template Jinja producono YAML ibek; ibek genera script di avvio e database EPICS.
Repository beamline
Contiene deploy/values*.yaml, inventario dispositivi, eventuali configurazioni IOC personalizzate e regole operative locali.
epik8s-chart
Crea le Application figlie, unisce iocDefaults alle voci IOC e trasferisce i valori comuni della beamline.
ioc-chart e runtime
Distribuisce pod IOC, ConfigMap, rete e mount. L’immagine contiene moduli di supporto compilati e template.
Piattaforma
epik8s-platform descrive rete, storage, monitoraggio e servizi backend condivisi. Ha prerequisiti specifici del cluster da pianificare a parte.
La spiegazione completa è nella guida all’architettura IOC. Questa pagina offre una panoramica navigabile; per valori e versioni esatti fanno fede i repository.
03 / EPIK8S
Manual
Add an IOC
Start from a matching template fixture. Add an entry under epicsConfiguration.iocs with name, template, devtype, iocprefix and devices. Put family defaults in iocDefaults.<template>; the IOC entry overrides them. Render and review before sync.
Use a custom IOC
An IOC without template can load configuration from a beamline Git path such as config/iocs/<name>. The runtime also supports a remote host path. Choose the mode deliberately and keep its source in version control.
Add services
Define a service under epicsConfiguration.services with its charturl and service-specific values. The umbrella chart creates a separate ArgoCD Application. Shared backends may depend on epik8s-platform; check the cluster prerequisites first.
Version a change
Templates are baked into infn-epics-ioc-runtime. After changing ibek-templates or support modules, update the submodule in infn-epics-ioc, publish a runtime image, then pin the beamline’s image or ioc_version. Keep chart revisions explicit for repeatable deployments.
Operate and inspect
Review the ArgoCD diff and sync status, then inspect the child Application, pod events and logs. Most IOC deployments use manual sync unless autosync is enabled. The pod log and optional NFS runtime folder show rendered configuration and startup output.
Troubleshoot
A missing template usually means the image predates it. An unknown ibek entity usually means its support module is absent from the image. Connection checks fail when the configured device cannot be reached. Check the image tag, generated YAML, pod logs, and hardware path before changing configuration.
Private Git
The charts support epik8s_secrets and the optional git_credentials_secret for clone credentials. Follow the credential guide; keep tokens in Kubernetes Secrets, not in beamline values.
Aggiungi un IOC
Parti da un esempio del template. Aggiungi una voce in epicsConfiguration.iocs con name, template, devtype, iocprefix e devices. Metti i valori comuni in iocDefaults.<template>; la voce IOC prevale. Esegui il rendering e verifica prima della sincronizzazione.
IOC personalizzato
Un IOC senza template può caricare la configurazione dal repository della beamline, ad esempio config/iocs/<name>. Il runtime supporta anche un percorso host remoto. Scegli la modalità in modo esplicito e mantieni il sorgente sotto controllo versione.
Aggiungi servizi
Definisci un servizio in epicsConfiguration.services con charturl e valori specifici. Il chart principale crea un’Application ArgoCD separata. I backend condivisi possono dipendere da epik8s-platform: controlla prima i prerequisiti del cluster.
Gestisci le versioni
I template sono inclusi nell’immagine infn-epics-ioc-runtime. Dopo modifiche a ibek-templates o ai moduli di supporto, aggiorna il submodule in infn-epics-ioc, pubblica l’immagine runtime e fissa l’immagine o ioc_version della beamline. Usa revisioni esplicite dei chart.
Gestisci e controlla
Verifica differenza e stato di sincronizzazione in ArgoCD, poi Application figlia, eventi e log del pod. Per molti IOC la sincronizzazione è manuale, salvo autosync attivo. Il log e l’eventuale cartella runtime su NFS mostrano configurazione generata e avvio.
Diagnostica
Un template mancante indica spesso un’immagine precedente al template. Un’entità ibek sconosciuta indica di solito un modulo di supporto assente dall’immagine. Un errore di connessione indica che il dispositivo non è raggiungibile. Controlla tag, YAML generato, log e collegamento hardware prima di modificare la configurazione.
Git privato
I chart supportano epik8s_secrets e l’opzione git_credentials_secret per l’autenticazione dei cloni. Segui la guida alle credenziali; conserva i token nei Secret Kubernetes, non nei valori della beamline.
04 / EPIK8S
Source documentation
IOC architecture ↗epik8s-chart ↗ioc-chart ↗ibek-templates ↗epik8s-platform ↗Git credentials ↗epics-containers · Diamond ↗
This guide summarizes repository behavior inspected in October 2026. Check the linked source before applying changes to a facility.