diff --git a/doc/Makefile.am b/doc/Makefile.am index 79f8b2eb..68791b4e 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -39,7 +39,8 @@ MAN1_FILES_PRIMARY = \ man1/flux-account-show-usage.1 \ man1/flux-account-edit-all-users.1 \ man1/flux-account-export-json.1 \ - man1/flux-account-view-usage-report.1 + man1/flux-account-view-usage-report.1 \ + man1/flux-account-clear-usage.1 RST_FILES = \ $(MAN1_FILES_PRIMARY:.1=.rst) diff --git a/doc/components/job-usage-calculation.rst b/doc/components/job-usage-calculation.rst index 3f5d3317..76df1c6c 100644 --- a/doc/components/job-usage-calculation.rst +++ b/doc/components/job-usage-calculation.rst @@ -103,6 +103,21 @@ that make up their historical job usage value: moussa | 12345 | A | 100.0 | 243.5 | 8.7 | 0.0 +Resetting the usage for a bank +============================== + +The job usage value for a bank (and all of the users under that bank) can be +reset with the :man1:`flux-account-clear-usage` command. This will allow you to +quickly clear any amount of recently accrued usage, which, on a high-traffic +system, can ultimately bump up its users' fair-share values after the entire +hierarchy's job usage and fair-share values are updated. + +An optional timestamp can also be specified when running this command to tell +flux-accounting to *only* consider jobs newer than said timestamp with the +``--ignore-older-than`` optional argument. By default, the ``clear-usage`` +command will notify any future job usage updates to ignore jobs submitted under +that bank older than when the command was issued. + Calculating job usage arbitrarily ================================= diff --git a/doc/man1/flux-account-add-bank.rst b/doc/man1/flux-account-add-bank.rst index ba687707..e056a31e 100644 --- a/doc/man1/flux-account-add-bank.rst +++ b/doc/man1/flux-account-add-bank.rst @@ -28,6 +28,13 @@ configured when adding the bank. An associated priority to be applied to jobs submitted under this bank. +.. option:: --ignore-older-than + + A timestamp to which older jobs will be ignored when calculating job + usage; accepts multiple formats: seconds since epoch timestamp or human + readable timestamp (e.g. ``01/01/2025``, ``2025-01-01 08:00:00``, ``Jan 1, + 2025 8am``) + EXAMPLES -------- diff --git a/doc/man1/flux-account-clear-usage.rst b/doc/man1/flux-account-clear-usage.rst new file mode 100644 index 00000000..14a44a37 --- /dev/null +++ b/doc/man1/flux-account-clear-usage.rst @@ -0,0 +1,26 @@ +.. flux-help-section: flux account + +=========================== +flux-account-clear-usage(1) +=========================== + + +SYNOPSIS +======== + +**flux** **account** **clear-usage** [BANK BANK ...] [OPTIONS] + +DESCRIPTION +=========== + +.. program:: flux account clear-usage + +:program:`flux account clear-usage` will reset the usage for one or more banks +and all of the users under those banks back to 0. + +.. option:: --ignore-older-than + + A timestamp to which older jobs will be ignored when calculating job + usage; accepts multiple formats: seconds since epoch timestamp or human + readable timestamp (e.g. ``01/01/2025``, ``2025-01-01 08:00:00``, ``Jan 1, + 2025 8am``) diff --git a/doc/man1/flux-account-edit-bank.rst b/doc/man1/flux-account-edit-bank.rst index 7c91d0b0..c4e9091e 100644 --- a/doc/man1/flux-account-edit-bank.rst +++ b/doc/man1/flux-account-edit-bank.rst @@ -31,6 +31,13 @@ fields for a given bank. The list of modifiable fields are as follows: An associated priority to be applied to jobs submitted under this bank. +.. option:: --ignore-older-than + + A timestamp to which older jobs will be ignored when calculating job + usage; accepts multiple formats: seconds since epoch timestamp or human + readable timestamp (e.g. ``01/01/2025``, ``2025-01-01 08:00:00``, ``Jan 1, + 2025 8am``) + EXAMPLES -------- diff --git a/doc/manpages.py b/doc/manpages.py index 380bf56e..ea10b85b 100644 --- a/doc/manpages.py +++ b/doc/manpages.py @@ -251,4 +251,11 @@ [author], 1, ), + ( + "man1/flux-account-clear-usage", + "flux-account-clear-usage", + "reset the job usage for a bank back to 0", + [author], + 1, + ), ] diff --git a/t/t1026-flux-account-perms.t b/t/t1026-flux-account-perms.t index 66abf064..3efb0eb3 100755 --- a/t/t1026-flux-account-perms.t +++ b/t/t1026-flux-account-perms.t @@ -157,6 +157,17 @@ test_expect_success 'edit-factor should not be accessible by all users' ' ) ' +test_expect_success 'clear-usage should not be accessible by all users' ' + newid=$(($(id -u)+1)) && + ( export FLUX_HANDLE_ROLEMASK=0x2 && + export FLUX_HANDLE_USERID=$newid && + touch users.csv && + touch banks.csv && + test_must_fail flux account clear-usage my_bank > no_access_clear_usage.out 2>&1 && + grep "Request requires owner credentials" no_access_clear_usage.out + ) +' + test_expect_success 'remove flux-accounting DB' ' rm $(pwd)/FluxAccountingTest.db '