AerospikeCluster API Reference

This page documents the AerospikeCluster Custom Resource Definition (CRD) types.

API Group: acko.io API Version: v1alpha1 Kind: AerospikeCluster Short Names: asc

AerospikeCluster

AerospikeCluster is the Schema for the aerospikeclusters API. It manages the lifecycle of an Aerospike Community Edition cluster.

Field	Type	Description
`apiVersion`	string	`acko.io/v1alpha1`
`kind`	string	`AerospikeCluster`
`metadata`	ObjectMeta	Standard object metadata
`spec`	AerospikeClusterSpec	Desired state of the cluster
`status`	AerospikeClusterStatus	Observed state of the cluster

AerospikeClusterSpec

Defines the desired state of an Aerospike CE cluster.

Field	Type	Required	Default	Description
`size`	int32	Yes	—	Number of Aerospike pods. CE max: 8.
`image`	string	Yes	—	Aerospike CE container image (e.g., `aerospike:ce-8.1.1.1`).
`aerospikeConfig`	AerospikeConfigSpec	No	—	Raw Aerospike configuration map, converted to `aerospike.conf`.
`storage`	AerospikeStorageSpec	No	—	Volume definitions for Aerospike pods.
`rackConfig`	RackConfig	No	—	Rack-aware deployment topology.
`aerospikeNetworkPolicy`	AerospikeNetworkPolicy	No	—	Client access network configuration.
`podSpec`	AerospikePodSpec	No	—	Pod-level configuration.
`aerospikeAccessControl`	AerospikeAccessControlSpec	No	—	ACL roles and users.
`monitoring`	AerospikeMonitoringSpec	No	—	Prometheus monitoring configuration.
`networkPolicyConfig`	NetworkPolicyConfig	No	—	Automatic NetworkPolicy creation.
`bandwidthConfig`	BandwidthConfig	No	—	CNI bandwidth annotations.
`enableDynamicConfigUpdate`	*bool	No	—	Enable runtime config changes via `set-config`.
`rollingUpdateBatchSize`	*int32	No	`1`	Number of pods to restart in parallel during rolling update.
`disablePDB`	*bool	No	`false`	Disable PodDisruptionBudget creation.
`maxUnavailable`	IntOrString	No	`1`	Max pods unavailable during disruption.
`paused`	*bool	No	`false`	Stop reconciliation when true.
`seedsFinderServices`	SeedsFinderServices	No	—	LoadBalancer service for seed discovery.
`k8sNodeBlockList`	[]string	No	—	Node names to exclude from scheduling.
`operations`	[]OperationSpec	No	—	On-demand operations (WarmRestart, PodRestart). Max 1 at a time.
`validationPolicy`	ValidationPolicySpec	No	—	Controls webhook validation behavior.
`headlessService`	AerospikeServiceSpec	No	—	Custom metadata for the headless service.
`podService`	AerospikeServiceSpec	No	—	Custom metadata for per-pod services. Creates individual Service per pod when set.
`enableRackIDOverride`	*bool	No	`false`	Enable dynamic rack ID assignment via pod annotations.
`templateRef`	TemplateRef	No	—	Reference to an `AerospikeClusterTemplate`. When set, the template spec is resolved and stored as a snapshot at creation time.
`overrides`	AerospikeClusterTemplateSpec	No	—	Fields that override the referenced template. Merge priority: overrides > template > operator defaults.

TemplateRef

Reference to an AerospikeClusterTemplate in the same namespace.

Field	Type	Required	Description
`name`	string	Yes	Name of the `AerospikeClusterTemplate` resource

TemplateSnapshotStatus

Recorded in status.templateSnapshot after a template is resolved.

Field	Type	Description
`name`	string	Name of the referenced template
`resourceVersion`	string	ResourceVersion of the template at snapshot time
`snapshotTimestamp`	Time	When the snapshot was taken
`synced`	bool	Whether the cluster uses the latest template version. Set to `false` when the template changes after the snapshot.
`spec`	AerospikeClusterTemplateSpec	Resolved template spec at snapshot time.

AerospikeConfigSpec

Holds the raw Aerospike configuration as an unstructured JSON/YAML object. The operator converts this to aerospike.conf format.

This is a map[string]interface{} wrapper. Access via .Value in Go code. In YAML, write the Aerospike configuration directly:

