ACKO Deployment Guide

Deploy Aerospike Community Edition clusters on Kubernetes using the ACKO operator.

---

1. Quick Deploy: 1-Node Dev Cluster in 3 Steps

Step 1: Check Prerequisites

Run these commands to verify your environment is ready:

# Verify kubectl is connected to a cluster
kubectl cluster-info

# Verify the ACKO operator is running
kubectl get pods -n aerospike-operator -l control-plane=controller-manager

# Verify the AerospikeCluster CRD is installed
kubectl api-resources | grep aerospikeclusters

# Create the target namespace (if it does not exist)
kubectl create namespace aerospike --dry-run=client -o yaml | kubectl apply -f -

If the operator is not running, install it first:

kubectl apply -f https://raw.githubusercontent.com/aerospike-ce-ecosystem/aerospike-ce-kubernetes-operator/main/config/deploy/operator.yaml

Step 2: Apply the Minimal CR

apiVersion: acko.io/v1alpha1
kind: AerospikeCluster
metadata:
  name: aerospike-basic
  namespace: aerospike
spec:
  size: 1
  image: aerospike:ce-8.1.1.1
  aerospikeConfig:
    namespaces:
      - name: test
        replication-factor: 1
        storage-engine:
          type: memory
          data-size: 1073741824   # 1 GiB
    logging:
      - name: /var/log/aerospike/aerospike.log
        context: any info

Save this as aerospike-basic.yaml and apply:

kubectl apply -f aerospike-basic.yaml

Step 3: Verify Deployment

# Wait for phase=Completed (typically 30-90 seconds)
kubectl wait --for=jsonpath='{.status.phase}'=Completed asc/aerospike-basic -n aerospike --timeout=120s

# Check cluster status (should show PHASE=Completed, HEALTH=1/1)
kubectl get asc aerospike-basic -n aerospike

# Check pod status (should show 1/1 Running)
kubectl get pods -n aerospike

# Verify Aerospike is responding
kubectl exec -n aerospike aerospike-basic-0-0 -c aerospike-server -- asinfo -v status
# Expected output: ok

---

2. CE Constraints (Webhook-Enforced)

These constraints are enforced by the ACKO validating webhook. Violating any of them causes the CR to be rejected at apply time.

1. Cluster size: spec.size must be between 1 and 8 (inclusive).
2. Namespaces: Maximum 2 namespaces in aerospikeConfig.namespaces.
3. No XDR: aerospikeConfig must not contain an xdr section (Enterprise-only).
4. No TLS: aerospikeConfig must not contain a tls section (Enterprise-only).
5. No Enterprise images: spec.image must not contain enterprise, ee-, or ent-.
6. Mesh heartbeat only: network.heartbeat.mode must be mesh.
7. Byte values as integers: All size values in aerospikeConfig (such as data-size, filesize) must be specified as integer byte counts, not human-readable strings.
8. Replication factor: Must be between 1 and 4, and must not exceed spec.size.
9. No Enterprise namespace keys: The following keys are forbidden in namespace config: compression, compression-level, durable-delete, fast-restart, index-type, sindex-type, rack-id, strong-consistency, tomb-raider-eligible-age, tomb-raider-period.
10. No Enterprise security keys: Only enable-security and default-password-file are allowed in aerospikeConfig.security. The keys tls, ldap, log, syslog are forbidden.
11. Strengthened map/list shapes (April 2026): aerospikeConfig.service and aerospikeConfig.network must be YAML maps; aerospikeConfig.logging must be a YAML list; each namespaces[] entry must be a map with a name key. MetricLabels values are TOML-escaped — control characters are rejected. Within one update, namespace rack-id may be added OR removed but not both (prevents data loss on rename).
12. Operations spec invariants: spec.operations[].kind must be WarmRestart or PodRestart; spec.operations[].id length 1–20 chars; the operations list cannot be modified while one operation is InProgress. spec.overrides only valid when spec.templateRef is set.

---

3. Deployment Scenarios

Choose the scenario that matches your needs. Each links to a ready-to-use YAML example.

Scenario 1: Minimal In-Memory (Dev/Test)

• File: ./examples/01-minimal.yaml
• Use when: Quick local dev, CI tests, learning ACKO
• Key features: 1 node, in-memory storage, no persistence, no ACL

Scenario 2: 3-Node with Persistent Volume (Staging/Production Baseline)

