Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

rabbit: add docs on preset #DW strings #291

Merged
merged 1 commit into from
Dec 5, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 50 additions & 3 deletions tutorials/lab/rabbit.rst
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,53 @@ creating jobspecs directly.)
On the command line, set the ``.attributes.system.dw`` field by passing flags
like ``-S dw="my_string"`` or ``--setattr=dw="my_string"``.

The simplest way to use rabbits is to use preset DW strings that
administrators may have configured on a system. For more flexibility,
it may be desirable to write custom DW strings.


Preset DW Directives
--------------------

Running

.. code-block:: bash

flux config get rabbit.presets | jq .

will display a mapping of the presets that have been configured on the
current system. The keys of the mapping are the strings that you can
pass to ``-S dw=...``, the values of the mapping are the actual DW directives
the strings correspond to.


Preset Example
~~~~~~~~~~~~~~

Suppose ``flux config get rabbit.presets | jq .`` returns the following:

.. code-block:: json

{
"xfs_small": "#DW jobdw type=xfs capacity=256GiB name=xfssmall",
"xfs_large": "#DW jobdw type=xfs capacity=1TiB name=xfslarge",
"lustre_large": "#DW jobdw type=lustre capacity=10TiB name=lustrelarge",
}

Then you should be able to add the flag ``-S dw=lustre_large`` to
``flux run/batch/alloc/submit`` and have 10 Terabytes of lustre storage
accessible to your job at a path given by the ``$DW_JOB_lustrelarge``
environment variable. Similarly, ``-S dw=xfs_small`` and ``-S dw=xfs_large``
would give your job 256 gigabytes and 1 terabyte of XFS storage at
``$DW_JOB_xfssmall`` and ``$DW_JOB_xfslarge``, respectively.


Custom DW Directives
--------------------

Writing custom DW directives instead of using preset strings allows for much
greater flexibility.

DW directives are strings that start with ``#DW``. Directives
that begin with ``#DW jobdw`` are for requesting storage that
lasts the lifetime of the associated flux job. Directives that
Expand All @@ -30,8 +77,8 @@ Full documentation of the DW directives and their arguments is available
The usage with Flux is most easily understood by example.


Examples of jobdw directives
----------------------------
Examples of custom jobdw directives
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Requesting a 10 gigabyte XFS file system per compute node on the
command line:
Expand Down Expand Up @@ -59,7 +106,7 @@ Requesting both XFS and lustre file systems in a batch script:


Data Movement Examples
----------------------
~~~~~~~~~~~~~~~~~~~~~~

.. warning::

Expand Down
Loading