Configuration Reference

The Operator supports the following resource types (known as Kind's):

• KurrentDB
• KurrentDBBackup
• KurrentDBBackupSchedule

KurrentDB

This resource type is used to define a database deployment.

API

KurrentDBSpec

Field	Required	Description
replicas integer	Yes	Number of nodes in a database cluster. May be 1, 3, 5, or, for standalone ReadOnly-Replicas, it may be 0.
image string	Yes	KurrentDB container image URL. See Selecting An Image, below.
resources ResourceRequirements	No	Database container resource limits and requests
storage PersistentVolumeClaim	Yes	Persistent volume claim settings for the underlying data volume
network KurrentDBNetwork	Yes	Defines the network configuration to use with the database
configuration yaml	No	Additional configuration to use with the database, see below
environmentSecret string	No	The name of a Secret to populate environment variables. If the secret changes a rolling restart occurs.
sourceBackup string	No	Backup name to restore a cluster from
security KurrentDBSecurity	No	Security configuration to use for the database. This is optional, if not specified the cluster will be created without security enabled.
licenseSecret SecretKeySelector	No	A secret that contains the Enterprise license for the database
constraints KurrentDBConstraints	No	Scheduling constraints for the Kurrent DB pod.
readOnlyReplicas KurrentDBReadOnlyReplicasSpec	No	Read-only replica configuration for the Kurrent DB Cluster.
archiver KurrentDBArchiverSpec	No	Archiver replica configuration for the Kurrent DB Cluster.
extraMetadata KurrentDBExtraMetadataSpec	No	Additional annotations and labels for child resources.
quorumNodes string array	No	A list of endpoints (in host:port notation) to reach the quorum nodes when .Replicas is zero, see standalone ReadOnlyReplicas
serviceAccountName string	No	A ServiceAccount for pods to run as (defaults to default in the current namespace). Useful for IRSA, see archiver example.
telemetryOptOut boolean	No	Opt-out of telemetry in the KurrentDB cluster.
users KurrentDBUsersSpec	No	Initial user configuration. No deployment should be considered secure without configure initial user passwords.
configReloadKey string	No	Has no effect, except a change to this value triggers a config reload. See Manually Triggering Reload or Restart.
rollingRestartKey string	No	Has no effect, except a change to this value triggers a rolling restart. See Manually Triggering Reload or Restart.
fullRestartKey string	No	Has no effect, except a change to this value triggers a full restart. See Manually Triggering Reload or Restart.

KurrentDBReadOnlyReplicasSpec

Other than replicas, each of the fields in KurrentDBReadOnlyReplicasSpec default to the corresponding values from the main KurrentDBSpec.

Field	Required	Description
replicas integer	No	Number of read-only replicas in the cluster. Defaults to zero.
resources ResourceRequirements	No	Database container resource limits and requests.
storage PersistentVolumeClaim	No	Persistent volume claim settings for the underlying data volume.
configuration yaml	No	Additional configuration to use with the database.
constraints KurrentDBConstraints	No	Scheduling constraints for the Kurrent DB pod.

KurrentDBArchiverSpec

Other than enabled, each of the fields in KurrentDBArchiverSpec default to the corresponding values from the main KurrentDBSpec.

Field	Required	Description
enabled bool	No	If an Archiver node should be added to the cluster. Defaults to False.
resources ResourceRequirements	No	Database container resource limits and requests.
storage PersistentVolumeClaim	No	Persistent volume claim settings for the underlying data volume.
configuration yaml	No	Additional configuration to use with the database.
constraints KurrentDBConstraints	No	Scheduling constraints for the Kurrent DB pod.

KurrentDBConstraints

Field	Required	Description
nodeSelector yaml	No	Identifies nodes that the Kurrent DB may consider during scheduling.
affinity Affinity	No	The node affinity, pod affinity, and pod anti-affinity for scheduling the Kurrent DB pod.
tolerations list of Toleration	No	The tolerations for scheduling the Kurrent DB pod.
topologySpreadConstraints list of TopologySpreadConstraint	No	The topology spread constraints for scheduling the Kurrent DB pod.

KurrentDBExtraMetadataSpec

Field	Required	Description
all ExtraMetadataSpec	No	Extra annotations and labels for all child resource types.
configMaps ExtraMetadataSpec	No	Extra annotations and labels for ConfigMaps.
statefulSets ExtraMetadataSpec	No	Extra annotations and labels for StatefulSets.
pods ExtraMetadataSpec	No	Extra annotations and labels for Pods.
persistentVolumeClaims ExtraMetadataSpec	No	Extra annotations and labels for PersistentVolumeClaims.
headlessServices ExtraMetadataSpec	No	Extra annotations and labels for the per-cluster headless Services.
headlessPodServices ExtraMetadataSpec	No	Extra annotations and labels for the per-pod headless Services.
loadBalancers ExtraMetadataSpec	No	Extra annotations and labels for LoadBalancer-type Services.

Note that select kinds of extra metadata support template expansion to allow multiple instances of a child resource to be distinguished from one another. In particular, ConfigMaps, StatefulSets, and HeadlessServices support "per-node-kind" template expansions:

• {name} expands to KurrentDB.metadata.name
• {namespace} expands to KurretnDB.metadata.namespace
• {domain} expands to the KurrnetDBNetwork.domain
• {nodeTypeSuffix} expands to "" for a quorum node, "-replica" for a read-only replica node, or "-archiver" for an archiver node.

Additionally, HeadlessPodServices and LoadBalancers support "per-pod" template expansions:

• {name} expands to KurrentDB.metadata.name
• {namespace} expands to KurretnDB.metadata.namespace
• {domain} expands to the KurrnetDBNetwork.domain
• {nodeTypeSuffix} expands to "" for a quorum node, "-replica" for a read-only replica node, or "-archiver" for an archiver node.
• {podName} expands to the name of the pod corresponding to the resource
• {podOrdinal} the ordinal assigned to the pod corresponding to the resource

Notably, Pods and PersistentVolumeClaims do not support any template expansions, due to how StatefulSets work.

ExtraMetadataSpec

Field	Required	Description
labels object	No	Extra labels for a resource.
annotations object	No	Extra annotations for a resource.

KurrentDBNetwork

Field	Required	Description
domain string	Yes	Domain used for external DNS e.g. advertised address exposed in the gossip state
loadBalancer KurrentDBLoadBalancer	Yes	Defines a load balancer to use with the database
fqdnTemplate string	No	The template string used to define the external advertised address of a node. See below.
internodeTrafficStrategy string	No	How servers dial each other. One of "ServiceName" (default), "FQDN", or "SplitDNS". See details.
clientTrafficStrategy string	No	How clients dial servers. One of "ServiceName" or "FQDN" (default). See details.
splitDNSExtraRules list of DNSRule	No	Advanced configuration for when internodeTrafficStrategy is set to "SplitDNS".
nodePort integer	No	The HTTP port that KurrentDB listens on. Defaults to 2113. For priviliged ports, see below.
replicationPort integer	No	The TCP port for replication traffic from other nodes. Defaults to 1112. For priviliged ports, see below.
nodeTcpPort integer	No	The TCP port for legacy TCP client traffic. Defaults to 1113. For priviliged ports, see below.

Note that fqdnTemplate supports the following expansions:

• {name} expands to KurrentDB.metadata.name
• {namespace} expands to KurretnDB.metadata.namespace
• {domain} expands to the KurrnetDBNetwork.domain
• {nodeTypeSuffix} expands to "" for a quorum node, "-replica" for a read-only replica node, or "-archiver" for an archiver node.
• {podName} expands to the name of the pod

When fqdnTemplate is empty, it defaults to {podName}.{name}{nodeTypeSuffix}.{domain}.

The ports for nodePort, replicationPort, and nodeTcpPort may be chosen arbitrarily, but note that the Operator always runs nodes as non-root. Therefore, to utilize priviliged ports (port numbers less than 1024), you will need to use images with setcap cap_net_bind_service+ep applied to the kurrentd binary inside the image. Kurrent offers Red Hat-certified images which meet this criteria, see Selecting An Image, below.

DNSRule

Field	Required	Description
host string	Yes	A host name that should be intercepted.
result string	Yes	An IP address to return, or another hostname to look up for the final IP address.
regex boolean	No	Whether host and result should be treated as regex patterns. Defaults to false.

Note that when regex is true, the regex support is provided by the go standard regex library, and referencing captured groups differs from some other regex implementations. For example, to redirect lookups matching the pattern

    <podname>.my-db.my-namespace.svc.cluster.local

to

    <podname>.my-domain.com

you could use the following dns rule:

host: ([a-z0-9-]*)\.my-db\.my-namespace\.svc\.cluster\.local
result: ${1}.my-domain.com
regex: true

KurrentDBLoadBalancer

Field	Required	Description
enabled boolean	Yes	Determines if a load balancer should be deployed for each node
allowedIps string array	No	List of IP ranges allowed by the load balancer (default will allow all access)
loadBalancerClass string	No	The Service.spec.loadBalancerClass to use. Defaults to empty.

Note that changing the loadBalancerClass will require deleting the old load balancer Service completely and recreating it (which make take a while) because loadBalancerClass is an immutable field of a Service.

KurrentDBSecurity

Field	Required	Description
certificateReservedNodeCommonName string	No	Common name for the TLS certificate (this maps directly to the database property CertificateReservedNodeCommonName)
certificateAuthoritySecret CertificateSecret	No	Secret containing the CA TLS certificate. Updates trigger a config reload. Only .name is required; See below.
certificateSecret CertificateSecret	Yes	Secret containing the TLS certificate to use. Updates trigger a config reload.
certificateSubjectName string	No	Deprecated field. The value of this field is always ignored.

Note that in certificateAuthoritySecret, only .name is required. .keyName is optional; if provided only that Secret key will be mounted into the pod as a CA. If not provided, all Secret keys will be mounted as CAs, which allows for rotating CAs without downtime, by trusting both old and new CAs for a period of time. .privateKeyName is deprecated and ignored.

CertificateSecret

Field	Required	Description
name string	Yes	Name of the secret holding the certificate details
keyName string	Yes	Key within the secret containing the TLS certificate
privateKeyName string	No	Key within the secret containing the TLS certificate private key

KurrentDBUsersSpec

Field	Required	Description
adminPasswordSecret SecretKeySelector	Yes	Secret containing initial password for admin user.
opsPasswordSecret SecretKeySelector	Yes	Secret containing initial password for ops user.
customUsers KurrentDBUserSpec array	No	Custom users to add to the database.

The admin and ops passwords are required if users are configured at all. Those paswords are set by initial database creation; when set, the database will never accept the default password (changeit). No deployment should be considered secure without configuring these two passwords.

The additioanl users described in customUsers are optional, and are configured by the Operator after the first successful health check.

The Operator does not currently support updates to the intial user configuration. The Secrets referenced here are not read after the first time the KurrentDB cluster reaches a healhty state, and may safely be deleted.

KurrentDBUserSpec

Field	Required	Description
loginName string	Yes	The login name of the user.
fullName string	Yes	The display name of the user.
passwordSecret SecretKeySelector	Yes	The Secret from which the password should be read.
groups string array	No	Additional groups to add user to, see below.

Note that KurrentDB always adds every new user to a group matching its login name, so the groups listed in .groups are in addition to that default behavior.

The Operator does not currently support updates to the intial user configuration. The Secrets referenced here are not read after the first time the KurrentDB cluster reaches a healhty state, and may safely be deleted.

KurrentDBBackup

This resource type is used to define a backup for an existing database deployment.

Important

Resources of this type must be created within the same namespace as the target database cluster to backup.

API

KurrentDBBackupSpec

Field	Required	Description
clusterName string	Yes	Name of the source database cluster
nodeName string	No	Specific node name within the database cluster to use as the backup. If unspecified, the leader is used.
volumeSnapshotClassName string	Yes	The name of the underlying volume snapshot class to use.
extraMetadata KurrentDBBackupExtraMetadataSpec	No	Additional annotations and labels for child resources.
ttl string	No	A time-to-live for this backup. If unspecified, the TTL is treated as infinite.

The format of the ttl may be in years (y), weeks (w), days (d), hours (h), or seconds (s), or a combination like 1d12h

KurrentDBBackupExtraMetadataSpec

Field	Required	Description
All ExtraMetadataSpec	No	Extra annotations and labels for all child resource types (currently only VolumeSnapshots).
VolumeSnapshots ExtraMetadataSpec	No	Extra annotations and labels for VolumeSnapshots.

KurrentDBBackupSchedule

This resource type is used to define a schedule for creating database backups and retention policies.

KurrentDBBackupScheduleSpec

Field	Required	Description
schedule string	Yes	A CronJob-style schedule. See Writing a CronJob Spec.
timeZone string	No	A timezone specification. Defaults to Etc/UTC.
template KurrentDBBackup	Yes	A KurrentDBBackup template.
keep integer	No	The maximum of complete backups this schedule will accumulate before it prunes the oldes ones. If unset, there is no limit.
suspend boolean	No

Note that the only metadata allowed in template.metadata is name, labels, and annotations. If name is provided, it will be extended with an index like my-name-1 when creating backups, otherwise created backups will be based on the name of the schedule resource.

Selecting an Image

When selecting a KurrentDB image, you may choose from one of Kurrent's standard images:

Versions	Image	Link
23.10.x to 24.10.x	docker.eventstore.com/eventstore/eventstoredb-ee:X.Y.Z	link
25.0.0 and greater	docker.kurrent.io/kurrent-latest/kurrentdb:X.Y.Z	link

Additionally, Kurrent offers Red Hat-certified KurrentDB images. These images have the additional property that they have setcap cap_net_bind_service+ep applied to the kurrentd binary inside the image, which allows them to be used in conjunction with setting .spec.network.nodePort to a privileged port, like 443.

These same images without the Red Hat Certification (or official Red Hat sha256 checks) are available without a Red Hat account directly from Kurrent. This is useful if you want the setcap-enabled image but don't care about the Red Hat Certification.

Versions	Certified	Image	Link
25.0.0 and greater	Yes	registry.connect.redhat.com/kurrent-io/kurrentdb:X.Y.Z	link
25.0.0 and greater	No	docker.kurrent.io/kurrent-latest/kurrentdb-rhel8:X.Y.Z	link

Configuring KurrentDB

The KurrentDB.spec.configuration yaml field may contain any valid configuration values for Kurrent DB. However, some values may be unnecessary, as the Operator provides some defaults, while other values may be ignored, as the Operator may override them.

The Operator-defined default configuration values, which may be overridden by the user's KurrentDB.spec.configuration are:

Default Field	Default Value
DisableLogFile	true
EnableAtomPubOverHTTP	true
Insecure	false
PrepareTimeoutMs	3000
CommitTimeoutMs	3000
GossipIntervalMs	2000
GossipTimeoutMs	5000
LeaderElectionTimeoutMs	2000
ReplicationHeartbeatInterval	1000
ReplicationHeartbeatTimeout	2500
NodeHeartbeatInterval	1000
NodeHeartbeatTimeout	2500

The Operator-managed configuration values, which take precedence over the user's KurrentDB.spec.configuration, are:

Managed Field	Value
Db	hard-coded volume mount point
Index	hard-coded volume mount point
Log	hard-coded volume mount point
Insecure	true if KurrentDB.spec.security.certificateSecret is empty
DiscoverViaDns	false (GossipSeed is used instead)
AllowAnonymousEndpointAccess	true
AllowUnknownOptions	true
NodeIp	0.0.0.0 (to accept traffic from outside pod)
ReplicationIp	0.0.0.0 (to accept traffic from outside pod)
NodeHostAdvertiseAs	Derived from pod name
ReplicationHostAdvertiseAs	Derived from pod name
AdveritseHostToClientAs	Derived from KurrentDB.spec.newtork.fqdnTemplate
ClusterSize	Derived from KurrentDB.spec.replicas
GossipSeed	Derived from pod list
ReadOnlyReplica	Automatically set for ReadOnlyReplica and Archiver pods
NodePort	Derived from KurrentDB.spec.network.nodePort
ReplicationPort	Derived from KurrentDB.spec.network.replicationPort
NodeTcpPort	Derived from KurrentDB.spec.network.nodeTcpPort