= Architecture
:figure-caption!:
:slurmrestd-release-notes: https://slurm.schedmd.com/openapi_release_notes.html

== Components

This diagram represents all Slurm-web components with their respective roles and
integration with Slurm workload manager:

.Slurm-web architecture with components roles [xref:image$arch/slurm-web_architecture.svg[icon:download[] SVG]]
image::arch/slurm-web_architecture.png[]

Slurm-web is based on 3 components:

* *agent*: Sends requests to Slurm `slurmrestd` service which exposes a REST
  API for `slurmctld` and `slurmdbd` daemons. The _agent_ is also in charge of
  the _authorizations_ enforcement and acts as a _caching_ layer over Slurm.
* *gateway*: Performs _user authentication_ and acts as a _reserve proxy_ for
  the _agents_.
* *frontend*: The _representation layer_ for the user interface. It is actually
  served by the _gateway_ application and executed on client side in web
  browsers.

NOTE: The *gateway* and *frontend* components are bundled together in the
Slurm-web _gateway_ system package and container image for simplicity. See
xref:#deployment[Deployment] section for more details.

[sidebar]
--
.More links
* https://slurm.schedmd.com/rest_quickstart.html[Slurm REST API Quick Start Guide]
* https://slurm.schedmd.com/rest.html[Slurm REST API Reference]
* https://slurm.schedmd.com/rest_api.html[Slurm REST API implementation details]
--

== Integration

In addition to Slurm workload manager, Slurm-web interacts with some other
external services and data sources:

.Slurm-web integration with external components [xref:image$arch/slurm-web_integration.svg[icon:download[] SVG]]
image::arch/slurm-web_integration.png[]

The *gateway* component authenticates users with either:

* *LDAP* — enterprise directories such as OpenLDAP, FreeIPA, and Active Directory,
  including legacy NIS and RFC 2307 bis schemas for groups.
* *OIDC* — single sign-on (SSO) with OpenID Connect identity providers such as
  https://www.keycloak.org/[Keycloak] or https://goauthentik.io/[Authentik].

The *agent* component reads the
xref:conf:policy.adoc[RBAC autorization policy] from a plain INI file with
permissions associated to roles and LDAP groups.

Optionally, the *agent* can also:

- Extract cluster racking topology from
  xref:racksdb:overview:start.adoc[RacksDB] database to generate
  xref:overview.adoc#nodes-status[interactive graphical representation of nodes status]
  in the racks.
- Connect to https://redis.io/[Redis] in-memory key/value database to
  xref:overview.adoc#cache[save cached data] from Slurm.
- Integrate with https://prometheus.io/[Prometheus] (or compatible) by exporting
  xref:overview.adoc#metrics[various Slurm metrics] for storage in timeseries
  database. The agent can then query this database to get historical values of
  these metrics.

