Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .api-docs-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ sources:
- name: dns
org: datum-cloud
repo: dns-operator
version: v0.4.0
version: v0.5.0

# Activity Tracking
- name: activity
Expand Down
29 changes: 24 additions & 5 deletions src/content/docs/docs/api/reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ _Appears in:_
| --- | --- | --- | --- |
| `startTime` <br />_string_ | StartTime is the beginning of your search window (inclusive).<br />Format Options:<br />- Relative: "now-30d", "now-2h", "now-30m" (units: s, m, h, d, w)<br /> Use for dashboards and recurring queries - they adjust automatically.<br />- Absolute: "2024-01-01T00:00:00Z" (RFC3339 with timezone)<br /> Use for historical analysis of specific time periods.<br />Examples:<br /> "now-30d" → 30 days ago<br /> "2024-06-15T14:30:00-05:00" → specific time with timezone offset | | |
| `endTime` <br />_string_ | EndTime is the end of your search window (exclusive).<br />Uses the same formats as StartTime. Commonly "now" for current moment.<br />Must be greater than StartTime.<br />Examples:<br /> "now" → current time<br /> "2024-01-02T00:00:00Z" → specific end point | | |
| `filter` <br />_string_ | Filter narrows results using CEL (Common Expression Language). Leave empty to get all events.<br />Available Fields:<br /> verb - API action: get, list, create, update, patch, delete, watch<br /> auditID - unique event identifier<br /> stageTimestamp - when this stage occurred (RFC3339 timestamp)<br /> user.username - who made the request (user or service account)<br /> responseStatus.code - HTTP response code (200, 201, 404, 500, etc.)<br /> objectRef.namespace - target resource namespace<br /> objectRef.resource - resource type (pods, deployments, secrets, configmaps, etc.)<br /> objectRef.name - specific resource name<br />Operators: ==, !=, <, >, <=, >=, &&, \|\|, in<br />String Functions: startsWith(), endsWith(), contains()<br />Common Patterns:<br /> "verb == 'delete'" - All deletions<br /> "objectRef.namespace == 'production'" - Activity in production namespace<br /> "verb in ['create', 'update', 'delete', 'patch']" - All write operations<br /> "responseStatus.code >= 400" - Failed requests<br /> "user.username.startsWith('system:serviceaccount:')" - Service account activity<br /> "objectRef.resource == 'secrets'" - Secret access<br /> "verb == 'delete' && objectRef.namespace == 'production'" - Production deletions<br />Note: Use single quotes for strings. Field names are case-sensitive.<br />CEL reference: https://cel.dev | | |
| `filter` <br />_string_ | Filter narrows results using CEL (Common Expression Language). Leave empty to get all events.<br />Available Fields:<br /> verb - API action: get, list, create, update, patch, delete, watch<br /> auditID - unique event identifier<br /> requestReceivedTimestamp - when the API server received the request (RFC3339 timestamp)<br /> user.username - who made the request (user or service account)<br /> user.uid - unique user identifier (stable across username changes)<br /> responseStatus.code - HTTP response code (200, 201, 404, 500, etc.)<br /> objectRef.namespace - target resource namespace<br /> objectRef.resource - resource type (pods, deployments, secrets, configmaps, etc.)<br /> objectRef.name - specific resource name<br />Operators: ==, !=, <, >, <=, >=, &&, \|\|, in<br />String Functions: startsWith(), endsWith(), contains()<br />Common Patterns:<br /> "verb == 'delete'" - All deletions<br /> "objectRef.namespace == 'production'" - Activity in production namespace<br /> "verb in ['create', 'update', 'delete', 'patch']" - All write operations<br /> "responseStatus.code >= 400" - Failed requests<br /> "user.username.startsWith('system:serviceaccount:')" - Service account activity<br /> "user.uid == '550e8400-e29b-41d4-a716-446655440000'" - Specific user by UID<br /> "objectRef.resource == 'secrets'" - Secret access<br /> "verb == 'delete' && objectRef.namespace == 'production'" - Production deletions<br />Note: Use single quotes for strings. Field names are case-sensitive.<br />CEL reference: https://cel.dev | | |
| `limit` <br />_integer_ | Limit sets the maximum number of results per page.<br />Default: 100, Maximum: 1000.<br />Use smaller values (10-50) for exploration, larger (500-1000) for data collection.<br />Use continue to fetch additional pages. | | |
| `continue` <br />_string_ | Continue is the pagination cursor for fetching additional pages.<br />Leave empty for the first page. If status.continue is non-empty after a query,<br />copy that value here in a new query with identical parameters to get the next page.<br />Repeat until status.continue is empty.<br />Important: Keep all other parameters (startTime, endTime, filter, limit) identical<br />across paginated requests. The cursor is opaque - copy it exactly without modification. | | |

