feat(discovery): simplify agent registration and publication by jtolentino1 · Pull Request #1586 · cryostatio/cryostat

jtolentino1 · 2026-06-09T20:41:12Z

Welcome to Cryostat! 👋

Before contributing, make sure you have:

Read the contributing guidelines
Linked a relevant issue which this PR resolves
Linked any other relevant issues, PR's, or documentation, if any
Resolved all conflicts, if any
Rebased your branch PR on top of the latest upstream main branch
Attached at least one of the following labels to the PR: [chore, ci, docs, feat, fix, test]
Signed all commits using a GPG signature

To recreate commits with GPG signature git fetch upstream && git rebase --force --gpg-sign upstream/main

Fixes: #1494
Companion PRs: cryostatio/cryostat-agent#909, cryostatio/cryostat-operator#1349

Description of the change:

This change adds a new Agent-specific endpoint POST /api/v4.3/discovery/agents that combines Discovery Plugin registration, Stored Credential creation/association, and discovery node publication into a single request handled in one transaction. The response is the same PluginRegistration shape (id, token, env) as the existing registration endpoint.

Re-registering an existing Agent (same realm and callback, ex. after its JWT expires) reuses the plugin record, replaces its Stored Credential (the old one is cascade-deleted), reissues the JWT, and republishes its nodes.
Publication now removes a plugin's previously published nodes before inserting the replacements, so republication is idempotent instead of colliding with the plugin's own earlier Target records on the connectUrl unique constraint. This applies to both the new endpoint and the existing POST /api/v4.2/discovery/{id} publication path, which shares the same implementation.
The existing Discovery Plugin registration/publication flow is unchanged and remains in place for other plugin implementations; the shared logic is extracted into common helpers.
DiscoveryPlugin now supports a directly-associated credential at persist time, so Agent callbacks no longer need to embed storedcredentials:<id> userinfo for Cryostat to authenticate its pings.
Added DiscoveryPluginTest coverage for the new endpoint: registration with credential storage and publication, deregistration cleanup, and idempotent re-registration with credential replacement.

Motivation for the change:

See #1494. The Cryostat Agent is the only known external Discovery Plugin implementation, and its registration currently requires a sequence of separate requests (credential query/creation, plugin registration, publication) with corresponding state tracking on the Agent side. Combining these into one Agent-specific request reduces the number of API calls and database transactions, lets the Agent's internal state shrink to just its webserver credentials and plugin ID/token, and removes the need for the Agent to track and clean up Stored Credentials. The Agent-side counterpart is cryostatio/cryostat-agent#909, and cryostatio/cryostat-operator#1349 tightens the operator's Agent proxy accordingly.

How to manually test:

Start the application

./smoketest.bash -O

Register an "Agent" with a single request (the callback points at Cryostat's own health endpoint so the registration-time reachability ping succeeds), and note the returned id and token:

curl -k -u user:pass \
  -X POST https://localhost:8443/api/v4.3/discovery/agents \
  -H 'Content-Type: application/json' \
  -d '{
    "realm": "manual-test",
    "callback": "http://localhost:8181/health/liveness",
    "credential": {"matchExpression": "true", "username": "agent-user", "password": "agent-pass"},
    "nodes": [{"name": "agent-node", "nodeType": "CryostatAgent", "target": {"connectUrl": "https://agent-test.local:9977", "alias": "agent-node"}}],
    "fillStrategy": "NONE",
    "context": {}
  }'

Verify the registration did all three steps: the plugin's realm contains the published node, the target appears, and the Stored Credential exists:

curl -k -u user:pass https://localhost:8443/api/v4/discovery_plugins/<id>
curl -k -u user:pass https://localhost:8443/api/v4/targets
curl -k -u user:pass https://localhost:8443/api/v4/credentials

Repeat the request from step 2 unchanged. Verify it returns the same plugin id with a new token, the realm still contains exactly one agent-node (no duplicates), and the credential from step 3 has been replaced by a new one (old ID gone from /api/v4/credentials).
Deregister and verify cleanup (credential and target are removed along with the plugin):

curl -k -u user:pass \
  -X DELETE https://localhost:8443/api/v4/discovery/<id> \
  -H 'Cryostat-Discovery-Authentication: <token>'
curl -k -u user:pass https://localhost:8443/api/v4/credentials
curl -k -u user:pass https://localhost:8443/api/v4/targets

For a full end-to-end test with a real Agent using the new flow, pair this branch with feat(registration): use simplified registration API cryostat-agent#909 (and chore(autoconfig): remove credential API paths from Agent proxy allowlist cryostat-operator#1349 on OpenShift): the Agent registers with a single POST /api/v4.3/discovery/agents, makes no /api/v4/credentials requests, re-registers cleanly after its token expires, and deregisters with credential cleanup on shutdown.

github-actions · 2026-06-09T20:41:22Z