VMAlert datasource bearer token isn't documented

[Sleuth56]

The CRD reference in the API docs for vmalert doesn't show that bearer tokens are a possibility to use with the datasource options. VMAlert supports this option and the operator successfully applies this configuration when the fields are present in the CRD.

apiVersion: operator.victoriametrics.com/v1beta1
kind: VMAlert
metadata:
  name: vmalert
  namespace: victoria-metrics
spec:
  datasource:
    url: http://vmauth-vmalert:8427
    bearerTokenSecret:
      name: vmalert-token
      key: token

[mehrdadbn9]

I dug into this — confirmed, and it's slightly broader than the vmalert datasource section.

bearerTokenFile / bearerTokenSecret are missing from the generated API docs for every type that embeds HTTPAuth (datasource, notifier, remoteRead, remoteWrite), and from the HTTPAuth section itself, while its sibling fields (basicAuth, oauth2, tlsConfig, headers) all render fine.

Root cause: HTTPAuth embeds BearerAuth as an anonymous pointer (*BearerAuth with json:",inline,omitempty", api/operator/v1beta1/vmextra_types.go). crd-ref-docs flattens value embeds (hence the sibling fields showing up) but drops fields from embedded pointer types. The CRD schema itself is unaffected — controller-gen flattens the pointer embed correctly — which is why the fields work at runtime as you observed.

Two possible fixes:

1. Teach crd-ref-docs (the AndrewChubatiuk/crd-ref-docs fork used in the Makefile) to flatten embedded pointer structs — no API change, fixes all affected sections at once.
2. Change the embed to a value BearerAuth. Wire-compatible (both fields are omitempty), but it changes nil-check semantics at 3 call sites (factory/vmalert/vmalert.go, factory/vmanomaly/config/config.go), so it's more invasive.

Happy to send a PR for whichever direction you prefer.

[mehrdadbn9]

Update: I implemented option 1 and verified it against this repo at the pinned crd-ref-docs commit (4deb8b1). The fix is a one-liner in types.InlineTypes: dereference embedded pointer types to their underlying struct before the type-map lookup.

Result on make docs (patched vs unpatched, same environment): 31 lines added, 0 removed — bearerTokenFile/bearerTokenSecret now render in HTTPAuth and all four vmalert consumers. It also revealed a second instance of the same bug: SecurityContext (built entirely from pointer embeds) currently renders with no fields at all, and gets its full field table back.

PR to the crd-ref-docs fork: AndrewChubatiuk/crd-ref-docs#2. Happy to also send the version-bump PR here once that merges.