Ansible collection meant for centralizing deployment logic for EPICS IOC instances.
The nsls2.ioc_deploy collection expects to be used in tandem with two other
(currently private) repositories: one with the playbook that eventually calls
these roles with input parameters
(deploy_ioc.yml),
and another for storing IOC instance configurations
(ioc_host_vars). See the NSLS2
internal deployment documentation:
Development Environment Setup.
The collection includes several core central roles that are shared by all
deployments, and then one role per type of IOC/hardware/device, found under
roles/device_roles/. Each IOC type also has a vars file for overriding
default behaviors in roles/deploy_ioc/vars/. Any required EPICS modules can be
automatically built by the install_module role. The configured modules can be
seen at roles/install_module/vars/.
If you require an EPICS module as a dependency, but don't plan on deploying it as an IOC, then you can make only the module.
pixi run make-moduleFollow the prompts to get started. See install_module for a full reference on supported options.
You can then add this module to the module_deps of any device role.
If you have a new EPICS module that you also plan to deploy as an IOC, then you can make a device role. This will also prompt you to make the installable module.
pixi run make-roleFollow the prompts to get started. See deploy_ioc and install_module for full references on supported options. Furthermore, if a similar device exists (it probably does), then browse the device_roles before starting.
There are a few required items to help make this repository more maintainable. They are:
- a
schema.ymldefining how to configure the role for deployment - an example configuration (either
examples/<name>/config.ymlor legacyexample.yml)
You can deploy your example configuration locally. Please see the section on Local Testing.
Simply make changes to the device role and submit a pull request to this repository. Breaking changes to existing schemas will need to be justified.
If you require a new version of the IOC, you will need to
add a new installable module with that
specific Git commit hash. Then, you can override the
deploy_ioc_required_module of the existing device role to point to this new
installable module.
If the newest version is not a major release (i.e. does not contain breaking changes), then you can likely update the existing installable module to use the new Git commit hash. Be sure to extensively test with real hardware before and after doing this.
You can update the module by running:
pixi run update-module[!NOTE] Maintainers of this repository will periodically update important installable modules to keep up with version changes. Please submit an issue if you notice we are behind.
This requires pixi and docker or podman.
Deploy a device role's example configuration into a local container:
pixi run deployment --container -t <role-name>Deploy all examples across multiple EL versions:
pixi run deploy-allThe deployment script automatically pulls the required
ghcr.io/nsls2/epics-alma{8,9}:latest container image and manages the container
lifecycle.
If a role needs the test container prepared before its examples deploy (e.g.
creating directories or files that exist on real hosts but not in the
container), add a script at
roles/device_roles/<role-name>/test_hooks/pre_deploy.sh and/or
pre_deploy.py. These hooks:
- only run for
--containerdeployments (never against real hosts with-l), and are skipped on--dry-run - run as root inside the container via
bash/python3(the shell script runs first if both exist) - run once per role per container, before that role's first example is deployed
- receive the
IOC_DEPLOY_ROLEandIOC_DEPLOY_EL_VERSIONenvironment variables
If a hook exits non-zero, that role's examples are marked as failed and not
deployed. Hooks should be idempotent, since the same container may be reused
across runs. The test_hooks directories are excluded from the built
collection.
Run using pixi run <command>.
| Command | Purpose |
|---|---|
make-role |
Make a new deployment role |
make-module |
Make a new installable module |
update-module |
Update an existing installable module |
delete-role |
Remove an existing deployment role |
delete-module |
Remove an existing installable module |
report |
View the status of this Ansible collection |
lint |
Run all pre-commit hooks against every file |
lint-files |
Run pre-commit hooks on specific files (after --) |
lint-changes |
Lint only the staged changes |
tests |
Run tests |
deployment |
Deploy example configs locally (interactive) |
deploy-all |
Deploy all examples in containers across EL matrix |
ruff-fix |
Auto-fix linting issues |
Linting is done with pre-commit, using the same hook
set as NSLS2/ansible (ruff, pyright,
codespell, markdownlint, yamllint, zizmor, actionlint, ansible-lint, biome,
shellcheck, and gitleaks). The lint tools live in the pixi dev environment. To
run the hooks on every commit, install them with:
pixi run -e dev pre-commit installCI runs the same hooks against changed files via the Lint workflow.