Skip to content

Commit 4a87f37

Browse files
scotwellsscotwells
committed
feat: add activity cli
Registers the new activity CLI so users can query the platform for activity logs. Also adds documentation for the activity logs to provide guidance on how to use the CLI.
1 parent 05c9a8d commit 4a87f37

File tree

5 files changed

+199
-131
lines changed

5 files changed

+199
-131
lines changed

‎docs/user/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,8 @@ This guide provides information for users on how to install and use the
1111
**Resource Commands:**
1212

1313
* [Organizations](./resources/organizations.md)
14+
15+
**Commands**
16+
17+
- **[Activity](./commands/activity.md)** - interact with the activity system to
18+
retrieve audit logs for events happening within your infrastructure

‎docs/user/commands/activity.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Activity
2+
3+
The `datumctl activity` command is available for interacting with the [activity
4+
service] we've made available to Datum Cloud consumers. The activity service
5+
allows users to query for audit logs that are collected for all interactions
6+
with the platform.
7+
8+
You can see the full list of commands and CLI options by using the `--help`
9+
flag.
10+
11+
```shell
12+
$ datumctl activity --help
13+
```
14+
15+
This document will guide you through how to query the system using some of the
16+
most frequently used commands.
17+
18+
[activity service]: https://github.com/datum-cloud/activity
19+
[milo]: https://github.com/datum-cloud/milo
20+
21+
## Querying audit logs
22+
23+
The `datumctl activity query` command is available to query the system for audit
24+
logs to understand what's happening within your organization and projects.
25+
26+
### Project and organization audit logs
27+
28+
Use the `--project` and `--organization` flag to control which context audit
29+
logs are retrieved from.
30+
31+
```shell
32+
$ datumctl activity query --project datum-cloud
33+
TIMESTAMP VERB USER NAMESPACE RESOURCE NAME STATUS
34+
2026-01-14 09:52:43 create [email protected] auditlogqueries 201
35+
2026-01-14 09:44:09 get [email protected] dnszones 201
36+
2026-01-14 09:44:29 update [email protected] dnszones datum.net 201
37+
2026-01-14 09:50:22 delete [email protected] dnszones datum.net 201
38+
```
39+
40+
### Filtering
41+
42+
The `--filter` command is available to filter the audit logs returned in the
43+
query. The filter option accepts a [CEL expression][cel] to select which audit
44+
logs should be returned.
45+
46+
```shell
47+
$ datumctl activity query --project datum-cloud --limit 10 --filter='user.username == "[email protected]" && objectRef.apiGroup == "networking.datumapis.com"'
48+
TIMESTAMP VERB USER NAMESPACE RESOURCE NAME STATUS
49+
2026-01-14 10:08:33 get [email protected] default domains datum.net 200
50+
2026-01-14 10:08:40 get [email protected] default domains datum.net 200
51+
2026-01-14 10:08:27 get [email protected] default domains datum.net 200
52+
2026-01-14 10:08:40 get [email protected] default domains datum.net 200
53+
54+
No more results.
55+
```
56+
57+
[cel]: https://cel.dev
58+
59+
### Pagination
60+
61+
The `--continue` option is available to paginate requests when additional
62+
results are available. The CLI will provide the continue option to use for the
63+
next page of requests.
64+
65+
```shell
66+
$ datumctl activity query --project datum-cloud --limit 10 --filter='user.username == "[email protected]" && objectRef.apiGroup == "networking.datumapis.com"' --limit 3
67+
TIMESTAMP VERB USER NAMESPACE RESOURCE NAME STATUS
68+
2026-01-14 10:08:33 get [email protected] default domains datum.net 200
69+
2026-01-14 10:08:40 get [email protected] default domains datum.net 200
70+
2026-01-14 10:19:48 get [email protected] default domains datum.net 200
71+
72+
More results available. Use --continue-after '{continue-token}' to get the next page.
73+
Or use --all-pages to fetch all results automatically.
74+
```
75+
76+
You can also use the `--all-pages` option to retrieve all pages.
77+
78+
### Output
79+
80+
The `--output` or `-o` option is available to control the format that's
81+
returned. By default the query command will output a table with common fields
82+
that are helpful to users to understand the activity. You can also output the
83+
results as `yaml` or `json` to see the full audit logs that were retrieved by
84+
the query.
85+
86+
```shell
87+
$ datumctl activity query --project datum-cloud -o yaml
88+
apiVersion: audit.k8s.io/v1
89+
items:
90+
- annotations:
91+
authorization.k8s.io/decision: allow
92+
authorization.k8s.io/reason: ""
93+
platform.miloapis.com/scope.name: datum-cloud
94+
platform.miloapis.com/scope.type: project
95+
auditID: 5b842c5a-001f-45c3-97af-d76a4114e9ee
96+
level: Request
97+
objectRef:
98+
apiGroup: networking.datumapis.com
99+
apiVersion: v1alpha
100+
name: datum.net
101+
namespace: default
102+
resource: domains
103+
requestReceivedTimestamp: "2026-01-14T16:08:33.274159Z"
104+
requestURI: /apis/networking.datumapis.com/v1alpha/namespaces/default/domains/datum.net
105+
responseStatus:
106+
code: 200
107+
metadata: {}
108+
stage: ResponseComplete
109+
stageTimestamp: "2026-01-14T16:08:33.278787Z"
110+
user:
111+
extra:
112+
iam.miloapis.com/parent-api-group:
113+
- resourcemanager.miloapis.com
114+
iam.miloapis.com/parent-name:
115+
- datum-cloud
116+
iam.miloapis.com/parent-type:
117+
- Project
118+
iam.miloapis.com/registrationApproval:
119+
- Approved
120+
groups:
121+
- system:authenticated
122+
uid: "328747448287632651"
123+
username: [email protected]
124+
userAgent: axios/1.13.2
125+
verb: get
126+
...
127+
kind: EventList
128+
metadata: {}
129+
```