• File: ./examples/02-3node-pv.yaml
• Use when: You need data persistence across pod restarts
• Key features: 3 nodes, PVC-backed device storage, resource limits, cascadeDelete

Scenario 3: ACL (Access Control)

• File: ./examples/03-acl.yaml
• Use when: You need authentication and role-based access control
• Key features: security stanza, admin user (sys-admin + user-admin required), K8s Secrets for passwords

Scenario 4: Prometheus Monitoring

• File: ./examples/04-monitoring.yaml
• Use when: You need metrics, dashboards, and alerting
• Key features: Exporter sidecar, ServiceMonitor, PrometheusRule, metric labels

Scenario 5: Multi-Rack (Zone-Aware Topology)

• File: ./examples/05-multirack.yaml
• Use when: You need high availability across availability zones
• Key features: 3 racks pinned to zones, rack-aware replication

Scenario 6: Advanced Storage

• File: ./examples/06-storage-advanced.yaml
• Use when: You need block devices, hostPath, CSI, local PV, or sidecar mounts
• Key features: Volume policies, block volumes, mount propagation, sidecar sharing

Scenario 7: Template-Based

• File: ./examples/07-template.yaml
• Use when: You manage multiple clusters with shared configuration
• Key features: AerospikeClusterTemplate, templateRef, overrides, resync annotation

Scenario 8: Full-Featured

• File: ./examples/08-full-featured.yaml
• Use when: Production deployment with all features enabled
• Key features: ACL + monitoring + multi-rack + PV + PDB + dynamic config

Scenario 9: On-Demand Operations (WarmRestart / PodRestart)

• File: ./examples/09-operations.yaml
• Use when: You need to manually restart pods (warm via SIGUSR1, or full pod recreate) without changing spec
• Key features: spec.operations[] with WarmRestart (SIGUSR1) or PodRestart (delete+recreate); optional podList to target specific pods; webhook prevents modifying the operations list while one is InProgress

Monitoring sample note (04-monitoring.yaml): Recent fix — metricLabels values are TOML-escaped (double-quote-wrapped, backslash-escaped, control chars rejected) and the demo emptyDir mount points to /opt/aerospike/work instead of accidentally overlaying /opt/aerospike. If you cloned this example before April 2026, verify both.

---

4. CR Spec Reference

Detail: ./reference/cr-spec-fields.md

---

5. Webhook Auto-Settings

Webhook auto-settings and CRD field mapping: See acko-config-reference skill's reference/crd-mapping.md

---

6. Verification Commands

Run these after deploying or modifying a cluster.

# List all Aerospike clusters with their phase
kubectl get asc -n aerospike

# Check specific cluster phase
kubectl get asc <name> -n aerospike -o jsonpath='{.status.phase}'

# Check phase reason (useful when phase is Error or InProgress)
kubectl get asc <name> -n aerospike -o jsonpath='{.status.phaseReason}'

# Check all conditions
kubectl get asc <name> -n aerospike -o jsonpath='{.status.conditions}' | jq .

# Check pod status details
kubectl get asc <name> -n aerospike -o jsonpath='{.status.pods}' | jq .

# Check ready pod count
kubectl get asc <name> -n aerospike -o jsonpath='{.status.size}'

# Check cluster events (most recent last)
kubectl get events -n aerospike --field-selector involvedObject.name=<name> --sort-by='.lastTimestamp'

# Verify Aerospike service is responding
kubectl exec -n aerospike <pod-name> -c aerospike-server -- asinfo -v status

# Check cluster membership
kubectl exec -n aerospike <pod-name> -c aerospike-server -- asinfo -v 'statistics' | tr ';' '\n' | grep cluster_size

# Check namespace stats
kubectl exec -n aerospike <pod-name> -c aerospike-server -- asinfo -v 'namespace/<namespace-name>'

---

7. Byte Value Reference

Byte values: See acko-config-reference skill's reference/byte-values.md

---

8. CE 8.1 Configuration Notes

CE 8.1 notes: See acko-config-reference skill

---

9. Template Fix Notice (April 2026)

A recent operator fix re-applies the resolved template to the in-memory cluster spec after every Status().Update/Patch, so template-derived fields (PodSpec.PodAntiAffinity, Resources, Storage) now reach the StatefulSet and persist across reconciles. If you previously worked around this by inlining template values into spec.overrides, you can drop those workarounds. VolumeClaimTemplate updates remain immutable — VCTs are only set at StatefulSet creation time inside buildStatefulSet.