EloqDBCluster

Overview

EloqDBCluster represents a physical database instance managed by the Eloq Operator. While users primarily interact with EloqDBClusterClaim, administrators use this resource to monitor and manage the actual deployment of database components, pods, and services. A cluster is automatically generated by the operator to satisfy a Claim, combining the architectural blueprint from a Template with specific resource requirements and storage overrides.

info

Throughout this documentation, we use eloqdb-clusters as the example namespace. Please replace it with your own namespace in actual usage.

Internal Representation

Below is an example of an EloqDBCluster status reflecting a running instance:

apiVersion: eloqdbcluster.eloqdata.com/v1alpha1
kind: EloqDBCluster
metadata:
  name: eloq-dc-4f2a-8b1e
  namespace: eloqdb-clusters
spec:
  # Desired operational state
  state: Attached
  templateRef:
    name: pool-eloqdoc-free
    namespace: eloqdb-clusters
  # Merged S3 storage overrides for data and log state
  overrides:
    txStore:
      eloqStore:
        cloudStorePath: "eloqcloud-us-west-1/my-eloqdoc-cluster-store"
  # Reference back to the originating claim
  claimRef:
    name: my-eloqdoc-cluster
    namespace: eloqdb-clusters

Phase and Conditions

Cluster Phases

The status.phase provides a granular view of the internal deployment and runtime state:

Phase	Description
Preparing	Resolving template references and validating configuration.
Initializing	Creating foundational Kubernetes resources (ConfigMaps, etc.).
Bootstrapping	Initializing the database substrate/log group.
DeployingLog	Deploying the Log Service components.
DeployingTx	Deploying the Transaction Service (database engine).
CreatingUsers	Establishing internal database users and admin credentials.
ExposingService	Creating Kubernetes Services and Load Balancers.
Deployed	Infrastructure is ready, but database engine might be stopped.
Detached	Resources exist, but database processes are suspended.
Attaching	Starting database processes and mounting storage.
Attached	Cluster is running and actively serving traffic.
Detaching	Gracefully stopping database processes.
Scaling	Horizontal or vertical scaling in progress.
ShuttingDown	Terminating pods (scaling to 0 replicas).
Shutdown	All processes stopped with zero running replicas.

Status Conditions

Conditions track the successful completion of critical deployment milestones:

Condition	Description
Prepared	Configuration is valid and all references are resolved.
Initialized	Base infrastructure resources are successfully created.
Bootstrapped	Database storage substrate is ready for use.
LogServiceDeploy	Log Service components are healthy and running.
TxServiceDeploy	Transaction Service (Engine) component is healthy.
UserCreated	Administrative and user credentials have been set up.
DBServiceExpose	Service endpoints and load balancers are active.
Deployed	All automated deployment steps have concluded.
Attached	The database engine is serving client requests.

Detailed Field Reference

Spec Fields

Field	Type	Required	Default	Description
state	string	Yes	-	Desired state: Deployed, Attached, or Detached.
templateRef	TemplateReference	Yes	-	References the EloqDBClusterTemplate for base config.
overrides	OverrideSpec	No	-	Combined storage overrides (usually from Claim).
dbUserSecret	SecretReference	No	-	Reference to the Secret containing user credentials.
claimRef	ClaimReference	No	-	Reference to the EloqDBClusterClaim using this cluster.
poolRef	PoolReference	No	-	Reference to the EloqDBPool this cluster belongs to.

Status Fields

Field	Type	Description
phase	string	The current lifecycle phase (e.g., Preparing, Attached).
conditions	[]Condition	List of standard Kubernetes status conditions.
resolvedConfig	EloqDBClusterTemplateSpec	The final merged configuration currently in use.
observedGeneration	int64	The most recent generation observed by the controller.