[#protocols]
== Protocols

Protocols and authentication realms involved in communications between Slurm-web
and Slurm components are represented in this diagram:

.Protocols in communication between Slurm-web components [xref:image$arch/slurm-web_protocols.svg[icon:download[] SVG]]
image::arch/slurm-web_protocols.png[]

All communications from the clients web browsers to Slurm-web *agent*
component are performed with HTTP over TCP/IP network protocols. These
network communications can be secured with SSL/TLS (aka. HTTPS) over standard
port TCP/443 with a xref:conf:wsgi/index.adoc[production HTTP server]. After
initial authentication at the gateway with
xref:conf:auth/index.adoc[LDAP or OIDC], users are authenticated between these
components with https://jwt.io/[JSON Web Token] (JWT). Slurm-web has its own JWT
realm, with its dedicated JWT signing key, to secure communication between its
components.

Slurm `slurmrestd` supports incoming HTTP requests on:

* *TCP/IP socket*, with `rest_auth/jwt` authentication and tokens signed by
  Slurm JWT signing key.
* *Unix socket*, with two authentication methods: `rest_auth/jwt` and
  `rest_auth/local` _(deprecated)_ in which `slurmrestd` authenticates users
  with client process UID/GID.

Slurm-web *agent* supports all these combinations of sockets and authentication
methods. Please refer to
xref:conf:slurmrestd.adoc[slurmrestd access configuration page] for more
details.

Slurm components communicates with specific binary RPC protocol over TCP/IP
sockets, secured by either https://dun.github.io/munge/[Munge] or
https://slurm.schedmd.com/authentication.html#slurm[Slurm internal mechanism].
When JWT authentication is used between Slurm-web *agent* and Slurm `slurmrestd`
service, the `auth/jwt` alternative authentication type must also be enabled in
main Slurm and `slurmdbd` configuration.

[#multiclusters]
== Multi-clusters Distribution

Slurm-web is designed to support natively multiple HPC clusters with a central
dashboard. In this configuration, the components are distributed as represented
in this diagram:

.Slurm-web distribution on multiple clusters [xref:image$arch/slurm-web_distribution.svg[icon:download[] SVG]]
image::arch/slurm-web_distribution.png[]

In this configuration, the *agent* component must be deployed on all clusters
collocated with Slurm `slurmrestd` daemon. An *agent* interacts with only one
Slurm cluster.

The *gateway* can be deployed on a central server. It distributes the requests
to the *agents* deployed on the clusters.

[#deployment]
== Deployment

Slurm-web is distributed as system packages and as OCI container images for the
_agent_ and _gateway_ components. This section describes where these components
run in common deployment topologies. The same component split applies with both
system packages and container images.

=== Single cluster — collocated with Slurm

All Slurm-web components run on the same host as Slurm services (`slurmrestd`,
`slurmctld` and `slurmdbd`), typically the _admin_ node of the cluster:

.Slurm-web deployment on a single cluster [xref:image$arch/slurm-web_deployment_mono-cluster_collocated.svg[icon:download[] SVG]]
image::arch/slurm-web_deployment_mono-cluster_collocated.png[]

In this architecture, deploy the _agent_ and _gateway_ Slurm-web components on
the Slurm controller host.

This is the *simplest deployment topology* and is recommended for small clusters.

NOTE: The frontend component is included with the _gateway_ component, both in
the `slurm-web-gateway` package and in the `slurm-web-gateway` image. There is
no separate frontend deployment artifact.

=== Single cluster — separate server

Slurm-web components are deployed on a dedicated host (bare-metal, virtual
machine, or container host). Multiple deployment topologies are possible:
Slurm-web can be separated from Slurm services, collocated with `slurmrestd`
only, or the Slurm-web components themselves (*agent* and *gateway*) can run on
separate hosts.

.Slurm-web deployment on a single cluster with separate server [xref:image$arch/slurm-web_deployment_mono-cluster_separated.svg[icon:download[] SVG]]
image::arch/slurm-web_deployment_mono-cluster_separated.png[]

CAUTION: When slurmrestd is not collocated with Slurm-web, `slurmrestd` must be
configured to listen on a TCP/IP socket (_ie._ not on Unix socket). Please refer
to xref:conf:slurmrestd.adoc[slurmrestd access configuration page] for more
details.

=== Multiple clusters

Each cluster has its own _agent_ collocated with its `slurmrestd` service. The
central _gateway_ routes user traffic to the appropriate agent:

.Slurm-web deployment on multiple clusters [xref:image$arch/slurm-web_deployment_multi-clusters.svg[icon:download[] SVG]]
image::arch/slurm-web_deployment_multi-clusters.png[]

On each cluster, deploy one _agent_ component. On the central Slurm-web host,
deploy the _gateway_ component.

[NOTE]
====
* The gateway must be configured with all agents’ URLs and serves the single
  frontend for all clusters. Please refer to
  xref:conf:conf/gateway.adoc[gateway configuration page] for more details.
* As in single cluster deployment topology, the _agent_ component and Slurm
  services can be collocated on the same host or separated.
====

[#slurm-versions]
== Slurm REST API versions

Slurm-web {version} is officially tested and supported with Slurm REST API
versions from *v{api_version}* to *v{api_version_latest}*. These versions of
Slurm REST API are available in Slurm major versions 24.05, 24.11, 25.05, 25.11
and 26.05.

This table represents all Slurm REST API versions supported by the latest Slurm
releases:

.REST API versions by Slurm releases
[cols="2,1,1,1,1"]
|===
.2+|*Slurm releases*
4+^|*Supported API versions*

|*Latest*
2+^|*Compatible*
|*Deprecated*

|26.05
|*0.0.45*
|*0.0.44*
|*0.0.43*
|*0.0.42*

|25.11
|*0.0.44*
|*0.0.43*
|*0.0.42*
|*0.0.41*

|25.05
|*0.0.43*
|*0.0.42*
|*0.0.41*
|0.0.40

|24.11
|*0.0.42*
2+|*0.0.41*
|0.0.40

|24.05
|*0.0.41*
2+|0.0.40
|0.0.39

|23.11
|0.0.40
2+|0.0.39
|0.0.38

|===
