📖 WIP: OPRUN-4357: Add documentation URLs into CRD descriptions

[tmshort]

These documentation URLs are templated, so that they can be updated
downstream as needed.

Added quick-helm utility to go template a file using helm-like
semantics (i.e. everything is prefixed with .Values), because the crd-ref-doc utility does not have a mechanism to template.

Description

Reviewer Checklist

• API Go Documentation
• Tests: Unit Tests (and E2E Tests, if appropriate)
• Comprehensive Commit Messages
• Links to related GitHub Issue(s)

[netlify]

✅ Deploy Preview for olmv1 ready!

Name	Link
🔨 Latest commit	0dece5b
🔍 Latest deploy log	https://app.netlify.com/projects/olmv1/deploys/6938700046ef31000782ce9a
😎 Deploy Preview	https://deploy-preview-2377--olmv1.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 34 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.51%. Comparing base (f17f3c5) to head (0dece5b).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
hack/tools/quick-helm/main.go	0.00%	34 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2377      +/-   ##
==========================================
+ Coverage   71.10%   74.51%   +3.40%     
==========================================
  Files          95       96       +1     
  Lines        7323     7357      +34     
==========================================
+ Hits         5207     5482     +275     
+ Misses       1683     1442     -241     
  Partials      433      433              

Flag	Coverage Δ
e2e	44.99% <ø> (-0.04%)	⬇️
experimental-e2e	49.35% <ø> (?)
unit	58.55% <0.00%> (-0.28%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign grokspawn for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[perdasilva]

This looks really good! I don't know if we want to add the links to the docs of each of the CRDs. But, this would work perfectly for the .spec.config case.

[pedjak]

Added quick-helm utility to go template a file using helm-like
semantics (i.e. everything is prefixed with .Values), because the crd-ref-doc utility does not have a mechanism to template.

How hard would it be to add this logic into crd-ref-doc instead, in order to keep the number of utilities low?

[pedjak]

Perhaps we could rely on existing Godoc links?

[pedjak]

CRDs are based on OpenAPI 3.0 which has externalDocs field: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md#schema Perhaps we should add the documentation links using that method, so that consumers could interpret it properly?

[tmshort]

CRDs are based on OpenAPI 3.0 which has externalDocs field: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md#schema Perhaps we should add the documentation links using that method, so that consumers could interpret it properly?

This PR is less about the format/content of the actual links, but on the ability to substitute different links for upstream and downstream. That is the part that really needs review. The text of the CRD is of secondary importance to the method.

If we want to take that approach for the content, I'm fine with it.

(Also, not sure how to get that field into the CRD from the golang definitions?)

[tmshort]

Perhaps we could rely on existing Godoc links?

I don't think that will work, as the intent is to reference Openshift documentation (i.e. on redhat.com) downstream, not repository documentation.

[tmshort]

Added quick-helm utility to go template a file using helm-like
semantics (i.e. everything is prefixed with .Values), because the crd-ref-doc utility does not have a mechanism to template.

How hard would it be to add this logic into crd-ref-doc instead, in order to keep the number of utilities low?

We don't own crd-ref-doc, and I'm not sure they'll want to support Helm-style templating within the documents themselves (although they do use go templating for generation). There doesn't seem to be much activity in that repo; the last merge activity was Sept 2025, and even the automated bot PRs have been sitting around for 3 weeks.

AFAIK, there's some urgency here, and I don't think we can wait on that. I was going to try to use helm at first, but that would have required a full chart definition. The solution proposed is a very simple go template utility that uses some Helm syntactic sugar.

[tmshort]

This looks really good! I don't know if we want to add the links to the docs of each of the CRDs. But, this would work perfectly for the .spec.config case.

I swear I read something about kubectl explain <resource> and having the ability to see the documentation URL as part of it?
EDIT: use proper command

[pedjak]

I swear I read something about kubectl describe <resource> and having the ability to see the documentation URL as part of it?

kubectl explain <crd> is what we need to use here.

[pedjak]

(Also, not sure how to get that field into the CRD from the golang definitions?)

We could extend controller-gen with additional markers like:

kubebuilder:externaldocs:description="foo",url="http://bar.com"

or do some postprocessing of the generated CRD and extract links in Godoc link format and add needed externalDocs schema field to CRD schema or overwrrite with some downstream values.

[pedjak]

AFAIK, there's some urgency here, and I don't think we can wait on that.

In that case, why not do some quick solution downstream?

[perdasilva]

@pedjak the ask is that we carry some documentation link around configuration specifically looking at how to determine the bundle configuration given that we don't yet have a way to get the bundle configuration schema out of the bundle. I think this makes sense for now even in the upstream, tbh. In which case we'd need a way to replace it downstream. We could also just do it downstream through some sed magic, but my worry there is that it will get forgotten. I think its better to have a single thread of maintenance for this particular thing. It's quite possible that in the future we remove it once we can better inspect the bundle configuration schema.

Thinking about it a bit more as I write, let me come up with the actual documentation that would meet the bar and see if we can just insert it in the CRD directly and avoid this whole url thing all together.

/hold on the basis described above

[tmshort]

AFAIK, there's some urgency here, and I don't think we can wait on that.

In that case, why not do some quick solution downstream?

In this case, we need something upstream that gives us the ability to customize the value both upstream and downstream. TL;DR: Downstream, we really can't modify anything outside the openshift directory. Meaning we can't modify the source of the CRDs downstream. But we can add configurables upstream that we then use downstream.

A quick fix downstream would be to do some sort of yq manipulation of the manifests when the containers are built, which seemed messy, and would likely be thrown out when a better solution (like this one) presents itself.

The downstream manifests are deployed via helm template by cluster-olm-operator. So, whatever we do has to be helm compatible, or has to be done when the helm chart is copied to the containers.

[tmshort]

I swear I read something about kubectl describe <resource> and having the ability to see the documentation URL as part of it?

kubectl explain <crd> is what we need to use here.

That's what I meant. I updated my comment.