Configuration
Well-known metadata
Every label, annotation, finalizer and node taint Bloodraven reads or writes, with its writer, value grammar and stability level.
This page lists every label, annotation and finalizer key Bloodraven reads or writes, and its node taint, with the objects that carry each one, who writes it, the grammar of its value, and how stable it is:
- Public: you may set or select on it, and it changes only with a release-noted break.
- Operator-owned read-only: the operator writes it; you may read it, but do not edit or remove it.
- Internal (may change): operator bookkeeping. Do not read or edit it; its key and value can change in any release.
Every key is under bloodraven.shipstream.io: the prefix itself (bloodraven.shipstream.io/<name>), or a subdomain of it for a family whose name part is an id (<kind>-hold.bloodraven.shipstream.io/<id>, <namespace>.db-readonly.bloodraven.shipstream.io/<group>), so one prefix match finds every member. The app.kubernetes.io/* labels the operator also sets are the Kubernetes recommended labels and are not listed. A boolean label value is true or false.
A structured internal value is a JSON object with a schemaVersion member. A payload with a version the operator does not know proves nothing: the operator refuses it and reports it with a condition and a Warning Event (MetadataVersionUnsupported), as each key below says.
Action annotations
A user (or kubectl bloodraven) sets these on the MysqlFailoverGroup to request a one-shot action. They share one value grammar, <subject>(:<key>=<value>)*: the subject is a site name or an operation id, a pair splits at its first =, and a value matches ^[A-Za-z0-9._/+-]+$, so it never contains : or =. An instant inside a value uses the ISO 8601 basic UTC form, for example 20261104T100000Z. A destructive action on a site-name subject carries confirm=<metadata.name>:uid=<metadata.uid>; an operation id the operator minted and never reuses needs neither. Two keys are outside the grammar: RevokeDeploymentLeasesAnnotation is presence-only (its value is ignored), and RotateKeyringAnnotation takes a bare site name, since a rotation destroys nothing. A value that does not parse, or fails its interlock, is never acted on: each key's consumer reports why (a Warning Event, or the status of the request) and, for most keys, removes the annotation so the request can be set again; the entries below say which. Never commit an action annotation to a GitOps repository: a sync re-applies it.
| Key | On | Writer | Value and meaning | Stability |
|---|---|---|---|---|
bloodraven.shipstream.io/planned-failover (annotation) | MysqlFailoverGroup | user (kubectl bloodraven promote); the operator removes it | <site>[:maxLagWait=<duration>], for example pdx or pdx:maxLagWait=30s; maxLagWait is 1s to 1h. This key triggers a graceful, cooldown-respecting switchover to the named PrimaryCandidate site. The operator removes it once the request is decided: accepted, rejected or skipped. A request that is deferred (onCooldown=Defer, a deployment hold), or that waits for admission, keeps it until then; removing it cancels a deferred run. | Public |
bloodraven.shipstream.io/acknowledge-planned-failover-hold (annotation) | MysqlFailoverGroup | user (kubectl bloodraven ack-planned-failover-hold); the operator removes it | <runID>, the held run's status.plannedFailoverHold.runID. This key acknowledges an automation hold. An operator-minted run id cannot match another group, so the value needs no confirm= or uid= pair. The operator removes it after it clears the hold. | Public |
bloodraven.shipstream.io/reclone-site (annotation) | MysqlFailoverGroup | user (kubectl bloodraven reclone); operator | <site>:confirm=<metadata.name>:uid=<metadata.uid>, plus :gtidPrefix=<uuid prefix> when the site has diverged. This key asks the operator to reclone one site from the current primary with CLONE INSTANCE, which wipes the site's datadir. When the site has a recorded divergent GTID set (status.sites.divergentGtid), gtidPrefix= is required: at least 8 characters of the source UUID of the set's first entry. It proves the requester read the divergence. The operator also writes it to drain status.restoreReclones, and removes it when the clone is done or the request is rejected. | Public |
bloodraven.shipstream.io/revoke-deployment-leases (annotation) | MysqlFailoverGroup | user; the operator removes it | any; its presence is the request. This key revokes every deployment lease the group holds. Lease admission stays closed while it is set; the operator removes it once every revocation has persisted, and a value changed meanwhile is a new request it handles first. | Public |
bloodraven.shipstream.io/rotate-keyring (annotation) | MysqlFailoverGroup | user; the operator removes it | <site>. This key triggers an InnoDB master-key rotation on the named site. The operator refuses to rotate the active primary: rotate the replicas, run a planned failover, then rotate the former primary. | Public |
bloodraven.shipstream.io/release-pitr-archive-binding (annotation) | MysqlFailoverGroup | user; the operator removes it | <binding id>:confirm=<metadata.name>:uid=<metadata.uid>. This key releases one PITR archive binding and deletes its key snapshots. The binding id is derived from the destination, so it recurs in a re-created group of the same name: the uid pair keeps a stale request from releasing the new group's binding. | Public |
Failover record and planned-failover bookkeeping
| Key | On | Writer | Value and meaning | Stability |
|---|---|---|---|---|
bloodraven.shipstream.io/last-failover, bloodraven.shipstream.io/last-failover-target (annotation) | MysqlFailoverGroup | operator | an RFC 3339 UTC instant at second precision; the target site name. These keys copy the anti-flap record (status.lastFailover) to object metadata, so a status-write outage that overlaps an operator restart cannot lose the cooldown. Both are written in one patch on every promotion. | Operator-owned read-only |
bloodraven.shipstream.io/promotion-gtid-executed (annotation) | MysqlFailoverGroup | operator | a GTID set. This key is the out-of-band copy of the promotion watermark (status.lastFailover.promotionGtidExecuted), written with bloodraven.shipstream.io/last-failover and bloodraven.shipstream.io/last-failover-target. Omitted above 64 KiB. Ignored unless bloodraven.shipstream.io/promotion-gtid-executed-for names the event the other two keys record. | Operator-owned read-only |
bloodraven.shipstream.io/promotion-gtid-executed-for (annotation) | MysqlFailoverGroup | operator | <last-failover> <last-failover-target> (one space), for example 2026-11-04T10:00:00Z iad. This key binds the watermark to its failover event, written and deleted in the same patch as bloodraven.shipstream.io/promotion-gtid-executed. A watermark whose binding does not name the event the other two keys record is no watermark. | Operator-owned read-only |
bloodraven.shipstream.io/planned-failover-status-fence (annotation) | MysqlFailoverGroup | operator | an ISO 8601 basic UTC instant with nanoseconds, 20261104T100000.123456789Z. This key is bumped with a write conditioned on the resourceVersion an ambiguous status write was made against. Its success proves that write can never commit. Each bump moves past the stored value. | Internal (may change) |
bloodraven.shipstream.io/planned-failover-terminal (annotation) | MysqlFailoverGroup | operator | {"schemaVersion":1,"runID":"<runID>","outcome":"<outcome>","reason":"<reason>","warnings":["<warning>"]} (reason and warnings may be omitted). This key ends a run outside /status when its status writes stall. Every planned-failover predicate treats the run it names as terminal; a ManualRecoveryRequired marker is also a hold record. A marker with a schemaVersion the operator does not know is reported (Degraded=True/MetadataVersionUnsupported and a Warning Event) and proves no outcome, but one naming a run with outcome ManualRecoveryRequired still holds automation. | Internal (may change) |
bloodraven.shipstream.io/planned-failover-stall-since (annotation) | MysqlFailoverGroup | operator | <runID>:since=<YYYYMMDDThhmmssZ>. This key is the durable start of the status-stall deadline. | Internal (may change) |
bloodraven.shipstream.io/planned-failover-manager-absent-since (annotation) | MysqlFailoverGroup | operator | <runID>:since=<YYYYMMDDThhmmssZ>. This key is the durable start of the manager-absence deadline. | Internal (may change) |
bloodraven.shipstream.io/planned-failover-confirmed (annotation) | MysqlFailoverGroup | operator | <runID>:since=<YYYYMMDDThhmmssZ>, the confirmation time. This key records, before the run releases its claim, that the run's promotion was confirmed, recorded and published, so a restart before the final status write does not take the released claim back. Removed when the run ends. | Internal (may change) |
bloodraven.shipstream.io/encryption-status-fence (annotation) | MysqlFailoverGroup | operator | an RFC 3339 timestamp. This key is bumped to advance the group's resourceVersion, so a status write conditioned on an older version (one whose response was lost) can no longer commit. The write is what matters; nothing reads the value. | Internal (may change) |
bloodraven.shipstream.io/restore-confirm (annotation) | the in-place restore Job | operator | the confirm token. This key is the spec.restoreInPlace.confirm token the in-place restore Job was created for, so a Job left over from an earlier request with the same name is not mistaken for the current one. | Internal (may change) |
Finalizers
Each finalizer is named after its kind. The operator adds and removes them; removing one by hand skips the cleanup it guards.
| Key | On | Writer | Value and meaning | Stability |
|---|---|---|---|---|
bloodraven.shipstream.io/failover-group (finalizer) | MysqlFailoverGroup | operator | none (a finalizer). This key runs the graceful-shutdown sequence (node taints removed, DNS records deleted) before a MysqlFailoverGroup is deleted. | Internal (may change) |
bloodraven.shipstream.io/mysqldatabase (finalizer) | MysqlDatabase | operator | none (a finalizer). This key guards the MySQL-side cleanup of a MysqlDatabase. | Internal (may change) |
bloodraven.shipstream.io/mysqlbackup (finalizer) | MysqlBackup | operator | none (a finalizer). This key guards the artifact cleanup of a MysqlBackup. | Internal (may change) |
bloodraven.shipstream.io/mysqlbackup-verification (finalizer) | MysqlBackupVerification | operator | none (a finalizer). This key guards the cleanup of a MysqlBackupVerification's resources. | Internal (may change) |
Group routing labels
The operator puts these on the objects it manages for a MysqlFailoverGroup (pods, Services, Deployments, StatefulSets, Secrets). Services, NetworkPolicies and monitors select on them. Operator labels win over spec.podLabels.
| Key | On | Writer | Value and meaning | Stability |
|---|---|---|---|---|
bloodraven.shipstream.io/failover-group (label) | managed objects and pods; MysqlBackup, MysqlBackupVerification | operator; kubectl bloodraven backup and verify; user, on a MysqlBackup or MysqlBackupVerification it creates | the group name. This key names the owning MysqlFailoverGroup. It is also on MysqlBackups and MysqlBackupVerifications (spec.failoverGroupRef), and kubectl bloodraven sets it on the ones it creates. The one place a user writes it is a MysqlBackup or MysqlBackupVerification created by hand: set it to spec.failoverGroupRef, with bloodraven.shipstream.io/backup-profile. On every object the operator manages it is the operator's. | Operator-owned read-only |
bloodraven.shipstream.io/site (label) | managed objects and pods | operator | the site name. This key names the site. It is part of every Deployment and StatefulSet selector, which is immutable: a workload whose selector differs from the one the operator renders is refused (Degraded=True/WorkloadSelectorMismatch). | Operator-owned read-only |
bloodraven.shipstream.io/role (label) | MySQL pods | operator | primary or replica. This key is the site's role, set on the live pods each health poll. The primary and replica Services select on it. | Operator-owned read-only |
bloodraven.shipstream.io/healthy (label) | MySQL pods | operator | true or false. This key is the site's verdict from its last health poll. The replica Service and a ReadOnly site's Service select on "true". | Operator-owned read-only |
bloodraven.shipstream.io/dragonfly-role (label) | Dragonfly pods | operator | master or replica. This key is a Dragonfly pod's operator-assigned role. The active Service selects on it together with bloodraven.shipstream.io/dragonfly-traffic. | Operator-owned read-only |
bloodraven.shipstream.io/dragonfly-traffic (label) | Dragonfly pods | operator | true, or absent. This key gates whether a Dragonfly pod is eligible for the active Service, which selects "true". A planned failover removes it from the source pod before the takeover, so the Service sheds the old endpoint first. | Operator-owned read-only |
Managed-object bookkeeping
| Key | On | Writer | Value and meaning | Stability |
|---|---|---|---|---|
bloodraven.shipstream.io/keyring-version (label) | keyring escrow Secrets | operator; the keyring escrow recovery runbook reads it | an integer. This key is the escrow version on a site's keyring escrow Secret. | Internal (may change) |
bloodraven.shipstream.io/keyring-digest (annotation) | keyring escrow Secrets | operator | sha256:<hex>. This key records the digest of the escrowed keyring bytes. It is informational: the operator always recomputes it. | Internal (may change) |
bloodraven.shipstream.io/spec-hash (annotation) | site Deployments and other managed objects | operator | a hash. This key is the hash of the rendered spec of a managed object; a difference starts an ordered update. | Internal (may change) |
bloodraven.shipstream.io/managed-service-annotations (annotation) | Services | operator | a JSON list of annotation keys. This key lists the Service annotations the operator manages, so it can remove one that leaves the spec. | Internal (may change) |
bloodraven.shipstream.io/credential-hash (annotation) | credential Secrets | operator | a hash. This key records the hash of the credentials last applied. | Internal (may change) |
bloodraven.shipstream.io/system-schema-restriction (annotation) | credential Secrets | operator | a hash. This key records the credential hash for which the application user's system-schema restriction last succeeded. | Internal (may change) |
bloodraven.shipstream.io/dragonfly-load-hold (annotation) | Dragonfly pods | operator | an RFC 3339 time, when the hold started. This key marks a Dragonfly pod whose traffic the operator holds off until it has loaded its snapshot: the active site of a snapshot-restore upgrade that ended while it was still loading. While it is set, the operator removes the pod's bloodraven.shipstream.io/dragonfly-traffic again whoever restored it, and it removes the annotation once the site answers as loaded. | Internal (may change) |
Backup and verification labels
| Key | On | Writer | Value and meaning | Stability |
|---|---|---|---|---|
bloodraven.shipstream.io/mysqlbackup (label) | backup and cleanup Jobs, MysqlBackupVerification | operator | the MysqlBackup name. This key names the MysqlBackup a Job or a verification belongs to. | Operator-owned read-only |
bloodraven.shipstream.io/backup-profile (label) | MysqlBackup, MysqlBackupVerification, their Jobs and CronJobs | operator; kubectl bloodraven backup and verify; user | the profile name. This key names the backup profile (spec.profileName). Set it with bloodraven.shipstream.io/failover-group when you create a MysqlBackup by hand. | Public |
bloodraven.shipstream.io/backup-schedule (label) | MysqlBackup, backup CronJobs | operator | the schedule name. This key names the schedule that created a MysqlBackup. The schedule rollup reads it. | Public |
bloodraven.shipstream.io/resource (label) | operator-created Jobs, CronJobs and Secrets | operator | backup, backup-cleanup, backup-schedule, restore, backup-verification, backup-verification-schedule or pitr-archive-check. This key classifies an operator-created Job, CronJob or Secret. | Operator-owned read-only |
bloodraven.shipstream.io/backup-encrypted (label) | backup Jobs and their pods | operator | true, or absent. This key marks a backup Job (and its pods) that writes an encrypted artifact. The MysqlBackup itself does not carry it: read status.encryption.mode there. | Operator-owned read-only |
bloodraven.shipstream.io/mysqlbackup-verification (label) | verification Jobs | operator | the MysqlBackupVerification name. This key names the MysqlBackupVerification a Job belongs to. | Operator-owned read-only |
bloodraven.shipstream.io/verification-schedule (label) | scheduled MysqlBackupVerifications, verification CronJobs | operator (the CronJob and the trigger command it runs) | the backup profile name (a profile has one verification schedule, named after it). This key names the verification schedule that created a MysqlBackupVerification. A verification created by hand or by kubectl bloodraven verify does not carry it. | Public |
bloodraven.shipstream.io/triggered-by (annotation) | MysqlBackup, MysqlBackupVerification | the schedules, the trigger commands, kubectl bloodraven (--triggered-by, default manual), user | free text. The operator's writers use schedule, schedule/<name> and retry/<name>/attempt-<n>; other writers may record anything. This key records what created a MysqlBackup or a MysqlBackupVerification. Informational free text; nothing reads it. | Public |
Backup bookkeeping
| Key | On | Writer | Value and meaning | Stability |
|---|---|---|---|---|
bloodraven.shipstream.io/backup-retry-of (label) | MysqlBackup | operator | the replaced MysqlBackup's name. This key names the MysqlBackup a retry replaces. | Internal (may change) |
bloodraven.shipstream.io/backup-retry-root, bloodraven.shipstream.io/backup-retry-root-uid (annotation) | MysqlBackup | operator | the root MysqlBackup's name; its uid. These keys name the first backup of a retry chain. | Internal (may change) |
bloodraven.shipstream.io/backup-attempt (annotation) | MysqlBackup | operator | an integer. This key is the attempt number within a retry chain. | Internal (may change) |
bloodraven.shipstream.io/cleanup-failure-recorded (annotation) | backup cleanup Jobs | operator | true. This key marks a failed cleanup Job whose failure Event and metric were emitted, so each Job counts once. | Internal (may change) |
bloodraven.shipstream.io/failover-group-uid (annotation) | backup Jobs and their pod template | operator | the group's metadata.uid. This key pins the source group's uid on a backup Job and its pod; status.failoverGroupUID is recovered from it. The same key is bloodraven.shipstream.io/failover-group-uid on key snapshots. | Internal (may change) |
bloodraven.shipstream.io/pitr-archive-id (annotation) | backup Jobs and their pod template | operator | ar1-…, or empty while PITR is off. This key pins the source group's PITR archive ID on a backup Job; status.pitrArchiveID is recovered from it. | Internal (may change) |
bloodraven.shipstream.io/verification-backup (annotation) | verification Job pod templates | operator | {"schemaVersion":1,"name":…,"uid":…,"artifactStorage":{…}}. This key pins the MysqlBackup a verification Job reads. A record with a schemaVersion the operator does not know fails the verification (Verified=False/MetadataVersionUnsupported and a Warning Event). | Internal (may change) |
Holds
A hold keeps an object that a running operation reads. Holds form one family, <kind>-hold.bloodraven.shipstream.io/<id>, so every hold of a kind is found by one prefix match. Removing a hold by hand while its holder runs can delete data under it.
| Key | On | Writer | Value and meaning | Stability |
|---|---|---|---|---|
verification-hold.bloodraven.shipstream.io/<verification uid> (annotation) | MysqlBackup; PITR archive key snapshot Secrets | operator | the verification's name. This key marks a MysqlBackup, and a PITR archive key snapshot, that a MysqlBackupVerification is reading. The full key is the prefix followed by the verification's uid. Retention, the artifact-cleanup finalizer and the PITR binlog cutoff leave the object alone while a hold on it is live, also while the verification is Terminating. | Operator-owned read-only |
PITR archive binding metadata
On archive key snapshots (Secrets) and the Jobs that mount them.
| Key | On | Writer | Value and meaning | Stability |
|---|---|---|---|---|
bloodraven.shipstream.io/pitr-render (annotation) | site Deployments | operator | sorted JSON with schemaVersion 1; unknown keys are refused. This key is the canonical JSON of the PITR identity and access fields a site Deployment renders. | Internal (may change) |
bloodraven.shipstream.io/pitr-destination (annotation) | archive key snapshot Secrets | operator | the normalized destination. This key is the normalized archive destination. | Internal (may change) |
bloodraven.shipstream.io/pitr-accepted (annotation) | archive key snapshot Secrets | operator | JSON with schemaVersion 1. This key is the acceptance record of an accepted archive key snapshot. Never edit it. | Operator-owned read-only |
bloodraven.shipstream.io/pitr-binding-id (label) | archive key snapshot Secrets | operator | pab-<16 hex digits>. This key is the binding id. It is the release selector, so a release also covers snapshots whose binding entry was dropped or lost. | Internal (may change) |
bloodraven.shipstream.io/failover-group-uid (label) | archive key and dump key snapshot Secrets | operator; doctor support-bundle.sh selects on it | the group's metadata.uid. This key is the group's metadata.uid. Snapshots have no owner reference, so it scopes every listing to one group incarnation. Same key as bloodraven.shipstream.io/failover-group-uid. | Internal (may change) |
bloodraven.shipstream.io/mysqlbackup-uid (label) | dump key snapshot Secrets | operator | the MysqlBackup's metadata.uid. This key is the MysqlBackup's uid. | Internal (may change) |
bloodraven.shipstream.io/pitr-key-secret (label) | check, restore, verification and in-place staging Jobs | operator | the snapshot Secret's name. This key is the archive key snapshot a Job mounts. A release is refused while such a Job has not stopped. | Internal (may change) |
bloodraven.shipstream.io/pitr-key-secret-uid (annotation) | archive check Jobs | operator | the snapshot Secret's metadata.uid. This key is the uid of the candidate snapshot a check Job mounts, when the Job was created. A verdict is accepted only for that object. | Internal (may change) |
Deployment API leases
On the coordination.k8s.io Leases the operator creates for deployment leases.
| Key | On | Writer | Value and meaning | Stability |
|---|---|---|---|---|
bloodraven.shipstream.io/deployment-lease (annotation) | deployment Leases | operator | JSON with schemaVersion 1. This key holds the lease record. A record with a schemaVersion the operator does not know is refused: the lease request fails, and the group reports Degraded=True/MetadataVersionUnsupported with a Warning Event. | Internal (may change) |
bloodraven.shipstream.io/deployment-kind (label) | deployment Leases | operator | migration or failover-hold. This key is the lease kind. | Internal (may change) |
bloodraven.shipstream.io/deployment-state (label) | deployment Leases | operator | active, released, expired or revoked. This key is the lease state. | Internal (may change) |
Client labels
The chart's deployment API NetworkPolicy (auxiliary.deployAPI.networkPolicy.enabled) admits a client only when both labels match the same source.
| Key | On | Writer | Value and meaning | Stability |
|---|---|---|---|---|
bloodraven.shipstream.io/mysql-client (label) | Namespace | user; the chart NetworkPolicy selects on it | true. This key marks a namespace whose pods may reach the operator's deployment API. | Public |
bloodraven.shipstream.io/deploy-client (label) | Pod | user; the chart NetworkPolicy selects on it | true. This key marks a pod that may call the deployment API. | Public |
Node taint
| Key | On | Writer | Value and meaning | Stability |
|---|---|---|---|---|
<namespace>.db-readonly.bloodraven.shipstream.io/<group> (taint) | Node | operator; users tolerate it | true, effect NoExecute. The operator puts this taint, with effect NoExecute, on a site's nodes (spec.sites.taintNodeSelector) while the site is read only, so pods that do not tolerate it are evicted; workloads that must keep running there tolerate it. The namespace is part of the key, so two groups of the same name in different namespaces never share a taint. The prefix is at most 100 characters (a 63-character namespace) and the name part is the group name. | Public |