Skip to main content

Installation

This guide covers two methods to install the ACKO operator.

Prerequisites​

  • Kubernetes cluster v1.26+
  • kubectl configured to access the cluster
  • cert-manager installed (required for webhook TLS)

cert-manager​

cert-manager is required for webhook TLS. Install it before the operator:

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true

Wait for cert-manager to be ready:

kubectl -n cert-manager wait --for=condition=Available deployment/cert-manager --timeout=60s
kubectl -n cert-manager wait --for=condition=Available deployment/cert-manager-webhook --timeout=60s

Install the Operator​

The simplest installation method using the published OCI Helm chart.

helm install aerospike-ce-kubernetes-operator oci://ghcr.io/kimsoungryoul/charts/aerospike-ce-kubernetes-operator \
  -n aerospike-operator --create-namespace

Customizing Helm Values​

You can override default values:

helm install aerospike-ce-kubernetes-operator oci://ghcr.io/kimsoungryoul/charts/aerospike-ce-kubernetes-operator \
  -n aerospike-operator --create-namespace \
  --set replicaCount=2 \
  --set resources.limits.memory=256Mi

To see all available values:

helm show values oci://ghcr.io/kimsoungryoul/charts/aerospike-ce-kubernetes-operator

Monitoring (Optional)​

The Helm chart includes built-in support for Prometheus Operator monitoring resources. All monitoring features are disabled by default and require Prometheus Operator (commonly installed via kube-prometheus-stack).

ServiceMonitor​

Creates a ServiceMonitor resource so Prometheus automatically scrapes operator metrics.

helm install aerospike-ce-kubernetes-operator oci://ghcr.io/kimsoungryoul/charts/aerospike-ce-kubernetes-operator \
  -n aerospike-operator --create-namespace \
  --set serviceMonitor.enabled=true \
  --set serviceMonitor.additionalLabels.release=prometheus
tip

The additionalLabels.release=prometheus label must match your Prometheus Operator's serviceMonitorSelector. Check with:

kubectl get prometheus -A -o jsonpath='{.items[*].spec.serviceMonitorSelector}'
ParameterDefaultDescription
serviceMonitor.enabledfalseCreate ServiceMonitor resource
serviceMonitor.interval—Scrape interval (e.g., "30s")
serviceMonitor.scrapeTimeout—Scrape timeout (e.g., "10s")
serviceMonitor.additionalLabels{}Extra labels for Prometheus selector matching

PrometheusRule​

Creates a PrometheusRule resource with built-in alerting rules for the operator.

helm install aerospike-ce-kubernetes-operator oci://ghcr.io/kimsoungryoul/charts/aerospike-ce-kubernetes-operator \
  -n aerospike-operator --create-namespace \
  --set serviceMonitor.enabled=true \
  --set prometheusRule.enabled=true

Built-in alerts (used when prometheusRule.rules is empty):

AlertConditionSeverity
AerospikeOperatorDownOperator unreachable for 5mcritical
AerospikeOperatorReconcileErrorsReconcile error rate > 0 for 15mwarning
AerospikeOperatorSlowReconcilep99 reconcile time > 60s for 10mwarning
AerospikeOperatorWorkQueueDepthQueue depth > 10 for 10mwarning
AerospikeOperatorHighMemoryMemory > 256Mi for 10mwarning
AerospikeOperatorPodRestarts> 3 restarts in 1hwarning

To provide custom rules instead of the built-in defaults, use a values.yaml file:

prometheusRule:
  enabled: true
  rules:
    - alert: CustomAerospikeAlert
      expr: up{job="aerospike"} == 0
      for: 5m
      labels:
        severity: critical
      annotations:
        summary: "Custom Aerospike alert"
ParameterDefaultDescription
prometheusRule.enabledfalseCreate PrometheusRule resource
prometheusRule.additionalLabels{}Extra labels for Prometheus selector matching
prometheusRule.rules[]Custom rules; when empty, built-in defaults are used

Grafana Dashboard​

Creates a ConfigMap with a pre-built Grafana dashboard. Requires the Grafana sidecar to be configured for auto-discovery.

