Last modified June 26, 2026

Kubernetes resource annotation reference

Notice: Annotations on Kubernetes resources are set by many different parties, and for various reasons. In this overview we explain our reasons for using a relevant set of annotations, and which values or value format is expected. If you are missing information, please consult upstream documentation from Kubernetes etc., or ask a Giant Swarm contact for more information. Also check our corresponding labels reference page.

app-operator.giantswarm.io/cordon-reason

On an App or Chart resource, this annotation indicates the reason why app-operator should currently not reconcile this app, until the app-operator.giantswarm.io/cordon-until date has passed.

More information: Source

app-operator.giantswarm.io/cordon-until

On an App or Chart resource, this annotation indicates a date until which app-operator should currently not reconcile this app. If specified, the app-operator.giantswarm.io/cordon-reason annotation should also be set.

More information: Source

cluster.giantswarm.io/description

Used on the Cluster resource to provide a human-readable description of the cluster. This description is shown in Giant Swarm web interfaces.

kustomize.toolkit.fluxcd.io/force

Can be set on any resource to control Flux reconciliation behaviour. The value can be either Enabled or Disabled. If set to Enabled, Flux will replace the resources in-cluster if the patching fails due to immutable field changes. More details in the Flux docs.

kustomize.toolkit.fluxcd.io/prune

The value disabled on any resource disables Flux garbage collection for this resource. More details in the Flux docs.

kustomize.toolkit.fluxcd.io/reconcile

Used on any resource. When set to disabled, Flux will no longer apply changes, nor will it prune the resource. Flux docs.

kustomize.toolkit.fluxcd.io/ssa

Used on any resource to control the server-side apply behaviour of Flux. The values Override, Merge, IfNotPresent, and Ignore can occur. More information on these settings is available in the Flux docs.

network-topology.giantswarm.io/mode

Found on the AWSCluster resource for Cluster API provider AWS (CAPA) clusters. Specifies how transit gateways for the cluster will get set up in AWS. Possible values are: None, GiantSwarmManaged, UserManaged.

More information: Source

network-topology.giantswarm.io/transit-gateway

Found on the AWSCluster resource for Cluster API provider AWS (CAPA) clusters. Specifies the ID of the transit gateway to use when the topology mode (network-topology.giantswarm.io/mode) is set to UserManaged.

More information: Source

network-topology.giantswarm.io/prefix-list

Found on the AWSCluster resource for Cluster API provider AWS (CAPA) clusters. Specifies the ID of the managed prefix list to use when the topology mode (network-topology.giantswarm.io/mode) is set to UserManaged.

More information: Source

network.giantswarm.io/wildcard-cname-target

Used on a cluster resource to define the CNAME target for the wildcard domain created by Giant Swarm operators in the cluster’s DNS zone. The annotation value is the subdomain part only — operators construct the full target by appending the cluster’s base domain.

For example, setting this annotation to gateway results in the wildcard DNS record pointing to gateway.<baseDomain>. The default value is ingress.

reconcile.fluxcd.io/requestedAt

On a Flux resource, this annotation indicates that a Flux reconciliation has been requested. More info in the Flux docs on HelmReleases, for example.

reconcile.fluxcd.io/forceAt

On a HelmRelease resource, this annotation indicates that a forceful Helm install or upgrade has been requested. More info in the Flux docs.

silence.application.giantswarm.io/force-all

On a Silence resource, the value true forces the silence to suppress every alert it matches, including critical alerts that the platform would otherwise keep flowing. Without this annotation, silences automatically exclude alerts targeting all notification pipelines (the most critical, system-wide alerts). The Heartbeat alert is always preserved. Use with caution, as it removes the safety net for critical notifications.

More information: Forcing complete silence