Add human-readable specification of Tracing Policy API to web site under Reference

[christian-2]

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem?

Currently the best exact description of Tetragon's CRD TraingPolicy resides in the source code (see also #2073). This is sub-optimal. There should be a human-friendly, if machine-generated description of the of Tetragon's tracing policy API available on tetragon.io under Reference.

See here on Slack.

Describe the feature you would like

A fourth section Tracing Policy API should be added to Reference (see above); it would sit next to Daemon Configuration, Helm Chart, and gRPC_API.

Describe your proposed solution

The content should reside under docs/content/en/docs/reference as a collection of HTML files. A pipeline that may be suitable for generating it automatically could perhaps consist of the following steps:

1. produce description in text format with go doc --all ...
2. pipe into custom script (or similar) that filters for descriptions of types and their fields only; converts those into JSON schema
3. "import" JSON schema into OpenAPI
4. let OpenAPI render static HTML files

Perhaps the model generator from kubernetes/kube-openapi ("goes through .go files, find and generate model definitions") could serve as well.

Code of Conduct

• I agree to follow this project's Code of Conduct

[christian-2]

@mtardy I have meanwhile looked how this is done in Kubernetes. If I am not mistaken, its hacks/update-openapi-spec.sh spins up a kube-apiserver as well as etcd and then contacts the first at URL path /openapi/v3 for downloading OpenAPI specifications for the Kubernetes APIs. Since Tetragon can be installed into Kubernetes, downloading an openapi.yaml for its CDR should be possible in the same way. So much for the first step; I have taken that one already.

In a second step static HTML would have to be generated from the downloaded OpenAPI spec. There are apparently suitable tools e.g. in OpenAPITools/openapi-generator, but I have not explored those yet.

Overall, this pipeline seems to be simpler than the one I had originally intended. Feel free to assign this issue to me, if that is of any help. A set of HTML files (in docs/content/en/docs/reference/tracing-policy-api/) plus perhaps a script (in contrib/) would be the likely deliverables.

[christian-2]

@mtardy I now have some output from OpenAPITools/openapi-generator. It is ready for a first review, but it is also quite large:

generator	size
html	948K
html2	1.5M
markdown	240K

Do you want me to push these files into GitHub or (perhaps better) to provide only instructions on how to generate them locally (suitable e.g. for Debian)?

[christian-2]

I have pushed the tree generators's current output to a temporary repository christian-2/tmp. This is to avoid polluting cilium/tetragon at this stage. The markdown version has already proved quite useful.

[mtardy]

Sorry I missed your messages, feel free to open a PR if you have something ready. I discussed this online and we were not sure if exposing this doc would be more interesting that the "human version" we have under concepts. Because we thought maybe that easier to use "kubectl explain" (or "tetra explain" as you suggested in another PR).

Of course if you've already invested time in this, please open a PR and we'll take a look on what we can do with it!

I'll assign this issue to you!