bc_interlink_node

Open OnDemand Batch Connect app template to run an interLink API server and Slurm sidecar plugin in a single on-demand session.

What this template provides

• manifest.yml, form.yml, submit.yml.erb — OSC Batch Connect app structure
• template/before.sh.erb — selects a free port, writes InterLinkConfig.yaml and SlurmConfig.yaml
• template/script.sh.erb — starts the plugin (unix socket) then the API server, waits for readiness
• template/after.sh.erb — waits for the API server to respond before OOD marks the session Running
• view.html.erb — session card showing proxy URL and auth guidance for interlink-vk
• etc/ood/clusters.d/login_node.yml.example — example cluster config for login-node (no-scheduler) mode

Installation

Clone this repository into your Open OnDemand system apps path:

cd /var/www/ood/apps/sys
git clone https://github.com/interlink-hq/bc_interlink_node.git

Edit form.yml to set your cluster ID(s). The cluster ID is the filename of the cluster config file without the .yml extension (e.g. slurm_local.yml → "slurm_local").

The job environment must provide these two binaries (via PATH, modules, or full path):

• interlink — the interLink API server (v0.7.x+)
• interlink-sidecar-slurm — the Slurm sidecar plugin (v0.6.x+)

Deployment modes

This app supports two modes, selected by the cluster config.

Mode 1: Slurm batch job (default)

interLink runs inside a Slurm job. Suitable when you want resource accounting or the interLink server needs to run on a compute node.

Configure a standard Slurm cluster in /etc/ood/config/clusters.d/ and set its ID in form.yml:

cluster:
  - "slurm_local"   # ID = filename without .yml

Mode 2: Login-node systemd service (no scheduler)

interLink runs as a transient systemd user service on the login node, via OOD's built-in systemd job adapter. No Slurm slot is consumed; the service persists as long as the OOD session is open.

Prerequisites:

1. SSH key access from the OOD server to the login node as the user (no password prompt). For single-node setups where OOD and the login node are the same host:

   ssh-keygen -t ed25519 -N '' -f ~/.ssh/id_ed25519
   ssh-copy-id <username>@localhost

2. Deploy the included cluster config example:

   cp /var/www/ood/apps/sys/bc_interlink_node/etc/ood/clusters.d/login_node.yml.example \
      /etc/ood/config/clusters.d/login_node.yml

   Then edit login_node.yml and set submit_host and ssh_hosts to your login node's hostname(s). ssh_hosts must list every name returned by hostname -A on the login node — the adapter validates the actual hostname against this list.

3. Set cluster: ['login_node'] in form.yml (or list both clusters so users can choose):

   cluster:
     - "slurm_local"
     - "login_node"

What happens on submit: OOD SSHes to the login node and runs the job script as a transient systemd-run --user service with loginctl enable-linger. The session appears in "My Interactive Sessions" and can be stopped from the OOD UI.

Usage

1. Launch InterLink Node from the OOD Interactive Apps menu.
2. Fill in the form (cluster, number of cores, commands).
3. Submit — wait for the session card to show Running.
4. Copy the Server URL through OnDemand from the session card.
5. Point your interlink-vk pod configuration to that endpoint.

Logs are written in the selected working directory with a host/port suffix:

• interlink-plugin-<host>-<port>.log
• interlink-server-<host>-<port>.log

OOD reverse proxy configuration

To expose the interLink API through OOD's reverse proxy (recommended for interlink-vk access), enable rnode_uri in /etc/ood/config/ood_portal.yml:

node_uri: '/node'
rnode_uri: '/rnode'
strip_proxy_headers: []

Regenerate and reload:

sudo /opt/ood/ood-portal-generator/sbin/update_ood_portal
sudo systemctl reload httpd

The interlink-vk endpoint becomes http://<ood-server>/rnode/<job-host>/<port>. Use /rnode/ (not /node/) — it strips the OOD path prefix before forwarding, so API paths like /status and /apis/v1beta/pods reach interLink correctly.

API client authentication (issue OSC/ondemand#5514)

OOD's proxy sets the X-Forwarded-User header to the authenticated username before forwarding requests to the backend. Configure interLink to authorise based on this header — no separate bearer token is required from the client.

interlink-vk authenticates to OOD with its standard credential (Basic or OIDC) and OOD takes care of populating X-Forwarded-User on every proxied request.

Security note

The generated InterLinkConfig.yaml binds the interLink API server to 0.0.0.0 so that interlink-vk can reach it. The sidecar plugin communicates only via a local Unix socket and is never exposed on a TCP port. Restrict the server bind address or apply firewall rules if your deployment requires tighter network controls.

Appendix: Bearer token relay for additional backend authentication

By default this app relies on OOD's X-Forwarded-User header to identify the caller. If your interLink deployment also requires a dedicated Bearer token on the backend (e.g. a Kubernetes service-account token), you can enable the token relay patch included in this repository.

The patch adds 7 lines to OOD's node_proxy.lua handler: when a request carries an X-Interlink-Token: Bearer <token> header, the handler promotes it to Authorization: Bearer <token> before proxying to the backend. The client sends its OOD credential in the standard Authorization header and the backend token in the custom header — both travel through the single HTTP connection.

Apply the patch:

sudo patch /opt/ood/mod_ood_proxy/lib/node_proxy.lua \
     /var/www/ood/apps/sys/bc_interlink_node/node_proxy_token_relay.patch
sudo systemctl reload httpd

Revert if needed:

sudo patch -R /opt/ood/mod_ood_proxy/lib/node_proxy.lua \
      /var/www/ood/apps/sys/bc_interlink_node/node_proxy_token_relay.patch
sudo systemctl reload httpd

Once applied, configure interlink-vk to send:

• Authorization: Basic <base64(user:pass)> (or an OIDC bearer token) for OOD auth
• X-Interlink-Token: Bearer <service-account-token> for the interLink backend