helm install aerospike-ce-kubernetes-operator oci://ghcr.io/kimsoungryoul/charts/aerospike-ce-kubernetes-operator \
  -n aerospike-operator --create-namespace \
  --set grafanaDashboard.enabled=true

The dashboard includes panels for: Reconcile Rate, Reconcile Errors, Reconcile Duration (p99/p50), Work Queue Depth, Operator Memory Usage, and Operator CPU Usage.

ParameterDefaultDescription
grafanaDashboard.enabledfalseCreate dashboard ConfigMap
grafanaDashboard.sidecarLabelgrafana_dashboardLabel key for Grafana sidecar discovery
grafanaDashboard.sidecarLabelValue"1"Label value for Grafana sidecar discovery
grafanaDashboard.folder""Grafana folder name for organizing dashboards

Setting Up Grafana with Dashboard Auto-Discovery​

A step-by-step guide to install Grafana with sidecar enabled and view the operator dashboard via port-forward.

1. Add Grafana Helm repository:

helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

2. Install Grafana with sidecar enabled:

helm install grafana grafana/grafana \
  -n monitoring --create-namespace \
  --set sidecar.dashboards.enabled=true \
  --set sidecar.dashboards.label=grafana_dashboard \
  --set sidecar.dashboards.labelValue="1" \
  --set sidecar.dashboards.searchNamespace=ALL \
  --set sidecar.datasources.enabled=true
info

sidecar.dashboards.searchNamespace=ALL enables the sidecar to discover dashboard ConfigMaps across all namespaces, including aerospike-operator where the operator chart deploys the dashboard ConfigMap. Without this, the sidecar only watches its own namespace.

3. Install (or upgrade) the operator with the dashboard enabled:

helm install aerospike-ce-kubernetes-operator oci://ghcr.io/kimsoungryoul/charts/aerospike-ce-kubernetes-operator \
  -n aerospike-operator --create-namespace \
  --set grafanaDashboard.enabled=true

4. Get the Grafana admin password:

kubectl -n monitoring get secret grafana -o jsonpath="{.data.admin-password}" | base64 -d; echo

5. Port-forward to access Grafana:

kubectl -n monitoring port-forward svc/grafana 3000:80

6. Open http://localhost:3000 in your browser. Log in with:

  • Username: admin
  • Password: the value from step 4

The "Aerospike CE Operator" dashboard will appear automatically under Dashboards. If you set grafanaDashboard.folder, it will be organized in the specified folder.

tip

If the dashboard does not appear, verify the ConfigMap was created and has the correct label:

kubectl -n aerospike-operator get configmap -l grafana_dashboard=1

Full Monitoring Stack Example​

Enable all monitoring features at once:

helm install aerospike-ce-kubernetes-operator oci://ghcr.io/kimsoungryoul/charts/aerospike-ce-kubernetes-operator \
  -n aerospike-operator --create-namespace \
  --set serviceMonitor.enabled=true \
  --set serviceMonitor.additionalLabels.release=prometheus \
  --set prometheusRule.enabled=true \
  --set grafanaDashboard.enabled=true \
  --set grafanaDashboard.folder=Aerospike

Cluster Manager UI (Optional)​

Aerospike Cluster Manager is a web-based GUI for managing Aerospike CE clusters — record browsing, query building, index management, K8s cluster lifecycle, and more.

Enable the UI when installing the operator:

helm install aerospike-ce-kubernetes-operator oci://ghcr.io/kimsoungryoul/charts/aerospike-ce-kubernetes-operator \
  -n aerospike-operator --create-namespace \
  --set ui.enabled=true

Access via port-forward:

kubectl -n aerospike-operator port-forward svc/aerospike-ce-kubernetes-operator-ui 3000:3000

See the Cluster Manager UI guide for full configuration options, Ingress setup, security, and feature documentation.

Verify Installation​

Check the operator pod is running:

kubectl -n aerospike-operator get pods

Expected output:

