Admin Primitives

Admin primitives are used to give explicitly specified users access to ICE ClusterWare ™ functionality. Regular HPC users do not need to have Admin primitives created for them - this is solely for those who will do administrative or managerial tasks on the cluster.

To create an Admin, the only required data is a name. This must match the username of the user on the underlying operating system. If additional user-data is required, like a full name or department affiliation, it should be stored inside the "description" field.

When issuing requests, the UID field in the URL can be either the actual UID of the primitive or the name of the primitive as given in the "name" field. Thus, once a user, user1, has been created, it can be referenced through /admin/user1 or /admin/<UID>.

Data Fields

Admin primitives have several fields:

name
      Required: The name of the user on the underlying system

description
      Optional: A text string with descriptive information

roles
      Optional: A comma-separated list of ClusterWare roles; while optional, if a user
                does not have any roles assigned, they will not be able to take any
                actions; note that PATCH operations on the “roles” field will
                overwrite the entire field, there is no way to append or extend the
                list of roles

keys
      Optional: A list of one or more ssh keys

gui_settings
      Optional: Used internally by the ClusterWare GUI; it should not be modified
                by end-users

Additional Endpoints

Several endpoints can be used to modify the gui_settings field. Where the standard PATCH actions can update just the gui_settings field, it must update the entire primitive; these actions allow finer-grained updating of individual keys in that primitive. Note that this field is used internally by the ClusterWare GUI and admins should not need to modify it directly.

GET /admin/<UID>/gui_settings

PATCH /admin/<UID>/gui_settings

DELETE /admin/<UID>/gui_settings

Several endpoints can be used to update or delete the list of SSH keys that have been stored for the admin.

POST /admin/<UID>/keys

PUT /admin/<UID>/keys

DELETE /admin/<UID>/keys

Similar to the token-refresh process, there is an endpoint that allows an admin to make a new token for use by other tools or automated processes; optional fields can be included in the request:

POST /admin/<UID>/newtoken lifespan:  integer; duration for the newly made token

Note

Starting with the 13.0 release, the duration name changed from timeout to lifespan. Support for the legacy name will be removed in a future release.

Example

First, create a new admin:

curl -X POST https://head1.cluster.local/api/v1/admins --data '{"name":"admin2"}' \
    -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": "d763705495c3423083ae35f0850da018"}

Get the details on that Admin record:

curl -X GET https://head1.cluster.local/api/v1/admin/d763705495c3423083ae35f0850da018 \
    -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": {"name": "admin2", "roles": ["role.authuser", \
    "role.fulladmin"], "last_modified": 1721850600.3619504, "last_modified_on": \
    "head23.cluster.local", "last_modified_by": "admin1", "uid": \
    "d763705495c3423083ae35f0850da018"}}

Update the record to include a description (switching to “admin2” in the URL):

curl -X PATCH https://head1.cluster.local/api/v1/admin/admin2 --data \
    '{"description":"John Doe, HPC admin"}' -H "Authorization: Bearer \
    eyJhbGciOiJIUzI1Ni…"
{"success": true}

Update the list of roles to be just “role.authuser”:

curl -X PATCH https://head1.cluster.local/api/v1/admin/admin2 --data \
    '{"roles":["role.authuser"]}' -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true}

While the PATCH request only updates that one field, leaving other fields as-is, the update to that field will overwrite the old data. There is no way to append or add to the list of roles.

Verify the new data:

curl -X GET https://head1.cluster.local/api/v1/admin/admin2 -H \
    "Authorization: Bearer eyJhbGciOiJIUzI1Ni…”
{"success": true, "data": {"name": "admin2", "roles": ["role.authuser"], \
    "last_modified": 1721851033.3245502, "last_modified_on": "head23.cluster.local", \
    "last_modified_by": "admin1", "description": "John Doe, HPC admin", "uid": \
    "d763705495c3423083ae35f0850da018"}}

Finally, delete the account:

curl -X DELETE https://head1.cluster.local/api/v1/admin/admin2 -H \
    "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true}