‎go.mod‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ require (
1111
github.com/spf13/cobra v1.10.2
1212
github.com/spf13/pflag v1.0.10
1313
github.com/zalando/go-keyring v0.2.6
14+
go.miloapis.com/activity v0.0.0-20260113191412-5f92a716b929
1415
go.miloapis.com/milo v0.16.1
1516
golang.org/x/oauth2 v0.34.0
1617
k8s.io/apiextensions-apiserver v0.35.0
@@ -42,11 +43,11 @@ require (
4243
github.com/go-errors/errors v1.4.2 // indirect
4344
github.com/go-jose/go-jose/v4 v4.1.3 // indirect
4445
github.com/go-logr/logr v1.4.3 // indirect
45-
github.com/go-openapi/jsonpointer v0.21.0 // indirect
46-
github.com/go-openapi/jsonreference v0.21.0 // indirect
46+
github.com/go-openapi/jsonpointer v0.22.1 // indirect
47+
github.com/go-openapi/jsonreference v0.21.3 // indirect
4748
github.com/go-openapi/swag v0.23.0 // indirect
49+
github.com/go-openapi/swag/jsonname v0.25.1 // indirect
4850
github.com/godbus/dbus/v5 v5.1.0 // indirect
49-
github.com/gogo/protobuf v1.3.2 // indirect
5051
github.com/google/btree v1.1.3 // indirect
5152
github.com/google/gnostic-models v0.7.0 // indirect
5253
github.com/google/go-cmp v0.7.0 // indirect
@@ -70,7 +71,6 @@ require (
7071
github.com/mxk/go-flowrate v0.0.0-20140419014527-cca7078d478f // indirect
7172
github.com/opencontainers/go-digest v1.0.0 // indirect
7273
github.com/peterbourgon/diskv v2.0.1+incompatible // indirect
73-
github.com/pkg/errors v0.9.1 // indirect
7474
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
7575
github.com/prometheus/client_golang v1.23.2 // indirect
7676
github.com/prometheus/client_model v0.6.2 // indirect
@@ -79,25 +79,25 @@ require (
7979
github.com/russross/blackfriday/v2 v2.1.0 // indirect
8080
github.com/x448/float16 v0.8.4 // indirect
8181
github.com/xlab/treeprint v1.2.0 // indirect
82-
go.opentelemetry.io/otel v1.36.0 // indirect
83-
go.opentelemetry.io/otel/trace v1.36.0 // indirect
82+
go.opentelemetry.io/otel v1.39.0 // indirect
83+
go.opentelemetry.io/otel/trace v1.39.0 // indirect
8484
go.yaml.in/yaml/v2 v2.4.3 // indirect
8585
go.yaml.in/yaml/v3 v3.0.4 // indirect
86-
golang.org/x/crypto v0.45.0 // indirect
87-
golang.org/x/net v0.47.0 // indirect
88-
golang.org/x/sync v0.18.0 // indirect
89-
golang.org/x/sys v0.38.0 // indirect
90-
golang.org/x/term v0.37.0 // indirect
91-
golang.org/x/text v0.31.0 // indirect
86+
golang.org/x/net v0.48.0 // indirect
87+
golang.org/x/sync v0.19.0 // indirect
88+
golang.org/x/sys v0.39.0 // indirect
89+
golang.org/x/term v0.38.0 // indirect
90+
golang.org/x/text v0.32.0 // indirect
9291
golang.org/x/time v0.12.0 // indirect
93-
google.golang.org/protobuf v1.36.8 // indirect
92+
google.golang.org/protobuf v1.36.10 // indirect
9493
gopkg.in/evanphx/json-patch.v4 v4.13.0 // indirect
9594
gopkg.in/inf.v0 v0.9.1 // indirect
9695
gopkg.in/yaml.v3 v3.0.1 // indirect
9796
k8s.io/api v0.35.0 // indirect
97+
k8s.io/apiserver v0.35.0 // indirect
9898
k8s.io/component-helpers v0.35.0 // indirect
9999
k8s.io/klog/v2 v2.130.1 // indirect
100-
k8s.io/kube-openapi v0.0.0-20250910181357-589584f1c912 // indirect
100+
k8s.io/kube-openapi v0.0.0-20251125145642-4e65d59e963e // indirect
101101
k8s.io/metrics v0.35.0 // indirect
102102
k8s.io/utils v0.0.0-20251002143259-bc988d571ff4 // indirect
103103
sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 // indirect

0 commit comments

Comments
 (0)