Skip to content

feat(cli): add report command for users per role - #4034

Open
schweigisito wants to merge 3 commits into
mainfrom
feat/report-command
Open

schweigisito wants to merge 3 commits into
mainfrom
feat/report-command

Conversation

@schweigisito

@schweigisito schweigisito commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Adds opencloud report, a CLI command that counts the users of a running instance and groups them by their assigned role.

Docs

opencloud-eu/docs#1390 documents this command under Admin > Maintenance.

That PR depends on this one and must not merge first, since it describes a command that is in no release yet. Merging this one first, or both together, is fine. Its availability note needs the release that ships this command.

What it does

By default the report is a plain user count per role:

Users in total: 10026

┌────────────────────┬───────┐
│        Role        │ Users │
├────────────────────┼───────┤
│ (no role assigned) │  9919 │
│ User               │   103 │
│ Admin              │     2 │
│ Space Admin        │     1 │
│ User Light         │     1 │
└────────────────────┴───────┘
  • Reads the libregraph API as the configured service account. It only reads, but the instance has to be running, and the command has to run next to it.
  • -o/--output takes table (default), json, csv and yaml.
  • --with-sign-in additionally reports, per role, how many of its users signed in within the last --days days (31 by default).
  • -t/--timeout caps the whole run, 5 minutes by default, since the graph API resolves role assignments per user.
  • --insecure skips the TLS certificate check, for deployments serving the generated self-signed certificate. TLS 1.2 is the minimum for every connection either way.

Sign-ins are opt-in

The second commit flips what was originally the default. The report used to include the sign-in window and needed --skip-sign-in to leave it out, which only worked on a deployment that records sign-ins. Everywhere else it produced a column of N/A and a warning.

Now the sign-in fields are absent from every output format unless --with-sign-in is given, rather than reported as null or N/A, because nothing was read. --days on its own is rejected.

OpenCloud stores the last sign-in as an attribute on the user entry in LDAP, so --with-sign-in needs an LDAP identity backend that OpenCloud may write to. It is refused otherwise, with the reason:

--with-sign-in is not available on this instance: the LDAP identity backend is read-only,
see OC_LDAP_SERVER_WRITE_ENABLED, so no sign-in is ever recorded

The cs3 backend never records sign-ins and is refused the same way. Where the backend does accept the write but no user has a recorded sign-in yet, the counts stay N/A rather than 0, so an unwritten directory is not mistaken for an idle instance.

Works without a service registry

The third commit fixes a gap found while testing against a Helm deployment. The command looked the gateway and the graph service up in the micro registry only. The chart runs the services with MICRO_REGISTRY=memory and discovers them through Kubernetes instead, so a separate process found an empty registry and the command failed with eu.opencloud.api.gateway: service not found, even though both services were listening in the same pod.

Both lookups now fall back to the configured address when the registry holds no entry: the gateway over dns:/// at the address from the gateway config, with a wildcard bind rewritten to loopback, and the graph service at the address from the graph config. The configured reva address is still tried first, so a deployment with a populated registry is unaffected.

Verified in the opencloud-api pod of a k3s deployment with MICRO_REGISTRY=memory, with no environment overrides, and re-verified unchanged against Docker Compose.

Changes after review

Thanks for the review, all five points are in:

  • TLS. You were right, and it broke outright. The graph endpoint now honours the use_tls metadata, resolved by a nodeProtocol helper the same way the proxy router does it. Verified on an instance with OC_HTTP_TLS_ENABLED=true and a generated certificate: before the fix it failed with could not list applications: undefined response type, after it reaches https:// and fails honestly with x509: certificate signed by unknown authority, and with --insecure it works.
  • Timeout. Added -t/--timeout, default raised from 1 to 5 minutes. Non-positive values are rejected.
  • No-role bucket. Both points went into the docs PR, including that a failed role lookup leaves a user in the same bucket undetectably.
  • CSV rows. slices.Concat instead of append(prefix, ...), in both paths.
  • Test helper. count renamed to countPtr.

Following a Codacy finding and a hint about TLS versions, the graph client is built in one place and requires TLS 1.2 or newer on every connection, not only with --insecure. It clones http.DefaultTransport rather than replacing it, so proxy support, HTTP/2 and connection pooling survive.

Testing

15 test functions. Besides the grouping, window, renderers and the unavailable case, they pin the TLS resolution, the TLS floor and transport clone, which flags may be refused, both registry fallbacks, and every flag's shorthand and default so a later flag cannot quietly take -t.

Run against live deployments covering: Keycloak with read-only LDAP on Docker Compose (10026 users), the built-in IDM with real OIDC logins and a backdated timestamp to check the window, an instance with OC_HTTP_TLS_ENABLED=true, and a k3s Helm deployment for the registry fallback and the read-only refusal.

AI assistance: Claude Code (claude-opus-5) wrote the code, the tests and this description, and ran the live tests.

@codacy-production

codacy-production Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 214 complexity

Metric Results
Complexity 214

View in Codacy

🟢 Coverage 57.84% diff coverage · +0.14% coverage variation

Metric Results
Coverage variation ✅ +0.14% coverage variation (-1.00%)
Diff coverage ✅ 57.84% diff coverage

View coverage diff in Codacy