NAME                                    READY   STATUS    RESTARTS   AGE
aerospike-ce-kubernetes-operator-controller-manager-xxxxx-yyyyy     1/1     Running   0          30s

Check the CRD is registered:

kubectl get crd aerospikeclusters.acko.io

Quick Start: Full Installation Script​

A single copy-paste script that sets up everything from scratch on a Kind cluster — cert-manager, Prometheus, the operator (with all monitoring enabled), Grafana, a sample Aerospike cluster, and verification.

Prerequisites

Create a Kind cluster first:

kind create cluster --config kind-config.yaml --name kind
# =============================================================================
# 1. Install cert-manager
# =============================================================================
helm repo add jetstack https://charts.jetstack.io
helm repo update jetstack
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true \
  --wait

# =============================================================================
# 2. Install Prometheus Operator (kube-prometheus-stack)
# =============================================================================
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update prometheus-community
helm install prometheus prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --create-namespace \
  --set grafana.enabled=false \
  --wait

# =============================================================================
# 3. Install Aerospike Operator (all monitoring enabled)
# =============================================================================
helm install aerospike-ce-kubernetes-operator oci://ghcr.io/kimsoungryoul/charts/aerospike-ce-kubernetes-operator \
  -n aerospike-operator --create-namespace \
  --set serviceMonitor.enabled=true \
  --set serviceMonitor.additionalLabels.release=prometheus \
  --set prometheusRule.enabled=true \
  --set grafanaDashboard.enabled=true \
  --set grafanaDashboard.folder=Aerospike \
  --wait

# =============================================================================
# 4. Install Grafana with sidecar dashboard auto-discovery
# =============================================================================
helm repo add grafana https://grafana.github.io/helm-charts
helm repo update grafana
helm install grafana grafana/grafana \
  --namespace monitoring \
  --set sidecar.dashboards.enabled=true \
  --set sidecar.dashboards.label=grafana_dashboard \
  --set sidecar.dashboards.labelValue="1" \
  --set sidecar.dashboards.searchNamespace=ALL \
  --set sidecar.datasources.enabled=true \
  --wait

# =============================================================================
# 5. Deploy an Aerospike CE cluster
# =============================================================================
kubectl create namespace aerospike --dry-run=client -o yaml | kubectl apply -f -
kubectl apply -f config/samples/acko_v1alpha1_aerospikecluster.yaml

echo "Waiting for Aerospike pod to be ready..."
kubectl -n aerospike wait --for=condition=Ready pod/aerospike-ce-basic-0-0 --timeout=120s

# =============================================================================
# 6. Verify: run asinfo inside the Aerospike pod
# =============================================================================
echo "=== Aerospike cluster info ==="
kubectl -n aerospike exec -it aerospike-ce-basic-0-0 -- asinfo -v status
kubectl -n aerospike exec -it aerospike-ce-basic-0-0 -- asinfo -v build

# =============================================================================
# 7. Port-forward Grafana (access at http://localhost:3000)
# =============================================================================
GRAFANA_PASSWORD=$(kubectl -n monitoring get secret grafana \
  -o jsonpath="{.data.admin-password}" | base64 -d)
echo ""
echo "=== Grafana ==="
echo "URL:      http://localhost:3000"
echo "Username: admin"
echo "Password: ${GRAFANA_PASSWORD}"
echo ""
kubectl -n monitoring port-forward svc/grafana 3000:80
tip

The script uses --wait on each Helm install so subsequent steps don't start until the previous component is fully ready. If you want to run this in CI without the final port-forward, remove the last command.

Uninstall​

warning

Always delete AerospikeCluster resources before uninstalling the operator. Removing the operator first will leave orphaned StatefulSets and PVCs.

# Delete all Aerospike clusters first
kubectl delete asc --all --all-namespaces

# Uninstall the operator
helm uninstall aerospike-ce-kubernetes-operator -n aerospike-operator

# (Optional) Uninstall CRDs — WARNING: this deletes all AerospikeCluster data
# helm uninstall aerospike-ce-kubernetes-operator-crds

# (Optional) Delete the namespace
kubectl delete namespace aerospike-operator