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.

---

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

---

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