| Name | Type | Description | Required |
|---|---|---|---|
| apiVersion | string | questdb.io/v1alpha1 | true |
| kind | string | QuestDBCluster | true |
| metadata | object | Refer to the Kubernetes API documentation for the fields of the `metadata` field. | true |
| spec | object |
spec defines the desired state of QuestDBCluster Validations:
|
true |
| status | object |
status defines the observed state of QuestDBCluster |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| image | string |
image is the QuestDB container image. |
true |
| storage | object |
storage describes the per-instance persistent volume. |
true |
| auth | object |
auth configures authentication. If omitted, the operator generates a
bootstrap admin password into a Secret named <cluster>-admin. |
false |
| backup | object |
backup configures in-database object-store backups. Absent ⇒ no backups.
When set and enabled, schedule must be non-empty. Validations:
|
false |
| bootstrap | object |
bootstrap selects how the genesis primary is initialized. Absent ⇒ fresh primary.
Immutable in presence as well as value: it cannot be added to, or removed from,
an existing cluster (see the spec-level rules). Validations:
|
false |
| config | map[string]string |
config is server.conf passthrough (key=value). Operator-owned keys
(acl.admin.*, http.health.check.authentication.required, replication.role,
cairo.snapshot.instance.id, *.tls.*) are rejected.
The object-store keys are NOT rejected, and setting backup.object.store or
replication.object.store here has no effect: the operator supplies both through
the engine's _FILE mechanism, which takes precedence over server.conf. The
additional backup destinations (backup.object.store.1 … .9) and
cold.storage.object.store are yours to set. |
false |
| imagePullSecrets | []object |
imagePullSecrets references Secrets in the cluster's namespace used to pull
spec.image. The QuestDB Enterprise image is private, and pull access to it is
the entitlement to run it, so this is how a licensed instance is authorized on
a cluster whose nodes have no ambient registry credentials (any AKS cluster, and
any EKS cluster whose node role lacks a cross-account ECR grant).
Mutable: changing it rolls the pods, because a rotated pull secret must reach a
pod that is restarted for an unrelated reason without a stale reference. Validations:
|
false |
| instances | integer |
instances is the total number of nodes (1 primary + the rest replicas).
Requires an enabled spec.backup (which itself requires spec.objectStoreRef)
when > 1, because replicas seed from a backup. Replication itself is gated on
spec.objectStoreRef, not on this count. Format: int32 Default: 1 Minimum: 1 |
false |
| objectStoreRef | object |
objectStoreRef references the QuestDBObjectStore (same namespace) that backs
BOTH backup and replication for this cluster. Backup and replication WAL share
this one store/bucket/provider under per-use roots
(spec.backup.root, spec.replication.root). Immutable: re-pointing a live
cluster's store would diverge replicas from the primary's WAL shipping
(split-brain) and strand backup history; a deliberate migration must be an
explicit gated flow (e.g. born-from-backup into a new cluster), not an
in-place edit. Required when spec.backup is enabled or spec.instances > 1.
It also cannot be REMOVED once set — that would converge a replicated cluster
down to a single unreplicated primary and strand its backups. ADDING one to a
cluster that never had it IS allowed: turning on backup/replication later is a
legitimate day-2 operation that strands nothing (see the spec-level rules). Validations:
|
false |
| protocols | object |
protocols configures the optional client-facing wire protocols. Absent ⇒ the
QWP UDP receiver is off.
The always-on surface is not represented here and is not configurable:
HTTP/REST and the Web Console (9000), PGWire (8812), ILP over TCP (9009), and
the min server's health check and /metrics (9003) are served by every cluster. |
false |
| pvcRetentionPolicy | enum |
pvcRetentionPolicy controls whether a stale replica's PVC is deleted when the
instance is removed on scale-down. Retain (default) keeps the durable data;
Delete reclaims it (a re-scale then born-from-backup re-seeds cleanly). The
primary's PVC is never deleted regardless of this policy. Enum: Retain, Delete Default: Retain |
false |
| replication | object |
replication optionally tunes primary+replica HA, which is active whenever
objectStoreRef is set. instances > 1 requires objectStoreRef and an enabled
scheduled backup, not this block. |
false |
| resources | object |
resources is the compute resource requirements for the QuestDB container.
When a memory request and limit are both set they must be EQUAL: QuestDB
mmaps/off-heaps heavily, so the memory limit must be firm and sized for the
page cache. CPU is intentionally left flexible — a CPU limit is optional
(CFS throttling can hurt tail latency; prefer pinning/dedicated nodes), so
the pod may be Burstable rather than strictly Guaranteed. Validations:
|
false |
| scheduling | object |
scheduling configures placement (nodeSelector/affinity/tolerations/
topologySpread/priorityClass) and the disruption budget for instance Pods. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| size | int or string |
size is the requested volume size (e.g. 100Gi). Expand-only: it may grow
(if the StorageClass allows expansion) but never shrink. Validations:
|
true |
| storageClassName | string |
storageClassName selects the StorageClass for the instance PVC. It is
immutable: changing it would orphan the bound volume. Validations:
|
true |
| Name | Type | Description | Required |
|---|---|---|---|
| adminSecret | object |
adminSecret optionally supplies the bootstrap admin password. If unset, the
operator generates one into <cluster>-admin (key "password"). The selected
key's value is injected via QDB_ACL_ADMIN_PASSWORD_FILE (the native _FILE convention), not written to server.conf. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| key | string |
The key of the secret to select from. Must be a valid secret key. |
true |
| name | string |
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names Default: |
false |
| optional | boolean |
Specify whether the Secret or its key must be defined |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| enabled | boolean |
enabled turns on QuestDB's backup subsystem (backup.enabled). |
false |
| retention | integer |
retention is how many recent backups QuestDB keeps
(backup.cleanup.keep.latest.n). Defaults to QuestDB's default (5) when unset. Format: int32 Minimum: 1 |
false |
| root | string |
root is the prefix within spec.objectStoreRef's bucket/container for backups
(e.g. "backup/"). It may share spec.replication.root or differ — QuestDB keeps
backup sets and replication WAL separate within a shared prefix. Defaults to
"backup/" when omitted. Mutable (changing only the backup sub-prefix is the
same low-risk operation the old mutable backup ref allowed). |
false |
| schedule | string |
schedule is a 5- or 6-field cron expression (backup.schedule.cron). Required
when enabled. |
false |
| stalledAfterSeconds | integer |
stalledAfterSeconds is how long an in-progress backup may show no change in
progressPercent before BackupHealthy becomes False/Stalled. The default is
3600 seconds. 0 disables stall detection. Format: int32 Default: 3600 Minimum: 0 |
false |
| timezone | string |
timezone is the IANA zone for the schedule (backup.schedule.tz). Defaults to
QuestDB's default (UTC) when unset. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| follow | object |
follow makes the cluster a replica-only FOLLOWER of an external QuestDB the
operator does not manage: every instance is a replica, there is no primary, and
the fleet seeds from that source's backup and then follows its WAL stream through
the shared object store. Promote one instance later to take over.
This is the low-downtime migration path onto the operator. spec.bootstrap.recovery
requires stopping the source BEFORE the restore begins, so it loses every write
since the last backup; a follower keeps consuming the source's stream while the
source still serves, and downtime shrinks to "stop the source, drain it, promote".
Mutually exclusive with recovery: both initialize the genesis instances, from the
same store, in incompatible ways. |
false |
| recovery | object |
recovery makes the genesis primary born from a backup (DR / PITR) instead of fresh. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| sourceInstanceName | string |
sourceInstanceName is the external source's backup_instance_name. It pins which
backup in the shared store each replica restores as its baseline, and the operator
cannot discover it — discovering it would mean querying the unmanaged source, which
is exactly what this design does not do.
It must name the same database the WAL under spec.replication.root belongs to. A
mismatch is not rejected here (nothing in the cluster can check it) and presents at
runtime as a follower that restores cleanly and then never advances. |
true |
| Name | Type | Description | Required |
|---|---|---|---|
| source | object |
source references the QuestDBObjectStore holding the backup to restore from. |
true |
| recoveryTarget | object |
recoveryTarget bounds the restore to a point in time. Omitted ⇒ restore the
latest available backup. Restore snaps to the latest backup at-or-before the
timestamp (granularity = the source's backup cadence; not continuous PITR). |
false |
| sourceInstanceName | string |
sourceInstanceName selects which backup instance to restore when the store
holds more than one. Optional when the store has exactly one instance. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| objectStoreRef | object |
objectStoreRef names a QuestDBObjectStore in the cluster's namespace. |
true |
| Name | Type | Description | Required |
|---|---|---|---|
| name | string |
name references a QuestDBObjectStore in the cluster's namespace. |
true |
| root | string |
root is the prefix within the store's bucket/container for THIS use
(e.g. "backup/", "db/"). It is the only isolation when multiple uses or
clusters share a bucket. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| timestamp | string |
timestamp is an RFC3339 instant. Restore selects the latest backup at-or-before it. Format: date-time |
true |
| Name | Type | Description | Required |
|---|---|---|---|
| name | string |
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names Default: |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| name | string |
name references an object in the same namespace as the object holding this
reference. Which kind is determined by the field: see its documentation. |
true |
| Name | Type | Description | Required |
|---|---|---|---|
| qwp | object |
qwp configures the QuestDB Wire Protocol (QWP). |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| udp | object |
udp configures the QWP UDP receiver. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| enabled | boolean |
enabled serves the QWP UDP receiver on port 9007, opened on the Pod and
published on the cluster and -rw Services only while this is true. It is NOT
published on -ro: the protocol is ingest-only, so a datagram aimed at a
replica is discarded, and fire-and-forget means nothing is returned to say so.
Defaults to false, matching the engine. UDP ingestion is fire-and-forget: it
is intended for metrics workloads where occasional message loss is
acceptable, and it neither acknowledges writes nor applies backpressure. Use
the WebSocket transport for reliable ingestion.
The receiver is UNAUTHENTICATED. QWP authenticates on the WebSocket upgrade
request, and UDP has no upgrade, so there is no credential path on this port:
anything that can reach it can write. Restrict it with a NetworkPolicy.
Requires an engine that ships the QWP UDP receiver; QuestDB Enterprise 3.3.4
and later do. Default: false |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| config | map[string]string |
config is replication tuning passthrough (replication.primary.* /
replication.requests.*). Operator-owned keys (replication.role,
replication.object.store, the structured walCleaner keys) are rejected.
replication.object.store stays rejected HERE (unlike in spec.config) because
this block is specifically about replication: silently ignoring a store
re-point written into the replication config would be the most misleading
possible place to ignore it. |
false |
| maxLagTxns | integer |
maxLagTxns optionally imposes a STRICT freshness gate on -ro membership: a
replica more than this many transactions behind drops out. Unset =>
readiness gates on initial-catch-up + not-suspended only. Format: int64 Minimum: 1 |
false |
| root | string |
root is the prefix within spec.objectStoreRef's bucket/container for this
cluster's replication WAL. It may share spec.backup.root or differ — QuestDB
keeps replication WAL and backup sets separate within a shared prefix.
DEFAULT WHEN OMITTED: the identity-scoped prefix "db/{namespace}/{name}/" — NOT
the bare "db/". Do NOT "make the default explicit" by writing root: "db/": that
names a DIFFERENT, shared stream and moves a live cluster's WAL onto it. QuestDB
has no instance-name key in the object store, so the prefix is the only isolation
between clusters that share a bucket. Deriving it from the cluster's own
namespace/name (both immutable on a QuestDBCluster, so the default is stable for
the object's lifetime) makes store-sharing safe by construction: a restore/DR
clone pointed at the source's bucket inherits the source's data_id from the
backup and would otherwise collide with the live source's WAL stream and
crash-loop with ER002 (#74). Clusters chained A→B→C each own a distinct stream
with no lineage tracking.
SET IT ONLY to opt into a SPECIFIC existing stream — that is the declarative way
to adopt/continue another cluster's WAL (a stream take-over), fenced by the
keepalive lease (ER005/ER006).
Immutable in VALUE and in PRESENCE (the presence half is enforced by a
spec-level rule, since a field-level transition rule cannot see the absent
case): re-pointing live WAL shipping would diverge replicas from the primary
(split-brain risk), and adding or clearing it moves the stream off/onto the
identity-scoped default just as destructively. A deliberate migration must be an
explicit gated flow (born-from-backup into a new cluster), not an in-place edit. Validations:
|
false |
| seedFrom | integer |
seedFrom optionally pins the seed source for NEW replicas to an instance
serial. Default (unset): the most-recent completed backup among live
instances. The operator resolves the serial to its backup_instance_name and
persists it, so the pin survives that instance's deletion. Format: int32 Minimum: 1 |
false |
| walCleaner | object |
walCleaner manages the primary's WAL cleaner — the engine job that bounds shared
replication-WAL growth in the object store. It is on by default; these are the
operator-surfaced knobs. Other replication.primary.cleaner.* tuning stays available
via config above. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| backupWindowCount | integer |
backupWindowCount is how many backup windows of WAL history the cleaner retains
(replication.primary.cleaner.backup.window.count). Higher keeps more WAL (a wider
PITR/seed window) at the cost of more storage. Defaults to QuestDB's default when unset. Format: int32 Minimum: 1 |
false |
| enabled | boolean |
enabled toggles the WAL cleaner (replication.primary.cleaner.enabled). Defaults to
true (the engine default). DISABLING IT LETS THE REPLICATION WAL GROW UNBOUNDED in
the object store — set false only if you manage WAL retention externally. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| claims | []object |
Claims lists the names of resources, defined in spec.resourceClaims,
that are used by this container.
This field depends on the
DynamicResourceAllocation feature gate.
This field is immutable. It can only be set for containers. |
false |
| limits | map[string]int or string |
Limits describes the maximum amount of compute resources allowed.
More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ |
false |
| requests | map[string]int or string |
Requests describes the minimum amount of compute resources required.
If Requests is omitted for a container, it defaults to Limits if that is explicitly specified,
otherwise to an implementation-defined value. Requests cannot exceed Limits.
More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| name | string |
Name must match the name of one entry in pod.spec.resourceClaims of
the Pod where this field is used. It makes that resource available
inside a container. |
true |
| request | string |
Request is the name chosen for a request in the referenced claim.
If empty, everything from the claim is made available, otherwise
only the result of this request. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| affinity | object |
affinity sets pod/node (anti-)affinity for instance Pods. When set, it
FULLY REPLACES the operator's default soft anti-affinity (no merge) — the
default per-hostname spreading is NOT retained, so re-add an anti-affinity
term if you still want it. |
false |
| nodeSelector | map[string]string |
nodeSelector constrains instance Pods to nodes with matching labels. |
false |
| podDisruptionBudget | object |
podDisruptionBudget tunes the operator-managed PodDisruptionBudget. |
false |
| priorityClassName | string |
priorityClassName sets the Pod priority class for instance Pods. |
false |
| tolerations | []object |
tolerations allow instance Pods onto tainted nodes. |
false |
| topologySpreadConstraints | []object |
topologySpreadConstraints spread instance Pods across failure domains. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| nodeAffinity | object |
Describes node affinity scheduling rules for the pod. |
false |
| podAffinity | object |
Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). |
false |
| podAntiAffinity | object |
Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| preferredDuringSchedulingIgnoredDuringExecution | []object |
The scheduler will prefer to schedule pods to nodes that satisfy
the affinity expressions specified by this field, but it may choose
a node that violates one or more of the expressions. The node that is
most preferred is the one with the greatest sum of weights, i.e.
for each node that meets all of the scheduling requirements (resource
request, requiredDuringScheduling affinity expressions, etc.),
compute a sum by iterating through the elements of this field and adding
"weight" to the sum if the node matches the corresponding matchExpressions; the
node(s) with the highest sum are the most preferred. |
false |
| requiredDuringSchedulingIgnoredDuringExecution | object |
If the affinity requirements specified by this field are not met at
scheduling time, the pod will not be scheduled onto the node.
If the affinity requirements specified by this field cease to be met
at some point during pod execution (e.g. due to an update), the system
may or may not try to eventually evict the pod from its node. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| preference | object |
A node selector term, associated with the corresponding weight. |
true |
| weight | integer |
Weight associated with matching the corresponding nodeSelectorTerm, in the range 1-100. Format: int32 |
true |
| Name | Type | Description | Required |
|---|---|---|---|
| matchExpressions | []object |
A list of node selector requirements by node's labels. |
false |
| matchFields | []object |
A list of node selector requirements by node's fields. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| key | string |
The label key that the selector applies to. |
true |
| operator | string |
Represents a key's relationship to a set of values.
Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. |
true |
| values | []string |
An array of string values. If the operator is In or NotIn,
the values array must be non-empty. If the operator is Exists or DoesNotExist,
the values array must be empty. If the operator is Gt or Lt, the values
array must have a single element, which will be interpreted as an integer.
This array is replaced during a strategic merge patch. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| key | string |
The label key that the selector applies to. |
true |
| operator | string |
Represents a key's relationship to a set of values.
Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. |
true |
| values | []string |
An array of string values. If the operator is In or NotIn,
the values array must be non-empty. If the operator is Exists or DoesNotExist,
the values array must be empty. If the operator is Gt or Lt, the values
array must have a single element, which will be interpreted as an integer.
This array is replaced during a strategic merge patch. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| nodeSelectorTerms | []object |
Required. A list of node selector terms. The terms are ORed. |
true |
| Name | Type | Description | Required |
|---|---|---|---|
| matchExpressions | []object |
A list of node selector requirements by node's labels. |
false |
| matchFields | []object |
A list of node selector requirements by node's fields. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| key | string |
The label key that the selector applies to. |
true |
| operator | string |
Represents a key's relationship to a set of values.
Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. |
true |
| values | []string |
An array of string values. If the operator is In or NotIn,
the values array must be non-empty. If the operator is Exists or DoesNotExist,
the values array must be empty. If the operator is Gt or Lt, the values
array must have a single element, which will be interpreted as an integer.
This array is replaced during a strategic merge patch. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| key | string |
The label key that the selector applies to. |
true |
| operator | string |
Represents a key's relationship to a set of values.
Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt. |
true |
| values | []string |
An array of string values. If the operator is In or NotIn,
the values array must be non-empty. If the operator is Exists or DoesNotExist,
the values array must be empty. If the operator is Gt or Lt, the values
array must have a single element, which will be interpreted as an integer.
This array is replaced during a strategic merge patch. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| preferredDuringSchedulingIgnoredDuringExecution | []object |
The scheduler will prefer to schedule pods to nodes that satisfy
the affinity expressions specified by this field, but it may choose
a node that violates one or more of the expressions. The node that is
most preferred is the one with the greatest sum of weights, i.e.
for each node that meets all of the scheduling requirements (resource
request, requiredDuringScheduling affinity expressions, etc.),
compute a sum by iterating through the elements of this field and adding
"weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the
node(s) with the highest sum are the most preferred. |
false |
| requiredDuringSchedulingIgnoredDuringExecution | []object |
If the affinity requirements specified by this field are not met at
scheduling time, the pod will not be scheduled onto the node.
If the affinity requirements specified by this field cease to be met
at some point during pod execution (e.g. due to a pod label update), the
system may or may not try to eventually evict the pod from its node.
When there are multiple elements, the lists of nodes corresponding to each
podAffinityTerm are intersected, i.e. all terms must be satisfied. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| podAffinityTerm | object |
Required. A pod affinity term, associated with the corresponding weight. |
true |
| weight | integer |
weight associated with matching the corresponding podAffinityTerm,
in the range 1-100. Format: int32 |
true |
| Name | Type | Description | Required |
|---|---|---|---|
| topologyKey | string |
This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
the labelSelector in the specified namespaces, where co-located is defined as running on a node
whose value of the label with key topologyKey matches that of any node on which any of the
selected pods is running.
Empty topologyKey is not allowed. |
true |
| labelSelector | object |
A label query over a set of resources, in this case pods.
If it's null, this PodAffinityTerm matches with no Pods. |
false |
| matchLabelKeys | []string |
MatchLabelKeys is a set of pod label keys to select which pods will
be taken into consideration. The keys are used to lookup values from the
incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
to select the group of existing pods which pods will be taken into consideration
for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
pod labels will be ignored. The default value is empty.
The same key is forbidden to exist in both matchLabelKeys and labelSelector.
Also, matchLabelKeys cannot be set when labelSelector isn't set. |
false |
| mismatchLabelKeys | []string |
MismatchLabelKeys is a set of pod label keys to select which pods will
be taken into consideration. The keys are used to lookup values from the
incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
to select the group of existing pods which pods will be taken into consideration
for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
pod labels will be ignored. The default value is empty.
The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
Also, mismatchLabelKeys cannot be set when labelSelector isn't set. |
false |
| namespaceSelector | object |
A label query over the set of namespaces that the term applies to.
The term is applied to the union of the namespaces selected by this field
and the ones listed in the namespaces field.
null selector and null or empty namespaces list means "this pod's namespace".
An empty selector ({}) matches all namespaces. |
false |
| namespaces | []string |
namespaces specifies a static list of namespace names that the term applies to.
The term is applied to the union of the namespaces listed in this field
and the ones selected by namespaceSelector.
null or empty namespaces list and null namespaceSelector means "this pod's namespace". |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| matchExpressions | []object |
matchExpressions is a list of label selector requirements. The requirements are ANDed. |
false |
| matchLabels | map[string]string |
matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
map is equivalent to an element of matchExpressions, whose key field is "key", the
operator is "In", and the values array contains only "value". The requirements are ANDed. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| key | string |
key is the label key that the selector applies to. |
true |
| operator | string |
operator represents a key's relationship to a set of values.
Valid operators are In, NotIn, Exists and DoesNotExist. |
true |
| values | []string |
values is an array of string values. If the operator is In or NotIn,
the values array must be non-empty. If the operator is Exists or DoesNotExist,
the values array must be empty. This array is replaced during a strategic
merge patch. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| matchExpressions | []object |
matchExpressions is a list of label selector requirements. The requirements are ANDed. |
false |
| matchLabels | map[string]string |
matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
map is equivalent to an element of matchExpressions, whose key field is "key", the
operator is "In", and the values array contains only "value". The requirements are ANDed. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| key | string |
key is the label key that the selector applies to. |
true |
| operator | string |
operator represents a key's relationship to a set of values.
Valid operators are In, NotIn, Exists and DoesNotExist. |
true |
| values | []string |
values is an array of string values. If the operator is In or NotIn,
the values array must be non-empty. If the operator is Exists or DoesNotExist,
the values array must be empty. This array is replaced during a strategic
merge patch. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| topologyKey | string |
This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
the labelSelector in the specified namespaces, where co-located is defined as running on a node
whose value of the label with key topologyKey matches that of any node on which any of the
selected pods is running.
Empty topologyKey is not allowed. |
true |
| labelSelector | object |
A label query over a set of resources, in this case pods.
If it's null, this PodAffinityTerm matches with no Pods. |
false |
| matchLabelKeys | []string |
MatchLabelKeys is a set of pod label keys to select which pods will
be taken into consideration. The keys are used to lookup values from the
incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
to select the group of existing pods which pods will be taken into consideration
for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
pod labels will be ignored. The default value is empty.
The same key is forbidden to exist in both matchLabelKeys and labelSelector.
Also, matchLabelKeys cannot be set when labelSelector isn't set. |
false |
| mismatchLabelKeys | []string |
MismatchLabelKeys is a set of pod label keys to select which pods will
be taken into consideration. The keys are used to lookup values from the
incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
to select the group of existing pods which pods will be taken into consideration
for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
pod labels will be ignored. The default value is empty.
The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
Also, mismatchLabelKeys cannot be set when labelSelector isn't set. |
false |
| namespaceSelector | object |
A label query over the set of namespaces that the term applies to.
The term is applied to the union of the namespaces selected by this field
and the ones listed in the namespaces field.
null selector and null or empty namespaces list means "this pod's namespace".
An empty selector ({}) matches all namespaces. |
false |
| namespaces | []string |
namespaces specifies a static list of namespace names that the term applies to.
The term is applied to the union of the namespaces listed in this field
and the ones selected by namespaceSelector.
null or empty namespaces list and null namespaceSelector means "this pod's namespace". |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| matchExpressions | []object |
matchExpressions is a list of label selector requirements. The requirements are ANDed. |
false |
| matchLabels | map[string]string |
matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
map is equivalent to an element of matchExpressions, whose key field is "key", the
operator is "In", and the values array contains only "value". The requirements are ANDed. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| key | string |
key is the label key that the selector applies to. |
true |
| operator | string |
operator represents a key's relationship to a set of values.
Valid operators are In, NotIn, Exists and DoesNotExist. |
true |
| values | []string |
values is an array of string values. If the operator is In or NotIn,
the values array must be non-empty. If the operator is Exists or DoesNotExist,
the values array must be empty. This array is replaced during a strategic
merge patch. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| matchExpressions | []object |
matchExpressions is a list of label selector requirements. The requirements are ANDed. |
false |
| matchLabels | map[string]string |
matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
map is equivalent to an element of matchExpressions, whose key field is "key", the
operator is "In", and the values array contains only "value". The requirements are ANDed. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| key | string |
key is the label key that the selector applies to. |
true |
| operator | string |
operator represents a key's relationship to a set of values.
Valid operators are In, NotIn, Exists and DoesNotExist. |
true |
| values | []string |
values is an array of string values. If the operator is In or NotIn,
the values array must be non-empty. If the operator is Exists or DoesNotExist,
the values array must be empty. This array is replaced during a strategic
merge patch. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| preferredDuringSchedulingIgnoredDuringExecution | []object |
The scheduler will prefer to schedule pods to nodes that satisfy
the anti-affinity expressions specified by this field, but it may choose
a node that violates one or more of the expressions. The node that is
most preferred is the one with the greatest sum of weights, i.e.
for each node that meets all of the scheduling requirements (resource
request, requiredDuringScheduling anti-affinity expressions, etc.),
compute a sum by iterating through the elements of this field and subtracting
"weight" from the sum if the node has pods which matches the corresponding podAffinityTerm; the
node(s) with the highest sum are the most preferred. |
false |
| requiredDuringSchedulingIgnoredDuringExecution | []object |
If the anti-affinity requirements specified by this field are not met at
scheduling time, the pod will not be scheduled onto the node.
If the anti-affinity requirements specified by this field cease to be met
at some point during pod execution (e.g. due to a pod label update), the
system may or may not try to eventually evict the pod from its node.
When there are multiple elements, the lists of nodes corresponding to each
podAffinityTerm are intersected, i.e. all terms must be satisfied. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| podAffinityTerm | object |
Required. A pod affinity term, associated with the corresponding weight. |
true |
| weight | integer |
weight associated with matching the corresponding podAffinityTerm,
in the range 1-100. Format: int32 |
true |
| Name | Type | Description | Required |
|---|---|---|---|
| topologyKey | string |
This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
the labelSelector in the specified namespaces, where co-located is defined as running on a node
whose value of the label with key topologyKey matches that of any node on which any of the
selected pods is running.
Empty topologyKey is not allowed. |
true |
| labelSelector | object |
A label query over a set of resources, in this case pods.
If it's null, this PodAffinityTerm matches with no Pods. |
false |
| matchLabelKeys | []string |
MatchLabelKeys is a set of pod label keys to select which pods will
be taken into consideration. The keys are used to lookup values from the
incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
to select the group of existing pods which pods will be taken into consideration
for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
pod labels will be ignored. The default value is empty.
The same key is forbidden to exist in both matchLabelKeys and labelSelector.
Also, matchLabelKeys cannot be set when labelSelector isn't set. |
false |
| mismatchLabelKeys | []string |
MismatchLabelKeys is a set of pod label keys to select which pods will
be taken into consideration. The keys are used to lookup values from the
incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
to select the group of existing pods which pods will be taken into consideration
for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
pod labels will be ignored. The default value is empty.
The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
Also, mismatchLabelKeys cannot be set when labelSelector isn't set. |
false |
| namespaceSelector | object |
A label query over the set of namespaces that the term applies to.
The term is applied to the union of the namespaces selected by this field
and the ones listed in the namespaces field.
null selector and null or empty namespaces list means "this pod's namespace".
An empty selector ({}) matches all namespaces. |
false |
| namespaces | []string |
namespaces specifies a static list of namespace names that the term applies to.
The term is applied to the union of the namespaces listed in this field
and the ones selected by namespaceSelector.
null or empty namespaces list and null namespaceSelector means "this pod's namespace". |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| matchExpressions | []object |
matchExpressions is a list of label selector requirements. The requirements are ANDed. |
false |
| matchLabels | map[string]string |
matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
map is equivalent to an element of matchExpressions, whose key field is "key", the
operator is "In", and the values array contains only "value". The requirements are ANDed. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| key | string |
key is the label key that the selector applies to. |
true |
| operator | string |
operator represents a key's relationship to a set of values.
Valid operators are In, NotIn, Exists and DoesNotExist. |
true |
| values | []string |
values is an array of string values. If the operator is In or NotIn,
the values array must be non-empty. If the operator is Exists or DoesNotExist,
the values array must be empty. This array is replaced during a strategic
merge patch. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| matchExpressions | []object |
matchExpressions is a list of label selector requirements. The requirements are ANDed. |
false |
| matchLabels | map[string]string |
matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
map is equivalent to an element of matchExpressions, whose key field is "key", the
operator is "In", and the values array contains only "value". The requirements are ANDed. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| key | string |
key is the label key that the selector applies to. |
true |
| operator | string |
operator represents a key's relationship to a set of values.
Valid operators are In, NotIn, Exists and DoesNotExist. |
true |
| values | []string |
values is an array of string values. If the operator is In or NotIn,
the values array must be non-empty. If the operator is Exists or DoesNotExist,
the values array must be empty. This array is replaced during a strategic
merge patch. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| topologyKey | string |
This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
the labelSelector in the specified namespaces, where co-located is defined as running on a node
whose value of the label with key topologyKey matches that of any node on which any of the
selected pods is running.
Empty topologyKey is not allowed. |
true |
| labelSelector | object |
A label query over a set of resources, in this case pods.
If it's null, this PodAffinityTerm matches with no Pods. |
false |
| matchLabelKeys | []string |
MatchLabelKeys is a set of pod label keys to select which pods will
be taken into consideration. The keys are used to lookup values from the
incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
to select the group of existing pods which pods will be taken into consideration
for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
pod labels will be ignored. The default value is empty.
The same key is forbidden to exist in both matchLabelKeys and labelSelector.
Also, matchLabelKeys cannot be set when labelSelector isn't set. |
false |
| mismatchLabelKeys | []string |
MismatchLabelKeys is a set of pod label keys to select which pods will
be taken into consideration. The keys are used to lookup values from the
incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
to select the group of existing pods which pods will be taken into consideration
for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
pod labels will be ignored. The default value is empty.
The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
Also, mismatchLabelKeys cannot be set when labelSelector isn't set. |
false |
| namespaceSelector | object |
A label query over the set of namespaces that the term applies to.
The term is applied to the union of the namespaces selected by this field
and the ones listed in the namespaces field.
null selector and null or empty namespaces list means "this pod's namespace".
An empty selector ({}) matches all namespaces. |
false |
| namespaces | []string |
namespaces specifies a static list of namespace names that the term applies to.
The term is applied to the union of the namespaces listed in this field
and the ones selected by namespaceSelector.
null or empty namespaces list and null namespaceSelector means "this pod's namespace". |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| matchExpressions | []object |
matchExpressions is a list of label selector requirements. The requirements are ANDed. |
false |
| matchLabels | map[string]string |
matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
map is equivalent to an element of matchExpressions, whose key field is "key", the
operator is "In", and the values array contains only "value". The requirements are ANDed. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| key | string |
key is the label key that the selector applies to. |
true |
| operator | string |
operator represents a key's relationship to a set of values.
Valid operators are In, NotIn, Exists and DoesNotExist. |
true |
| values | []string |
values is an array of string values. If the operator is In or NotIn,
the values array must be non-empty. If the operator is Exists or DoesNotExist,
the values array must be empty. This array is replaced during a strategic
merge patch. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| matchExpressions | []object |
matchExpressions is a list of label selector requirements. The requirements are ANDed. |
false |
| matchLabels | map[string]string |
matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
map is equivalent to an element of matchExpressions, whose key field is "key", the
operator is "In", and the values array contains only "value". The requirements are ANDed. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| key | string |
key is the label key that the selector applies to. |
true |
| operator | string |
operator represents a key's relationship to a set of values.
Valid operators are In, NotIn, Exists and DoesNotExist. |
true |
| values | []string |
values is an array of string values. If the operator is In or NotIn,
the values array must be non-empty. If the operator is Exists or DoesNotExist,
the values array must be empty. This array is replaced during a strategic
merge patch. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| enabled | boolean |
enabled controls whether the operator maintains a PDB. Defaults to true.
Set false to remove the PDB entirely (e.g. to permit unrestricted node drains). |
false |
| minAvailable | integer |
minAvailable overrides the computed integer minAvailable. When unset:
single instance => 1; replicated => instances-1.
LIMITATION: instance Pods have no controller to reschedule them, so a PDB
that leaves no disruption budget HARD-BLOCKS voluntary evictions (`kubectl
drain` hangs) until a human deletes the Pod or the PDB. This happens whenever
minAvailable >= the number of currently-Ready instances — including the
single-instance default (minAvailable=1 over one Pod). It is intentional
protection for a database, NOT auto-clamped: set a lower minAvailable, scale
out, or disable the PDB if you need drains to proceed unattended. Format: int32 Minimum: 0 |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| effect | string |
Effect indicates the taint effect to match. Empty means match all taint effects.
When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. |
false |
| key | string |
Key is the taint key that the toleration applies to. Empty means match all taint keys.
If the key is empty, operator must be Exists; this combination means to match all values and all keys. |
false |
| operator | string |
Operator represents a key's relationship to the value.
Valid operators are Exists, Equal, Lt, and Gt. Defaults to Equal.
Exists is equivalent to wildcard for value, so that a pod can
tolerate all taints of a particular category.
Lt and Gt perform numeric comparisons (requires feature gate TaintTolerationComparisonOperators). |
false |
| tolerationSeconds | integer |
TolerationSeconds represents the period of time the toleration (which must be
of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default,
it is not set, which means tolerate the taint forever (do not evict). Zero and
negative values will be treated as 0 (evict immediately) by the system. Format: int64 |
false |
| value | string |
Value is the taint value the toleration matches to.
If the operator is Exists, the value should be empty, otherwise just a regular string. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| maxSkew | integer |
MaxSkew describes the degree to which pods may be unevenly distributed.
When `whenUnsatisfiable=DoNotSchedule`, it is the maximum permitted difference
between the number of matching pods in the target topology and the global minimum.
The global minimum is the minimum number of matching pods in an eligible domain
or zero if the number of eligible domains is less than MinDomains.
For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same
labelSelector spread as 2/2/1:
In this case, the global minimum is 1.
| zone1 | zone2 | zone3 |
| P P | P P | P |
- if MaxSkew is 1, incoming pod can only be scheduled to zone3 to become 2/2/2;
scheduling it onto zone1(zone2) would make the ActualSkew(3-1) on zone1(zone2)
violate MaxSkew(1).
- if MaxSkew is 2, incoming pod can be scheduled onto any zone.
When `whenUnsatisfiable=ScheduleAnyway`, it is used to give higher precedence
to topologies that satisfy it.
It's a required field. Default value is 1 and 0 is not allowed. Format: int32 |
true |
| topologyKey | string |
TopologyKey is the key of node labels. Nodes that have a label with this key
and identical values are considered to be in the same topology.
We consider each <key, value> as a "bucket", and try to put balanced number
of pods into each bucket.
We define a domain as a particular instance of a topology.
Also, we define an eligible domain as a domain whose nodes meet the requirements of
nodeAffinityPolicy and nodeTaintsPolicy.
e.g. If TopologyKey is "kubernetes.io/hostname", each Node is a domain of that topology.
And, if TopologyKey is "topology.kubernetes.io/zone", each zone is a domain of that topology.
It's a required field. |
true |
| whenUnsatisfiable | string |
WhenUnsatisfiable indicates how to deal with a pod if it doesn't satisfy
the spread constraint.
- DoNotSchedule (default) tells the scheduler not to schedule it.
- ScheduleAnyway tells the scheduler to schedule the pod in any location,
but giving higher precedence to topologies that would help reduce the
skew.
A constraint is considered "Unsatisfiable" for an incoming pod
if and only if every possible node assignment for that pod would violate
"MaxSkew" on some topology.
For example, in a 3-zone cluster, MaxSkew is set to 1, and pods with the same
labelSelector spread as 3/1/1:
| zone1 | zone2 | zone3 |
| P P P | P | P |
If WhenUnsatisfiable is set to DoNotSchedule, incoming pod can only be scheduled
to zone2(zone3) to become 3/2/1(3/1/2) as ActualSkew(2-1) on zone2(zone3) satisfies
MaxSkew(1). In other words, the cluster can still be imbalanced, but scheduler
won't make it *more* imbalanced.
It's a required field. |
true |
| labelSelector | object |
LabelSelector is used to find matching pods.
Pods that match this label selector are counted to determine the number of pods
in their corresponding topology domain. |
false |
| matchLabelKeys | []string |
MatchLabelKeys is a set of pod label keys to select the pods over which
spreading will be calculated. The keys are used to lookup values from the
incoming pod labels, those key-value labels are ANDed with labelSelector
to select the group of existing pods over which spreading will be calculated
for the incoming pod. The same key is forbidden to exist in both MatchLabelKeys and LabelSelector.
MatchLabelKeys cannot be set when LabelSelector isn't set.
Keys that don't exist in the incoming pod labels will
be ignored. A null or empty list means only match against labelSelector.
This is a beta field and requires the MatchLabelKeysInPodTopologySpread feature gate to be enabled (enabled by default). |
false |
| minDomains | integer |
MinDomains indicates a minimum number of eligible domains.
When the number of eligible domains with matching topology keys is less than minDomains,
Pod Topology Spread treats "global minimum" as 0, and then the calculation of Skew is performed.
And when the number of eligible domains with matching topology keys equals or greater than minDomains,
this value has no effect on scheduling.
As a result, when the number of eligible domains is less than minDomains,
scheduler won't schedule more than maxSkew Pods to those domains.
If value is nil, the constraint behaves as if MinDomains is equal to 1.
Valid values are integers greater than 0.
When value is not nil, WhenUnsatisfiable must be DoNotSchedule.
For example, in a 3-zone cluster, MaxSkew is set to 2, MinDomains is set to 5 and pods with the same
labelSelector spread as 2/2/2:
| zone1 | zone2 | zone3 |
| P P | P P | P P |
The number of domains is less than 5(MinDomains), so "global minimum" is treated as 0.
In this situation, new pod with the same labelSelector cannot be scheduled,
because computed skew will be 3(3 - 0) if new Pod is scheduled to any of the three zones,
it will violate MaxSkew. Format: int32 |
false |
| nodeAffinityPolicy | string |
NodeAffinityPolicy indicates how we will treat Pod's nodeAffinity/nodeSelector
when calculating pod topology spread skew. Options are:
- Honor: only nodes matching nodeAffinity/nodeSelector are included in the calculations.
- Ignore: nodeAffinity/nodeSelector are ignored. All nodes are included in the calculations.
If this value is nil, the behavior is equivalent to the Honor policy. |
false |
| nodeTaintsPolicy | string |
NodeTaintsPolicy indicates how we will treat node taints when calculating
pod topology spread skew. Options are:
- Honor: nodes without taints, along with tainted nodes for which the incoming pod
has a toleration, are included.
- Ignore: node taints are ignored. All nodes are included.
If this value is nil, the behavior is equivalent to the Ignore policy. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| matchExpressions | []object |
matchExpressions is a list of label selector requirements. The requirements are ANDed. |
false |
| matchLabels | map[string]string |
matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
map is equivalent to an element of matchExpressions, whose key field is "key", the
operator is "In", and the values array contains only "value". The requirements are ANDed. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| key | string |
key is the label key that the selector applies to. |
true |
| operator | string |
operator represents a key's relationship to a set of values.
Valid operators are In, NotIn, Exists and DoesNotExist. |
true |
| values | []string |
values is an array of string values. If the operator is In or NotIn,
the values array must be non-empty. If the operator is Exists or DoesNotExist,
the values array must be empty. This array is replaced during a strategic
merge patch. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| adminSecretName | string |
adminSecretName is the Secret holding the bootstrap admin password in effect
(operator-generated <cluster>-admin, or the user-supplied auth.adminSecret). |
false |
| backup | object |
backup reports observed backup configuration + the latest run. |
false |
| conditions | []object |
conditions represent the current state of the QuestDBCluster.
Types: Available, Progressing, InstanceUnreachable, ConfigRejected,
OperatorIdentityReady, BackupHealthy, WriteHealthy, ReplicationHealthy,
PromotionRequired, Recovered, RecoveryFailed, StorageResizeBlocked. |
false |
| currentPrimary | string |
currentPrimary is the instance name of the current primary (e.g. prod-1). |
false |
| instances | integer |
instances is the number of instances the operator is currently managing. Format: int32 |
false |
| latestSerial | integer |
latestSerial is the highest instance serial ever allocated. Serials are
1-based and monotonic; a zero/absent value means no instance has ever been
minted (the reconciler allocates serial 1 from that state). It is never
reused and does NOT increment when a pod is recreated for the same identity. Format: int32 |
false |
| observedGeneration | integer |
observedGeneration is the most recent generation observed by the controller.
When it equals .metadata.generation, the reported status reflects the
current spec. Format: int64 |
false |
| operatorSecretName | string |
operatorSecretName is the Secret holding the questdb_operator service-account
password (<cluster>-operator). |
false |
| phase | string |
phase is a short, human-facing lifecycle summary surfaced as a printer
column. Use conditions for machine-readable state; phase is not load-bearing
for control flow. |
false |
| readyInstances | integer |
readyInstances is the number of instances whose pod reports Ready. Format: int32 |
false |
| recovery | object |
recovery reports genesis-primary restore state (nil unless spec.bootstrap.recovery set). |
false |
| replication | object |
replication reports observed replication state (nil when spec.objectStoreRef is unset). |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| configured | boolean |
configured is true once the operator has injected backup config into the pod. |
false |
| lastBackup | object |
lastBackup is the most recent run observed via backups() (nil until one runs). |
false |
| lastProgressAt | string |
lastProgressAt is when the operator first observed the current in-progress
backup or most recently observed its progressPercent change. Format: date-time |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| endTime | string |
Format: date-time |
false |
| error | string |
|
false |
| progressPercent | integer |
Format: int32 |
false |
| startTime | string |
Format: date-time |
false |
| status | string |
status is in_progress|completed|failed|unknown. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| lastTransitionTime | string |
lastTransitionTime is the last time the condition transitioned from one status to another.
This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. Format: date-time |
true |
| message | string |
message is a human readable message indicating details about the transition.
This may be an empty string. |
true |
| reason | string |
reason contains a programmatic identifier indicating the reason for the condition's last transition.
Producers of specific condition types may define expected values and meanings for this field,
and whether the values are considered a guaranteed API.
The value should be a CamelCase string.
This field may not be empty. |
true |
| status | enum |
status of the condition, one of True, False, Unknown. Enum: True, False, Unknown |
true |
| type | string |
type of condition in CamelCase or in foo.example.com/CamelCase. |
true |
| observedGeneration | integer |
observedGeneration represents the .metadata.generation that the condition was set based upon.
For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
with respect to the current state of the instance. Format: int64 Minimum: 0 |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| sourceInstanceName | string |
|
false |
| Name | Type | Description | Required |
|---|---|---|---|
| activePromotion | string |
activePromotion names the QuestDBPromotion currently being serviced for this
cluster, or is absent when no cutover is in flight. |
false |
| following | boolean |
following is true while the cluster is a replica-only follower of the external
QuestDB named by spec.bootstrap.follow. Such a cluster has no primary and accepts
no writes. It becomes false after an instance is promoted. |
false |
| maxLagTxns | integer |
maxLagTxns is the worst observed end-to-end lag across replicas and tables. Zero
means all observed replicas are caught up; absent means lag is undetermined. Format: int64 |
false |
| primaryEstablished | boolean |
primaryEstablished is true once the primary has been Ready at least once. When
true, primary-PVC-loss protection is active and the operator will not initialize
an empty replacement primary if that PVC is missing. |
false |
| replicas | []object |
replicas reports per-replica observed state. |
false |
| seed | object |
seed is the effective seed for the next replica bootstrap: the durable,
monotonically advanced last-known-good pointer (source=auto) or the resolved
pinned source (source=pinned). |
false |
| stream | object |
stream reports the observed follower and source WAL progress over time. |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| caughtUp | boolean |
caughtUp is a sticky indication that the replica completed its initial catch-up at
least once and became eligible for the read-only Service. It does not report current
freshness; use caughtUpNow for that. |
true |
| instance | string |
instance is the replica's instance/pod name. |
true |
| caughtUpNow | boolean |
caughtUpNow reports current observed freshness: true means the replica was reachable,
had no suspended tables, and was either at zero end-to-end lag or bounded-streaming
(applied everything the primary committed a short window ago, so its remaining lag
is at most one window of writes); false means it was behind or stale; absent means
freshness was undetermined.
On a primaryless (follower) cluster the bounded-streaming reading is not available —
there is no primary to reference — so this field carries the stricter zero-lag
meaning there. |
false |
| lagTxns | integer |
lagTxns is the replica's observed end-to-end transaction lag behind the primary.
A non-zero value does not by itself mean the replica is not caught up (see
caughtUpNow); absent means lag was undetermined. Format: int64 |
false |
| suspendedTables | []string |
suspendedTables lists tables whose replication is suspended (unhealthy). |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| backupInstanceName | string |
backupInstanceName is QuestDB's 3-word backup identity for that set,
written into a replica's _backup_restore trigger. |
true |
| serial | integer |
serial is the instance serial whose backup set seeds new replicas. Format: int32 |
true |
| source | enum |
source is how the seed was chosen: "auto" (most-recent-live) or "pinned"
(spec.replication.seedFrom). Enum: auto, pinned |
true |
| timestamp | string |
timestamp is the completion time of the backup this seed points at. Format: date-time |
true |
| Name | Type | Description | Required |
|---|---|---|---|
| advancedAt | string |
advancedAt is when writtenTxn last increased, or when observation began if no
increase has been observed. Format: date-time |
false |
| receivedAdvancedAt | string |
receivedAdvancedAt is when receivedTxn last increased, or when observation began
if no increase has been observed. A quiet value does not prove the source process
has stopped. Format: date-time |
false |
| receivedTxn | integer |
receivedTxn is the highest source transaction observed in sampled replication
indexes. It reports source publication progress and never decreases. Format: int64 |
false |
| writtenTxn | integer |
writtenTxn is the highest transaction observed as applied locally across sampled
tables and follower instances. It never decreases. Format: int64 |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| apiVersion | string | questdb.io/v1alpha1 | true |
| kind | string | QuestDBObjectStore | true |
| metadata | object | Refer to the Kubernetes API documentation for the fields of the `metadata` field. | true |
| spec | object |
spec defines the desired state of QuestDBObjectStore Validations:
|
true |
| status | object |
status defines the observed state of QuestDBObjectStore |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| provider | enum |
provider selects the backend. It is immutable: changing the backend of a
live store would orphan every object (data + backups) written under the old
backend while consumers silently re-point to an empty new one. Validations:
|
true |
| azure | object |
azure configures an Azure Blob store. Set iff provider is Azure. Validations:
|
false |
| gcs | object |
gcs configures a Google Cloud Storage store. Set iff provider is GCS. Validations:
|
false |
| s3 | object |
s3 configures an AWS S3 (or S3-compatible) store. Set iff provider is S3. Validations:
|
false |
| Name | Type | Description | Required |
|---|---|---|---|
| accountName | string |
accountName is the storage account name used to construct the default Azure
Blob endpoint and provider configuration. |
true |
| container | string |
container is the blob container name. |
true |
| credentialsSecret | object |
credentialsSecret holds static credentials. The operator never configures a
ServiceAccount, pod identity label, or provider identity; omit this field only
when the QuestDB pod already has provider-supported ambient identity. The
beta-supported wiring is EKS IRSA through the tenant default ServiceAccount;
the AKS guide uses AZURE_STORAGE_KEY. Expected Secret keys: S3 —
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, optional AWS_SESSION_TOKEN; Azure —
AZURE_STORAGE_KEY; GCS — GOOGLE_APPLICATION_CREDENTIALS_JSON. |
false |
| endpoint | string |
endpoint overrides the default endpoint (MinIO / Azurite / fake-gcs).
For Azure, when omitted the operator derives
https://<accountName>.blob.core.windows.net. |
false |
| extraOptions | map[string]string |
extraOptions are appended verbatim as OpenDAL key=value pairs (e.g.
ca_builtin_roots). Keys must not contain ';' or '='; values must not
contain ';'. Validations:
|
false |
| root | string |
root is a path prefix within the bucket/container. NOTE: on a QuestDBObjectStore
this field does NOT isolate data — the effective prefix is the consuming cluster's
per-use root (spec.backup.root / spec.replication.root), which overrides it. Those
per-use roots are what isolate clusters that share a bucket (QuestDB has no
instance-name key). |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| name | string |
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names Default: |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| bucket | string |
bucket is the GCS bucket name. |
true |
| credentialsSecret | object |
credentialsSecret holds static credentials. The operator never configures a
ServiceAccount, pod identity label, or provider identity; omit this field only
when the QuestDB pod already has provider-supported ambient identity. The
beta-supported wiring is EKS IRSA through the tenant default ServiceAccount;
the AKS guide uses AZURE_STORAGE_KEY. Expected Secret keys: S3 —
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, optional AWS_SESSION_TOKEN; Azure —
AZURE_STORAGE_KEY; GCS — GOOGLE_APPLICATION_CREDENTIALS_JSON. |
false |
| endpoint | string |
endpoint overrides the default endpoint (MinIO / Azurite / fake-gcs).
For Azure, when omitted the operator derives
https://<accountName>.blob.core.windows.net. |
false |
| extraOptions | map[string]string |
extraOptions are appended verbatim as OpenDAL key=value pairs (e.g.
ca_builtin_roots). Keys must not contain ';' or '='; values must not
contain ';'. Validations:
|
false |
| root | string |
root is a path prefix within the bucket/container. NOTE: on a QuestDBObjectStore
this field does NOT isolate data — the effective prefix is the consuming cluster's
per-use root (spec.backup.root / spec.replication.root), which overrides it. Those
per-use roots are what isolate clusters that share a bucket (QuestDB has no
instance-name key). |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| name | string |
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names Default: |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| bucket | string |
bucket is the S3 bucket name. |
true |
| credentialsSecret | object |
credentialsSecret holds static credentials. The operator never configures a
ServiceAccount, pod identity label, or provider identity; omit this field only
when the QuestDB pod already has provider-supported ambient identity. The
beta-supported wiring is EKS IRSA through the tenant default ServiceAccount;
the AKS guide uses AZURE_STORAGE_KEY. Expected Secret keys: S3 —
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, optional AWS_SESSION_TOKEN; Azure —
AZURE_STORAGE_KEY; GCS — GOOGLE_APPLICATION_CREDENTIALS_JSON. |
false |
| endpoint | string |
endpoint overrides the default endpoint (MinIO / Azurite / fake-gcs).
For Azure, when omitted the operator derives
https://<accountName>.blob.core.windows.net. |
false |
| extraOptions | map[string]string |
extraOptions are appended verbatim as OpenDAL key=value pairs (e.g.
ca_builtin_roots). Keys must not contain ';' or '='; values must not
contain ';'. Validations:
|
false |
| region | string |
region is the bucket region. |
false |
| root | string |
root is a path prefix within the bucket/container. NOTE: on a QuestDBObjectStore
this field does NOT isolate data — the effective prefix is the consuming cluster's
per-use root (spec.backup.root / spec.replication.root), which overrides it. Those
per-use roots are what isolate clusters that share a bucket (QuestDB has no
instance-name key). |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| name | string |
Name of the referent.
This field is effectively required, but due to backwards compatibility is
allowed to be empty. Instances of this type with an empty value here are
almost certainly wrong.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names Default: |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| observedGeneration | integer |
observedGeneration is the most recent .metadata.generation observed. Format: int64 |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| apiVersion | string | questdb.io/v1alpha1 | true |
| kind | string | QuestDBPromotion | true |
| metadata | object | Refer to the Kubernetes API documentation for the fields of the `metadata` field. | true |
| spec | object |
spec defines the desired state of QuestDBPromotion |
true |
| status | object |
status defines the observed state of QuestDBPromotion |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| clusterRef | object |
clusterRef names the QuestDBCluster to cut over, in this object's namespace. It is
immutable: re-pointing a live cutover at a different cluster is never a coherent
request. Validations:
|
true |
| target | integer |
target is the instance serial that should become the primary. Immutable, so an
escalation to mode: Emergency is structurally against the same cutover and cannot
silently substitute a different node. Validations:
Minimum: 1 |
true |
| catchUpTimeoutSeconds | integer |
catchUpTimeoutSeconds is how long a Planned cutover waits for the target replica to
catch up before failing. Nothing is shaped while it waits — the old primary is still
primary and still serving writes — so a timeout here leaves the cluster exactly as it
was and costs only the cutover. Raise it for a replica with a large lag to work
through. It is measured from the start of the cutover, so time spent waiting on a
non-drainable primary counts against it. 0 means wait indefinitely. Ignored when mode
is Emergency, which never waits. The post-drain wait for the target to confirm it
applied the drained tail is downtime, so it is bounded by primaryGracePeriodSeconds
instead — see there. Format: int32 Default: 900 Minimum: 0 |
false |
| mode | enum |
mode selects the cutover strategy. The operator never chooses between a lossless
cutover and a lossy one on your behalf — that choice is always yours.
Planned (the default) drains the old primary before promoting the target, so every
committed write reaches the new primary. If the old primary cannot be drained — its
data PVC is lost, or it is stranded on an unreachable node — the promotion FAILS and
nothing is promoted. It never falls back to Emergency.
Emergency skips the drain: it fences the old primary and promotes the target
immediately. Writes the old primary had not yet replicated are LOST. Use it when the
primary is dead, or alive but wedged and you accept the loss.
It is the one field editable on a running cutover, and only in one direction:
Planned may be escalated to Emergency, never the reverse, because a fence cannot be
undone. Validations:
Default: Planned |
false |
| primaryGracePeriodSeconds | integer |
primaryGracePeriodSeconds is how long a Planned cutover tolerates an old primary it
cannot drain before failing. It covers both the start of the cutover and a primary
lost mid-drain, and it exists so a brief node blip does not fail an otherwise
healthy cutover.
It also bounds the wait AFTER a successful drain, while the target confirms it has
applied what that drain uploaded (measured from status.drainCompletedAt; reason
TargetNotReplayed). The rule is the cost, not the phase: while the cluster is not
serving writes, this field is the limit; while it is still serving, it is
catchUpTimeoutSeconds.
This wait IS downtime: the primary is gone, so the cluster is not serving writes for
its duration, and reaching it fails this cutover for good (reason PrimaryNotDrainable,
or PrimaryLostDuringDrain if the primary was lost part-way through). A promotion is
one-shot: there is nothing to re-request on a terminal object, so accepting the loss
means creating a NEW QuestDBPromotion with mode: Emergency. Keep it short. 0 means wait
indefinitely, which trades a bounded outage for an unbounded one. Ignored when mode is
Emergency, which never waits. Format: int32 Default: 120 Minimum: 0 |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| name | string |
name references an object in the same namespace as the object holding this
reference. Which kind is determined by the field: see its documentation. |
true |
| Name | Type | Description | Required |
|---|---|---|---|
| completedAt | string |
completedAt is when this cutover reached a terminal phase. Format: date-time |
false |
| conditions | []object |
conditions carries Succeeded: Unknown while running, True on Completed, False on
Failed. |
false |
| drainCompletedAt | string |
drainCompletedAt is when the old primary's drain was first observed to finish — its
primary-catchup-uploads container exiting 0, which is the moment the object store
became final for this cutover. Nil until then, and while a Planned cutover shows a
Draining phase with this set, it is waiting for the TARGET to confirm it has applied
what that drain uploaded. primaryGracePeriodSeconds bounds that wait, measured from
here. Format: date-time |
false |
| message | string |
message is a human-readable explanation naming what happened, what state the cluster
is in, and what to do next. |
false |
| mode | string |
mode is the strategy this cutover RAN (Planned|Emergency): decided once at entry
from spec.mode and never escalated on the operator's own initiative. It only ever
differs from the request if you explicitly escalated to mode: Emergency while the
drain was still running. |
false |
| phase | enum |
phase is the saga phase. Completed and Failed are terminal. Enum: Pending, Validating, Draining, Promoting, Completed, Failed |
false |
| reason | string |
reason is a machine-readable outcome code (CamelCase), set on a terminal phase. |
false |
| startedAt | string |
startedAt is when this cutover left Pending. It is the clock catchUpTimeoutSeconds
is measured against. Format: date-time |
false |
| undrainableSince | string |
undrainableSince is when the old primary most recently became non-drainable, or nil
while it is drainable. It is cleared the moment the primary becomes drainable again,
so a blip that recovers resets the grace clock rather than consuming it. Format: date-time |
false |
| Name | Type | Description | Required |
|---|---|---|---|
| lastTransitionTime | string |
lastTransitionTime is the last time the condition transitioned from one status to another.
This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. Format: date-time |
true |
| message | string |
message is a human readable message indicating details about the transition.
This may be an empty string. |
true |
| reason | string |
reason contains a programmatic identifier indicating the reason for the condition's last transition.
Producers of specific condition types may define expected values and meanings for this field,
and whether the values are considered a guaranteed API.
The value should be a CamelCase string.
This field may not be empty. |
true |
| status | enum |
status of the condition, one of True, False, Unknown. Enum: True, False, Unknown |
true |
| type | string |
type of condition in CamelCase or in foo.example.com/CamelCase. |
true |
| observedGeneration | integer |
observedGeneration represents the .metadata.generation that the condition was set based upon.
For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
with respect to the current state of the instance. Format: int64 Minimum: 0 |
false |