aerospikeConfig:
  service:
    cluster-name: my-cluster
    proto-fd-max: 15000
  network:
    service:
      port: 3000
    heartbeat:
      mode: mesh
      port: 3002
    fabric:
      port: 3001
  namespaces:
    - name: testns
      replication-factor: 2
      storage-engine:
        type: device
        file: /opt/aerospike/data/testns.dat
        filesize: 4294967296
  logging:
    - name: /var/log/aerospike/aerospike.log
      context: any info

AerospikeClusterStatus

Observed state of the Aerospike CE cluster.

Field	Type	Description
`phase`	string	Cluster phase: `InProgress`, `Completed`, `Error`, `ScalingUp`, `ScalingDown`, `RollingRestart`, `ACLSync`, `Paused`, `Deleting`.
`size`	int32	Current cluster size.
`conditions`	[]Condition	Latest observations of cluster state.
`pods`	map[string]AerospikePodStatus	Per-pod status information, keyed by pod name.
`observedGeneration`	int64	Most recent generation observed by the controller.
`selector`	string	Label selector string for HPA compatibility.
`aerospikeConfig`	AerospikeConfigSpec	Last applied Aerospike configuration.
`operationStatus`	OperationStatus	Current on-demand operation status.
`phaseReason`	string	Human-readable explanation of the current phase (e.g., "Rolling restart in progress for rack 1").
`appliedSpec`	AerospikeClusterSpec	Copy of the last successfully reconciled spec. Used to detect configuration drift.
`aerospikeClusterSize`	int32	Aerospike cluster-size as reported by `asinfo`. May differ from K8s pod count during split-brain or rolling restarts.
`operatorVersion`	string	Version of the operator that last reconciled this cluster.
`pendingRestartPods`	[]string	Pods queued for restart in the current rolling restart. Cleared when complete.
`lastReconcileTime`	Time	Timestamp of the last successful reconciliation.
`templateSnapshot`	TemplateSnapshotStatus	Resolved template spec at last sync time.

Condition Types

The operator maintains the following condition types in status.conditions:

Type	Description
`Available`	At least one pod is ready to serve requests.
`Ready`	All desired pods are running and ready.
`ConfigApplied`	All pods have the desired Aerospike configuration.
`ACLSynced`	ACL roles and users are synchronized with the cluster.
`MigrationComplete`	No data migrations are pending.
`ReconciliationPaused`	Reconciliation is paused by the user (`spec.paused: true`).

AerospikePodStatus

Per-pod status information.

Field	Type	Description
`podIP`	string	Pod IP address.
`hostIP`	string	Host node IP address.
`image`	string	Container image running on the pod.
`podPort`	int32	Aerospike service port on the pod.
`servicePort`	int32	Aerospike service port exposed via node/LB.
`rack`	int	Rack ID assigned to this pod.
`initializedVolumes`	[]string	Volumes that have been initialized.
`isRunningAndReady`	bool	Whether the pod is running and ready.
`configHash`	string	SHA256 hash of the applied config.
`podSpecHash`	string	Hash of the pod template spec.
`dynamicConfigStatus`	string	Dynamic config update result: `Applied`, `Failed`, `Pending`, or empty.
`dirtyVolumes`	[]string	Volumes needing initialization or cleanup.
`nodeID`	string	Aerospike-assigned node identifier (e.g., `BB9020012AC4202`). Empty if unreachable.
`clusterName`	string	Aerospike cluster name as reported by the node.
`accessEndpoints`	[]string	Network endpoints (`host:port`) for direct client access via `asinfo "service"`.
`readinessGateSatisfied`	bool	Whether `acko.io/aerospike-ready` gate is `True`. Only meaningful when `readinessGateEnabled=true`.
`lastRestartReason`	RestartReason	Reason the pod was last restarted by the operator.
`lastRestartTime`	Time	When the pod was last restarted by the operator.
`unstableSince`	Time	First time this pod became NotReady. Reset to `nil` when Ready.

RestartReason

Describes why a pod was restarted by the operator.

Value	Description
`ConfigChanged`	Cold restart triggered by an Aerospike config change.
`ImageChanged`	Pod image was updated.
`PodSpecChanged`	Pod spec (resources, env, etc.) changed.
`ManualRestart`	On-demand pod restart (`OperationPodRestart`).
`WarmRestart`	On-demand or rolling warm restart (SIGUSR1).

AerospikeStorageSpec

Defines storage volumes for Aerospike pods.

