Documentation Request: Comprehensive List of CRD Annotations

[wzhramc]

Proposed Feature

Could you please add comprehensive documentation that:

• Lists all supported annotations for each CRD type
• Explains the purpose and effect of each annotation
• Provides examples of their usage
• Includes this information in the CRD reference documentation

This would greatly improve the discoverability of these features and make it easier for users to fully leverage Kargo's capabilities.

Motivation

I've noticed that the Kargo documentation lacks a reference for the annotations that can be applied to Kargo CRDs. For example, I was not aware that the color annotation existed until I discovered this example:

https://github.com/akuity/kargo-simple/blob/main/kargo/stages.yaml#L6-L7

I couldn't find it documented in the official documentation. When searching for "annotation" or "annotations" in the documentation search bar, there are no results that provide a clear list of all supported annotations and their effects.

When I checked the CRD reference for Stages I found that it doesn't include a section on annotations: https://doc.crds.dev/github.com/akuity/kargo/kargo.akuity.io/Stage/[email protected]

[krancour]

Thanks @wzhramc. Yes. These should be documented somewhere.

fwiw, other than kargo.akuity.io/color you're not missing out on much. I believe that's the only annotation that isn't merely an implementation detail. i.e. All the other annotations are things that API endpoints set/modify on a resource as a signal to its controller to take some action like abort, refresh, etc.

[fykaa]

Just to confirm before I proceed with the docs -- from what I understand, kargo.akuity.io/color is currently the only annotation intended to be set by users, and the others like abort, refresh, reverify, etc. are internal signals set by the UI/CLI/API and don’t need to be included in user-facing CRD docs. Is that right?

Also, do you think it would make sense to document these internal annotations (like the ones listed in annotations.go) somewhere in the repo itself -- maybe as dev-facing docs or a new page in the user-guide? Right now they’re kind of scattered and not obvious unless you go digging in the source.

Just want to make sure I’m aligned on what’s useful to document and what’s intentionally left internal.

cc: @krancour

[hiddeco]

(Most of) the other annotations are still worth documenting because they allow you to control Kargo's behavior through kubectl.