Expand All @@ -109,7 +109,7 @@ _Appears in:_

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `results` <br />_Event array_ | Results contains matching audit events, sorted newest-first.<br />Each event follows the Kubernetes audit.Event format with fields like:<br /> verb, user.username, objectRef.\{namespace,resource,name\}, stageTimestamp,<br /> responseStatus.code, requestObject, responseObject<br />Empty results? Try broadening your filter or time range.<br />Full documentation: https://kubernetes.io/docs/reference/config-api/apiserver-audit.v1/ | | |
| `results` <br />_Event array_ | Results contains matching audit events, sorted newest-first.<br />Each event follows the Kubernetes audit.Event format with fields like:<br /> verb, user.username, objectRef.\{namespace,resource,name\}, requestReceivedTimestamp,<br /> stageTimestamp, responseStatus.code, requestObject, responseObject<br />Empty results? Try broadening your filter or time range.<br />Full documentation: https://kubernetes.io/docs/reference/config-api/apiserver-audit.v1/ | | |
| `continue` <br />_string_ | Continue is the pagination cursor.<br />Non-empty means more results are available - copy this to spec.continue for the next page.<br />Empty means you have all results. | | |
| `effectiveStartTime` <br />_string_ | EffectiveStartTime is the actual start time used for this query (RFC3339 format).<br />When you use relative times like "now-7d", this shows the exact timestamp that was<br />calculated. Useful for understanding exactly what time range was queried, especially<br />for auditing, debugging, or recreating queries with absolute timestamps.<br />Example: If you query with startTime="now-7d" at 2025-12-17T12:00:00Z,<br />this will be "2025-12-10T12:00:00Z". | | |
| `effectiveEndTime` <br />_string_ | EffectiveEndTime is the actual end time used for this query (RFC3339 format).<br />When you use relative times like "now", this shows the exact timestamp that was<br />calculated. Useful for understanding exactly what time range was queried.<br />Example: If you query with endTime="now" at 2025-12-17T12:00:00Z,<br />this will be "2025-12-17T12:00:00Z". | | |
Expand Down Expand Up @@ -264,6 +264,23 @@ _Appears in:_
| `content` <br />_string_ | | | Format: ipv6 <br /> |


#### ALIASRecordSpec



ALIASRecordSpec is like CNAME but intended for providers that implement an ALIAS/ANAME-style record.
The content is a hostname (FQDN or relative) with an optional trailing dot.



_Appears in:_
- [RecordEntry](#recordentry)

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `content` <br />_string_ | | | MaxLength: 253 <br />MinLength: 1 <br />Pattern: `^([A-Za-z0-9_](?:[-A-Za-z0-9_]\{0,61\}[A-Za-z0-9_])?)(?:\.([A-Za-z0-9_](?:[-A-Za-z0-9_]\{0,61\}[A-Za-z0-9_])?))*\.?$` <br /> |


#### ARecordSpec


Expand Down Expand Up @@ -366,7 +383,7 @@ _Appears in:_
| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `dnsZoneRef` <br />_[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v/#localobjectreference-v1-core)_ | DNSZoneRef references the DNSZone (same namespace) this recordset belongs to. | | Required: \{\} <br /> |
| `recordType` <br />_[RRType](#rrtype)_ | RecordType is the DNS RR type for this recordset. | | Enum: [A AAAA CNAME TXT MX SRV CAA NS SOA PTR TLSA HTTPS SVCB] <br />Required: \{\} <br /> |
| `recordType` <br />_[RRType](#rrtype)_ | RecordType is the DNS RR type for this recordset. | | Enum: [A AAAA ALIAS CNAME TXT MX SRV CAA NS SOA PTR TLSA HTTPS SVCB] <br />Required: \{\} <br /> |
| `records` <br />_[RecordEntry](#recordentry) array_ | Records contains one or more owner names with values appropriate for the RecordType. | | MinItems: 1 <br /> |


Expand Down Expand Up @@ -617,7 +634,7 @@ _Appears in:_

| Field | Description | Default | Validation |
| --- | --- | --- | --- |
| `recordType` <br />_[RRType](#rrtype)_ | RecordType is the DNS RR type for this recordset. | | Enum: [A AAAA CNAME TXT MX SRV CAA NS SOA PTR TLSA HTTPS SVCB] <br />Required: \{\} <br /> |
| `recordType` <br />_[RRType](#rrtype)_ | RecordType is the DNS RR type for this recordset. | | Enum: [A AAAA ALIAS CNAME TXT MX SRV CAA NS SOA PTR TLSA HTTPS SVCB] <br />Required: \{\} <br /> |
| `records` <br />_[RecordEntry](#recordentry) array_ | Records contains one or more owner names with values appropriate for the RecordType.<br />The RecordEntry schema is shared with DNSRecordSet for easy translation. | | |


Expand Down Expand Up @@ -761,7 +778,7 @@ _Underlying type:_ _string_


_Validation:_
- Enum: [A AAAA CNAME TXT MX SRV CAA NS SOA PTR TLSA HTTPS SVCB]
- Enum: [A AAAA ALIAS CNAME TXT MX SRV CAA NS SOA PTR TLSA HTTPS SVCB]

_Appears in:_
- [DNSRecordSetSpec](#dnsrecordsetspec)
Expand All @@ -770,6 +787,7 @@ _Appears in:_
| Field | Description |
| `A` | |
| `AAAA` | |
| `ALIAS` | |
| `CNAME` | |
| `TXT` | |
| `MX` | |
Expand Down Expand Up @@ -802,6 +820,7 @@ _Appears in:_
| `a` <br />_[ARecordSpec](#arecordspec)_ | Exactly one of the following type-specific fields should be set matching RecordType. | | |
| `aaaa` <br />_[AAAARecordSpec](#aaaarecordspec)_ | | | |
| `cname` <br />_[CNAMERecordSpec](#cnamerecordspec)_ | | | |
| `alias` <br />_[ALIASRecordSpec](#aliasrecordspec)_ | | | |
| `ns` <br />_[NSRecordSpec](#nsrecordspec)_ | | | |
| `txt` <br />_[TXTRecordSpec](#txtrecordspec)_ | | | |
| `soa` <br />_[SOARecordSpec](#soarecordspec)_ | | | |
Expand Down