Field	Type	Required	Default	Description
`volumes`	[]VolumeSpec	No	—	List of volumes to attach.
`cleanupThreads`	int32	No	`1`	Max threads for volume cleanup/init.
`filesystemVolumePolicy`	AerospikeVolumePolicy	No	—	Default policy for filesystem-mode persistent volumes. Per-volume settings override this.
`blockVolumePolicy`	AerospikeVolumePolicy	No	—	Default policy for block-mode persistent volumes. Per-volume settings override this.
`localStorageClasses`	[]string	No	—	StorageClass names using local storage (e.g., `local-path`). Volumes using these classes require special handling on pod restart.
`deleteLocalStorageOnRestart`	*bool	No	—	Delete local PVCs before pod restart, forcing re-provisioning on new node.

AerospikeVolumePolicy

Default policies for a category of persistent volumes (filesystem or block).

Field	Type	Default	Description
`initMethod`	string	`none`	Default init method for this volume category.
`wipeMethod`	string	`none`	Default wipe method for this volume category.
`cascadeDelete`	*bool	`nil`	Delete PVCs when the CR is deleted.

VolumeSpec

Defines a single volume attachment.

Field	Type	Required	Default	Description
`name`	string	Yes	—	Volume name.
`source`	VolumeSource	Yes	—	Volume source (PVC, emptyDir, secret, configMap, hostPath).
`aerospike`	AerospikeVolumeAttachment	No	—	Mount path in Aerospike container.
`sidecars`	[]VolumeAttachment	No	—	Volume mounts for sidecar containers.
`initContainers`	[]VolumeAttachment	No	—	Volume mounts for init containers.
`initMethod`	string	No	`none`	Init method: `none`, `deleteFiles`, `dd`, `blkdiscard`, `headerCleanup`.
`wipeMethod`	string	No	`none`	Wipe method for dirty volumes: `none`, `deleteFiles`, `dd`, `blkdiscard`, `headerCleanup`, `blkdiscardWithHeaderCleanup`.
`cascadeDelete`	*bool	No	`nil`	Delete PVC when CR is deleted. When `nil`, falls back to global volume policy.

VolumeSource

Describes the volume data source. Exactly one field should be set.

Field	Type	Description
`persistentVolume`	PersistentVolumeSpec	Create a PVC.
`emptyDir`	EmptyDirVolumeSource	Use emptyDir.
`secret`	SecretVolumeSource	Use a Kubernetes Secret.
`configMap`	ConfigMapVolumeSource	Use a Kubernetes ConfigMap.
`hostPath`	HostPathVolumeSource	Use a path on the host node.

PersistentVolumeSpec

Defines a persistent volume claim template.

Field	Type	Required	Default	Description
`storageClass`	string	No	—	StorageClass name.
`volumeMode`	string	No	`Filesystem`	`Filesystem` or `Block`.
`size`	string	Yes	—	Storage size (e.g., `10Gi`).
`accessModes`	[]string	No	—	Access modes (e.g., `ReadWriteOnce`).
`selector`	LabelSelector	No	—	Label selector for PV binding.
`metadata`	AerospikeObjectMeta	No	—	Custom labels and annotations for the PVC.

AerospikeVolumeAttachment

Defines how a volume is mounted in the Aerospike container.

Field	Type	Required	Description
`path`	string	Yes	Mount path in the container.
`readOnly`	bool	No	Mount the volume as read-only.
`subPath`	string	No	Mount only a sub-path of the volume.
`subPathExpr`	string	No	Expanded path using environment variables. Mutually exclusive with `subPath`.
`mountPropagation`	MountPropagationMode	No	How mounts are propagated: `None`, `HostToContainer`, `Bidirectional`.

VolumeAttachment

Defines a volume mount for sidecar or init containers.

Field	Type	Required	Description
`containerName`	string	Yes	Target container name.
`path`	string	Yes	Mount path in the container.
`readOnly`	bool	No	Mount the volume as read-only.
`subPath`	string	No	Mount only a sub-path of the volume.
`subPathExpr`	string	No	Expanded path using environment variables. Mutually exclusive with `subPath`.
`mountPropagation`	MountPropagationMode	No	How mounts are propagated: `None`, `HostToContainer`, `Bidirectional`.

AerospikeNetworkPolicy

Defines network access configuration.

Field	Type	Default	Description
`accessType`	string	`pod`	Client access type: `pod`, `hostInternal`, `hostExternal`, `configuredIP`.
`alternateAccessType`	string	`pod`	Alternate access type.
`fabricType`	string	`pod`	Fabric (inter-node) network type.
`customAccessNetworkNames`	[]string	—	Network names for `configuredIP` access.
`customAlternateAccessNetworkNames`	[]string	—	Network names for `configuredIP` alternate access.
`customFabricNetworkNames`	[]string	—	Network names for `configuredIP` fabric.

