Annotations and Labels used by Kargo

This page documents certain annotations and labels that are applicable to Kargo resource types and other Kubernetes resource types (e.g. Secrets or ServiceAccounts) and affect how Kargo handles those resources. The subset documented here are those that the maintainers have judged most likely to be of use to advanced users who may, for instance, be looking to interact programmatically with Kargo.

Annotations

Key	Target Resource(s)	Possible Values	Description
kargo.akuity.io/abort	Stage	A plain string (verification ID from .status.verifications[*].id of the Stage).	Aborts an in-progress Freight verification.
kargo.akuity.io/authorized-stage	Argo CD Application	<project>:<stage>	Indicates which Stage is authorized to manage the Application resource.
kargo.akuity.io/color	Stage	Hex color code (e.g. #ff8800)	Optional cosmetic color used in the UI's pipeline view.
kargo.akuity.io/description	Any	Any string	Optional human-readable description of the resource. May be used by the Kargo UI to display additional context or details.
kargo.akuity.io/refresh	Warehouse, Stage, Promotion	A string that is unique or at least unlikely to repeat, such as a UUID or a timestamp of "now"	Triggers reconciliation of the resource when its value changes.
kargo.akuity.io/reverify	Stage	Either a plain string (verification ID from .status.verifications[*].id of the Stage) or a JSON object with id (required), actor, and controlPlane fields. If a JSON object is provided, it is parsed as a VerificationRequest.	Triggers re-verification of a previously completed verification for the current Freight.
rbac.kargo.akuity.io/claim.<name>	ServiceAccount	Any valid OIDC claim value (e.g., sub, email, or groups)	Maps an OIDC claim to a ServiceAccount, enabling user-to-ServiceAccount mappings. For more details, refer to the access control sections of the Operator Guide and User Guide.
rbac.kargo.akuity.io/claims	ServiceAccount	Any valid OIDC claim values (e.g., sub, email, or groups)	Maps multiple OIDC claims to a ServiceAccount, enabling user-to-ServiceAccount mappings. This method is preferred over rbac.kargo.akuity.io/claim.<name>. For more details, refer to the access control sections of the Operator Guide and User Guide.
rbac.kargo.akuity.io/managed	ServiceAccount, Role, RoleBinding	"true"	Permits the UI or CLI (via the API server) to programmatically manage trios of ServiceAccount, Role, and RoleBinding resources via Kargo's own "roles" abstraction. Omit this annotation if you wish to exclusively manage these resources declaratively.

Labels

Key	Target Resource(s)	Possible Values	Description
kargo.akuity.io/alias	Freight	Any string that is unique within the project	Mutable, human-readable alias for a piece of Freight. This label is automatically synced from the resource's alias field. Users are discouraged from modifying the label directly. The label exists primarily to enable querying for Freight by alias using kubectl.
kargo.akuity.io/cred-type	Secret	git, helm, image, generic	Indicates a Secret represents credentials for a repository of the specified type. For more details, see the Managing Credentials.
kargo.akuity.io/project	Namespace	"true"	Indicates that the Namespace is eligible for adoption by a Project with the same name. This label is useful when Namespaces are unavoidably pre-created by some other agent. For more details, see the Working with Projects section.
kargo.akuity.io/shard	Promotion, Stage, Warehouse	Shard ID	Indicates a specific controller instance responsible for reconciling the resource. For Warehouse and Stage resources, this label is automatically synced from the resource's spec.shard field. Users are discouraged from modifying the label directly. The label exists primarily to enable querying for resources by shard using kubectl.