Documentation for UDS Package CR / Exemption CR

[mjnagel]

Is your feature request related to a problem? Please describe.

Currently there is some documentation surrounding the UDS Package/Exemption CRs but it is hidden in the src/pepr/operator folder making it not highly visible to end users. It is also currently missing documentation for monitor, which exists in a separate doc. UDS exemptions are also briefly documented here with other documentation under the pepr folder.

Describe the solution you'd like

It would be good to consistently document the operator/CRs under the docs/ folder. This will especially be helpful as we intend to surface documentation in a docs site soon.

An ideal state in my head:

• high level "operator" doc in docs/ that provides some overview of what the operator is and how it is used
• individual docs for pieces of the spec (expose, monitor, allow, sso) with more in depth explanations of options/architecture
• other operator docs as necessary (nerd notes?)

Additional context

There are probably plenty more docs considerations to help with clarifying things, but the operator seems like a minimal effort high value place to start.

[RothAndrew]

Would something like this help make this easier?

[RothAndrew]

I went down the rabbit hole with JSON schemas today. My use case was to document the values.yaml file for a helm chart I'm making, but there are a lot of similarities.

If you are able to get a package.schema.json and exemption.schema.json created, you can use a tool like Adobe's jsonschema2md to generate detailed docs.

I whipped up a pre-commit hook that will do it:

  - repo: https://github.com/rothandrew/pre-commit-hook-adobe-jsonschema2md
    rev: 1.0.0
    hooks:
      - id: jsonschema2md
        args: ["-d", "chart", "-o", "chart/docs", "-x", "-", "--example-format", "yaml", "--header", "true"]

just change the values for -d and -o to whatever you need it to be.

The added benefit of doing it this way is you get the .schema.json file which can be used in your IDE when building out one of the custom resources.

Apparently there's a way to generate JSON schema from the K8s API, though it sounds a little gross: https://stackoverflow.com/questions/71089827/is-there-any-easy-way-to-convert-crd-customresourcedefinition-to-json-schema

[jacobbmay]

I would like to see known issues documented for the custom resources so as a consumer of UDS packages I know where to start looking when I run into an issue and know where to document new ones when they are discovered.

A specific issue recently discovered that should be documented is that KubeAPI egress policies that are generated from a UDS package do not work as expected by default in clusters that us Cilium for CNI. The policies allow egress based on node and kubernetes service IPs and Cilium does not currently support selecting cluster resources by IP in network policies.

We should document that in order for KubeAPI egress policies to work with Cilium, Cilium must be configured to enable node selection by CIDR.