SeedsFinderServices

Configures external seed discovery via LoadBalancer.

Field	Type	Description
`loadBalancer`	LoadBalancerSpec	LoadBalancer service configuration.

LoadBalancerSpec

Defines a LoadBalancer service.

Field	Type	Default	Description
`annotations`	map[string]string	—	Service annotations.
`labels`	map[string]string	—	Service labels.
`externalTrafficPolicy`	string	—	`Cluster` or `Local`.
`port`	int32	`3000`	External port.
`targetPort`	int32	`3000`	Container target port.
`loadBalancerSourceRanges`	[]string	—	Allowed source CIDRs.

AerospikePodSpec

Pod-level customization for Aerospike pods.

Field	Type	Description
`aerospikeContainer`	AerospikeContainerSpec	Aerospike container customization.
`sidecars`	[]Container	Sidecar containers.
`initContainers`	[]Container	Additional init containers.
`imagePullSecrets`	[]LocalObjectReference	Image pull secrets.
`nodeSelector`	map[string]string	Node labels for scheduling.
`tolerations`	[]Toleration	Pod tolerations.
`affinity`	Affinity	Affinity/anti-affinity rules.
`securityContext`	PodSecurityContext	Pod-level security attributes.
`serviceAccountName`	string	ServiceAccount name.
`dnsPolicy`	string	DNS policy for the pod.
`hostNetwork`	bool	Enable host networking.
`multiPodPerHost`	*bool	Allow multiple pods on the same node.
`terminationGracePeriodSeconds`	*int64	Pod termination grace period.
`topologySpreadConstraints`	[]TopologySpreadConstraint	How pods spread across topology domains.
`podManagementPolicy`	string	StatefulSet pod management: `OrderedReady` (default) or `Parallel`.
`metadata`	AerospikePodMetadata	Additional pod labels/annotations.
`readinessGateEnabled`	*bool	Enable custom readiness gate `acko.io/aerospike-ready`. Pods excluded from Service endpoints until Aerospike joins cluster mesh and finishes migrations.

AerospikeContainerSpec

Customizes the Aerospike server container.

Field	Type	Description
`resources`	ResourceRequirements	CPU/memory requests and limits.
`securityContext`	SecurityContext	Container-level security attributes.

AerospikePodMetadata

Extra labels and annotations for pods.

Field	Type	Description
`labels`	map[string]string	Additional pod labels.
`annotations`	map[string]string	Additional pod annotations.

RackConfig

Defines rack-aware deployment configuration.

Field	Type	Required	Description
`racks`	[]Rack	Yes	List of rack definitions (min 1).
`namespaces`	[]string	No	Aerospike namespace names that are rack-aware.
`scaleDownBatchSize`	IntOrString	No	Pods to scale down simultaneously per rack. Int or percent string (e.g., `"25%"`). Default: 1.
`maxIgnorablePods`	IntOrString	No	Max pending/failed pods to ignore during reconciliation.
`rollingUpdateBatchSize`	IntOrString	No	Pods to restart simultaneously per rack. Int or percent string. Takes precedence over `spec.rollingUpdateBatchSize`.

Rack

Defines a single rack in the cluster topology.

Field	Type	Required	Description
`id`	int	Yes	Unique rack identifier (>= 1). Rack ID 0 is reserved for the default rack.
`zone`	string	No	Zone label value (`topology.kubernetes.io/zone`).
`region`	string	No	Region label value (`topology.kubernetes.io/region`).
`nodeName`	string	No	Constrain to a specific node.
`rackLabel`	string	No	Custom label for rack affinity. Schedules to nodes with `acko.io/rack=<rackLabel>`. Must be unique across racks.
`revision`	string	No	Version identifier for controlled rack migrations.
`aerospikeConfig`	AerospikeConfigSpec	No	Per-rack Aerospike config override.
`storage`	AerospikeStorageSpec	No	Per-rack storage override.
`podSpec`	RackPodSpec	No	Per-rack pod scheduling override.

RackPodSpec

Rack-level pod scheduling overrides.

Field	Type	Description
`affinity`	Affinity	Rack-level affinity override.
`tolerations`	[]Toleration	Rack-level tolerations override.
`nodeSelector`	map[string]string	Rack-level node selector override.

AerospikeAccessControlSpec

Defines ACL configuration.