Coverage variation details
Coverable lines Covered lines Coverage
Common ancestor commit (2032e85) 94240 28200 29.92%
Head commit (3275bd5) 94712 (+472) 28473 (+273) 30.06% (+0.14%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details
Coverable lines Covered lines Diff coverage
Pull request (#4034) 472 273 57.84%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.

@pbleser-oc pbleser-oc left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this reads well, and keeping "no sign-in data" (N/A) apart from "nobody signed in" (0) is a nice touch. It builds, vet is clean and the tests pass locally with -race.

One thing I'd like to see fixed before merging: the graph URL ignores internal TLS (inline comment). The other comments are questions or small suggestions, none of them blocking.

Comment thread opencloud/pkg/command/report.go Resolved
Comment thread opencloud/pkg/command/report.go Resolved
Comment thread opencloud/pkg/command/report.go Resolved
Comment thread opencloud/pkg/command/report.go Resolved
Comment thread opencloud/pkg/command/report_test.go Resolved
Add `opencloud report`, listing the users of a running instance grouped
by their assigned role, with the number that signed in within the last
--days days (31 by default) per role. Reads the libregraph API as the
configured service account. Output is a table by default, -o/--output
also takes json, csv and yaml.

Sign-in counts are reported as N/A when the instance records no sign-in
timestamps at all, e.g. with a read-only identity backend.

--skip-sign-in leaves the sign-in window out and reports only the users
per role. The sign-in fields are then dropped from the output rather
than reported as null or N/A, because nothing was read. Combining it
with --days is rejected, because the window has no effect then.

The graph endpoint honours the use_tls metadata of the service registry.
The registry reports "http" for every HTTP service and signals TLS
separately, so without this the report sent plain HTTP to a TLS listener
on a deployment with OC_HTTP_TLS_ENABLED=true. --insecure skips the
certificate check for deployments serving the generated self-signed
certificate.

-t/--timeout caps the whole run and defaults to 5 minutes. The graph API
resolves the role assignments per user, so the run grows with the number
of users and a large instance needs to raise it.

Assisted-by: Claude Code:claude-opus-5

@pbleser-oc pbleser-oc left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for addressing all of it. The TLS handling now follows use_tls the same way the proxy does, and cloning the default transport for --insecure keeps the rest of the client behaviour intact. The tests for nodeProtocol and the flags are a good addition, and opencloud-eu/docs#1390 covers the role bucket, the timeout and --insecure.

It builds, vet and golangci-lint are clean, and the tests pass locally with -race. Looks good to me.

Comment thread opencloud/pkg/command/report.go Outdated
// clone the default transport so that only the certificate check
// changes, and proxy support, HTTP/2 and connection pooling stay
transport := http.DefaultTransport.(*http.Transport).Clone()
transport.TLSClientConfig = &tls.Config{InsecureSkipVerify: true} //nolint:gosec // opt-in via --insecure

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not blocking: Codacy flags the missing MinVersion here. Go defaults to TLS 1.2 anyway, but most of the code base sets it explicitly (e.g. benchmark.go, which has the same --insecure option), so adding MinVersion: tls.VersionTLS12 would match that and quiet the check. The other Codacy finding, the skipped verification, is intended with --insecure.

The default behaviour has flipped. `opencloud report` used to include
the sign-in window and needed --skip-sign-in to leave it out. It now
counts the users per role and nothing else, and --with-sign-in asks for
the sign-in window on top. --skip-sign-in is gone, replaced by its
opposite.

The old default only worked on a deployment that records sign-ins.
Everywhere else it filled a column with N/A and printed a warning, which
is noise for anyone who just wants to know how many users hold which
role.

Without --with-sign-in the sign-in fields are left out of every output
format entirely, rather than reported as null or N/A, because nothing
was read. --days on its own is rejected, because the window has no
effect without the flag.

OpenCloud stores the last sign-in as an attribute on the user entry in
LDAP, so --with-sign-in needs an LDAP identity backend that OpenCloud
may write to. On a read-only LDAP backend, or on the cs3 backend which
never records sign-ins at all, the flag is refused with the reason
instead of reporting counts that could never be filled. Where the
backend does accept the write but no user has a recorded sign-in yet,
the counts stay N/A rather than 0.

The graph client now requires TLS 1.2 or newer for every connection,
not only for the ones made with --insecure.

Assisted-by: Claude Code:claude-opus-5
@pbleser-oc

Copy link
Copy Markdown
Member

Thanks, I had a look at the new commit as well. Making the sign-in window opt-in reads much better, and refusing --with-sign-in on the cs3 backend and on a read-only LDAP matches what the graph service does, since it skips recording the sign-in in exactly those two cases. The TLS floor and the test that the cloned transport keeps proxy support and HTTP/2 are a nice touch, too.

The failing test-API-sharingNg-posix doesn't touch the CLI, so it looks unrelated. From my side you're welcome to merge it into main.

The report looked the gateway and the graph service up in the micro
service registry only. A deployment that runs the services with
MICRO_REGISTRY=memory and discovers them through Kubernetes instead,
which is what the Helm chart does with an external NATS endpoint, leaves
a separate process with an empty registry. `opencloud report` then failed
with "eu.opencloud.api.gateway: service not found" even though both
services were listening in the very same pod.

Both lookups now fall back to the configured address when the registry
holds no entry for them. The gateway is dialled over dns:/// at the
address from the gateway config, with a wildcard bind rewritten to
loopback since the report runs next to the gateway it talks to, and the
graph service at the address from the graph config. The configured reva
address is still tried first, so nothing changes on a deployment where
the registry is populated.

Parsing the gateway config in PreRunE is new. It carries the fallback
address and was not needed before.

Verified on a k3s deployment with MICRO_REGISTRY=memory: the report runs
in the opencloud-api pod with no environment overrides at all, and
--with-sign-in is correctly refused there because that deployment sets
OC_LDAP_SERVER_WRITE_ENABLED=false. A Docker Compose deployment, where
the registry is populated, returns the same result as before.

Assisted-by: Claude Code:claude-opus-5
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants