Laurence Horrocks-Barlow
8840ba74f7
Adds a Python package that wraps the Storage Scale /scalemgmt/v3 management API behind a Claude-driven tool-use loop. Ships a Rich-styled terminal REPL and a Streamlit web UI sharing the same Agent/Dispatcher/GPFSClient stack. Guardrails are env-driven (.env): read-only by default; writes and DELETE gated by GPFS_ALLOW_WRITES / GPFS_ALLOW_DESTRUCTIVE; optional path allow/deny regex; mutating calls require operator confirmation. Free-text GPFS_INSTRUCTIONS (or GPFS_INSTRUCTIONS_FILE) appended to the system prompt. The system prompt also includes a curated v3 endpoint reference compiled from IBM Storage Scale 5.2.3 / 6.0.0 documentation so the agent doesn't have to guess endpoint shapes for common operations. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
98 lines
5.1 KiB
Python
98 lines
5.1 KiB
Python
V3_REFERENCE = """\
|
|
# IBM Storage Scale (GPFS) management REST API — v3 reference
|
|
|
|
Compiled from IBM Storage Scale documentation 5.2.3 / 6.0.0. The native REST
|
|
API is served by the Storage Scale GUI node.
|
|
|
|
## Connection facts
|
|
- Base path: `/scalemgmt/v3`
|
|
- Default GUI port: 443 (containerised CNSA) or 46443 (native install)
|
|
- Protocol: HTTPS only
|
|
- Auth: HTTP Basic, against a Storage Scale GUI user with an admin role
|
|
- OpenAPI: live spec is at `/openapi/` on the GUI node (interactive Swagger UI)
|
|
- v3 is the current native REST API; v2 is still served on most clusters for
|
|
backwards compatibility but new endpoints are only added under v3
|
|
|
|
## Common endpoints (non-exhaustive)
|
|
|
|
### Cluster & nodes
|
|
- `GET /clusters` List local cluster info (use `?view=BASIC` for a compact summary)
|
|
- `GET /cluster` Cluster configuration (legacy alias)
|
|
- `POST /clusters/remote` Register an owning cluster as a remote
|
|
- `GET /nodes` List all nodes
|
|
- `GET /nodes/{name}` Node details
|
|
- `DELETE /nodes/{name}` Remove a node (destructive)
|
|
- `GET /nodeclasses` List node classes
|
|
|
|
### NSDs & pools
|
|
- `GET /nsds` List all network-shared disks
|
|
- `GET /nsds/{nsd}` NSD details
|
|
- `GET /filesystems/{fs}/storagepools` Storage pools for a filesystem
|
|
|
|
### Filesystems
|
|
- `GET /filesystems` List all filesystems
|
|
- `POST /filesystems` Create a filesystem
|
|
- `GET /filesystems/{fs}` Filesystem detail (`?fields=mount` for mount state)
|
|
- `DELETE /filesystems/{fs}` Delete a filesystem (destructive)
|
|
- `PUT /filesystems/{fs}` Modify a filesystem
|
|
|
|
### Filesets
|
|
- `GET /filesystems/{fs}/filesets` List filesets
|
|
- `POST /filesystems/{fs}/filesets` Create a fileset
|
|
- `GET /filesystems/{fs}/filesets/{fileset}` Fileset detail
|
|
- `PUT /filesystems/{fs}/filesets/{fileset}` Modify a fileset
|
|
- `DELETE /filesystems/{fs}/filesets/{fileset}` Delete (destructive)
|
|
- `POST /filesystems/{fs}/filesets/{fileset}:link` Link a fileset to a path
|
|
- `POST /filesystems/{fs}/filesets/{fileset}:unlink` Unlink a fileset
|
|
|
|
### Snapshots
|
|
- `GET /filesystems/{fs}/snapshots` List global snapshots
|
|
- `POST /filesystems/{fs}/snapshots` Create a global snapshot
|
|
- `DELETE /filesystems/{fs}/snapshots/{snap}` Delete a global snapshot
|
|
- `GET /filesystems/{fs}/filesets/{fileset}/snapshots` List fileset snapshots
|
|
- `POST /filesystems/{fs}/filesets/{fileset}/snapshots` Create a fileset snapshot
|
|
- `DELETE /filesystems/{fs}/filesets/{fileset}/snapshots/{snap}` Delete a fileset snapshot
|
|
- `POST /filesystems/{fs}/filesets/snapshots:batchDelete` Batch-delete fileset snapshots
|
|
|
|
### Quotas
|
|
- `GET /filesystems/{fs}/quotas` List quotas on a filesystem
|
|
- `PUT /filesystems/{fs}/quotas` Set/modify quotas
|
|
- `GET /filesystems/{fs}/quotamanagement` Quota management state
|
|
- `GET /filesystems/{fs}/quotadefaults` Default quotas
|
|
|
|
### Policies & rules
|
|
- `GET /filesystems/{fs}/policies` Active policy
|
|
- `PUT /filesystems/{fs}/policies` Install / replace policy
|
|
- `GET /filesystems/{fs}/policyrules` Inspect rules
|
|
|
|
### Jobs (async operations)
|
|
- `GET /jobs` List jobs
|
|
- `GET /jobs/{jobId}` Poll a job (mutating endpoints return a jobId)
|
|
|
|
### Performance monitoring
|
|
- `GET /perfmon/data` Query perfmon sensors
|
|
- `GET /perfmon/sensors` List configured sensors
|
|
|
|
### Auth / config
|
|
- `GET /info` Product info / API version
|
|
- `GET /config` GUI/cluster config
|
|
|
|
## Conventions
|
|
- Async-by-default: most `POST/PUT/DELETE` calls return `202 Accepted` with a
|
|
`jobs[0].jobId`. Poll `/jobs/{jobId}` until the status is `COMPLETED` or
|
|
`FAILED`. Don't assume a mutation has taken effect until the job is done.
|
|
- Many GETs accept `?fields=<csv>` to narrow the response payload.
|
|
- Collection endpoints generally accept `?filter=<expr>` for server-side
|
|
filtering — when in doubt, fetch the collection and filter client-side.
|
|
- A colon segment like `:link` / `:unlink` / `:batchDelete` denotes a custom
|
|
verb on a sub-resource; treat the whole thing as one path segment.
|
|
|
|
## Behaviour rules for the agent
|
|
- Use the OpenAPI spec at `/openapi/` (HTML) or `/openapi.json` if the user
|
|
reports an endpoint that isn't listed here — it's the source of truth for
|
|
the specific cluster version.
|
|
- If a v3 endpoint 404s, retry once at the v2 equivalent before declaring
|
|
failure (some sites haven't upgraded the GUI yet).
|
|
- For any mutating call: state the plan in one sentence, wait for the harness
|
|
confirmation, then poll the returned jobId.
|
|
"""
|