Field	Type	Description
`roles`	[]AerospikeRoleSpec	Aerospike role definitions.
`users`	[]AerospikeUserSpec	Aerospike user definitions.
`adminPolicy`	AerospikeClientAdminPolicy	Admin client timeout policy.

AerospikeRoleSpec

Defines an Aerospike role.

Field	Type	Required	Description
`name`	string	Yes	Role name.
`privileges`	[]string	Yes	Privilege strings: `read`, `write`, `read-write`, `read-write-udf`, `sys-admin`, `user-admin`, `data-admin`, `truncate`. Supports namespace scoping (e.g., `read-write.testns`).
`whitelist`	[]string	No	Allowed CIDR ranges.

AerospikeUserSpec

Defines an Aerospike user.

Field	Type	Required	Description
`name`	string	Yes	Username.
`secretName`	string	Yes	Kubernetes Secret name containing the password (key: `password`).
`roles`	[]string	Yes	Assigned role names (min 1).

AerospikeClientAdminPolicy

Admin client timeout settings.

Field	Type	Default	Description
`timeout`	int	`2000`	Admin operation timeout in milliseconds.

AerospikeMonitoringSpec

Prometheus monitoring configuration.

Field	Type	Default	Description
`enabled`	bool	`false`	Enable Prometheus exporter sidecar.
`exporterImage`	string	`aerospike/aerospike-prometheus-exporter:1.16.1`	Exporter container image.
`port`	int32	`9145`	Metrics port.
`resources`	ResourceRequirements	—	Exporter resource limits.
`env`	[]EnvVar	—	Additional environment variables for the exporter container.
`metricLabels`	map[string]string	—	Custom labels added to all exported metrics via `METRIC_LABELS` env var.
`serviceMonitor`	ServiceMonitorSpec	—	ServiceMonitor configuration.
`prometheusRule`	PrometheusRuleSpec	—	PrometheusRule configuration for cluster alerts.

ServiceMonitorSpec

ServiceMonitor configuration for Prometheus Operator.

Field	Type	Default	Description
`enabled`	bool	`false`	Create ServiceMonitor resource.
`interval`	string	`30s`	Scrape interval.
`labels`	map[string]string	—	Additional labels for ServiceMonitor discovery.

PrometheusRuleSpec

PrometheusRule configuration for Aerospike cluster alerts.

Field	Type	Default	Description
`enabled`	bool	`false`	Create PrometheusRule resource.
`labels`	map[string]string	—	Additional labels for PrometheusRule discovery.
`customRules`	[]JSON	—	Custom rule groups replacing built-in alerts (NodeDown, StopWrites, HighDiskUsage, HighMemoryUsage). Each entry must be a complete Prometheus rule group object with `name` and `rules` fields.

NetworkPolicyConfig

Automatic NetworkPolicy creation.

Field	Type	Default	Description
`enabled`	bool	`false`	Enable NetworkPolicy creation.
`type`	string	`kubernetes`	Policy type: `kubernetes` or `cilium`.

BandwidthConfig

Bandwidth annotations for CNI traffic shaping.

Field	Type	Description
`ingress`	string	Max ingress bandwidth (e.g., `1Gbps`, `500Mbps`).
`egress`	string	Max egress bandwidth (e.g., `1Gbps`, `500Mbps`).

OperationSpec

Defines an on-demand operation to trigger on cluster pods.

Field	Type	Required	Description
`kind`	string	Yes	Operation type: `WarmRestart` (SIGUSR1) or `PodRestart` (delete/recreate).
`id`	string	Yes	Unique operation identifier (1-20 characters).
`podList`	[]string	No	Specific pod names to target. Empty means all pods.

OperationStatus

Tracks the status of an on-demand operation.

Field	Type	Description
`id`	string	Operation identifier.
`kind`	string	Operation type: `WarmRestart` or `PodRestart`.
`phase`	string	Operation phase: `InProgress`, `Completed`, or `Error`.
`completedPods`	[]string	Pods that have completed the operation.
`failedPods`	[]string	Pods where the operation failed.

ValidationPolicySpec

Controls webhook validation behavior.

Field	Type	Default	Description
`skipWorkDirValidate`	bool	`false`	Skip validation that the Aerospike work directory is on persistent storage.

AerospikeServiceSpec

Defines custom metadata for a Kubernetes Service.

Field	Type	Required	Description
`metadata`	AerospikeObjectMeta	No	Custom annotations and labels for the service.

AerospikeObjectMeta

Custom metadata for Kubernetes objects.

Field	Type	Description
`annotations`	map[string]string	Custom annotations.
`labels`	map[string]string	Custom labels.