Install Aerospike Kubernetes Operator using Helm

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

This page describes how to use Helm charts to install the Aerospike Kubernetes Operator (AKO).

Helm charts are groups of YAML files that describe Kubernetes resources and their current configurations. If you plan to use Helm charts to deploy Aerospike clusters, you also need to use Helm to install the AKO on your Kubernetes deployment.

Prerequisites

kubectl
A running Kubernetes cluster.
- Install minikube to create a local cluster.
- See the Kubernetes documentation to explore other options.
cert-manager, unless you provide the AKO webhook certificate another way. See Webhook certificates.
Helm

In Kubernetes 1.23 and later, Pod Security Admission (PSA) is enabled by default. Make sure the namespace where the AKO is installed has either baseline or privileged Pod Security Standard level set. The restricted level is not supported by Aerospike. The default Pod Security Standard level in Kubernetes 1.23 is privileged. For more details, see Apply Pod Security Standards.

If you use cert-manager, verify that it is running before you install AKO:

kubectl get pods -n cert-manager

Webhook certificates

AKO uses admission webhooks, which need a TLS serving certificate. The certs.webhook.provider Helm value sets where the certificate comes from:

`certs.webhook.provider`	Certificate source	Requires `cert-manager`
`certManager` (Recommended)	Default behavior (inferred when `provider` is empty). The chart creates a `cert-manager` `Issuer` and `Certificate`, and `cert-manager` adds the CA bundle to the webhook configurations.	Yes
`selfSigned`	The chart generates a CA and a serving certificate and stores them in a Secret. Use it only for development and proofs of concept.	No
`external`	You create the serving certificate Secret and pass the CA that signed it in `certs.webhook.external.caBundle`.	No

cert-manager is also required when certs.metrics.create is true, whichever webhook provider you choose.

certs.webhook.create is deprecated. The chart reads it only when certs.webhook.provider is empty. If an existing installation sets certs.webhook.create: false, the chart keeps the previous AKO behavior: it creates no Issuer or Certificate, and cert-manager fills in the CA bundle from the aerospike-operator-serving-cert Certificate that you manage.

Self-signed certificate

A selfSigned certificate is valid for one year, and nothing renews it. To replace it, delete the Secret and run helm upgrade. Replacing the certificate can interrupt admission until the new certificate is in place. The chart reuses the existing Secret on later upgrades, but helm template and helm install --dry-run generate a new certificate every time, so don’t use selfSigned with a pipeline that renders manifests and then applies them. The certificate’s validity starts at the clock of the machine that runs helm, so check that its clock is correct.

External certificate

In the AKO namespace, create a TLS Secret named webhook-server-cert, or the name set in certs.webhook.webhookServerCertSecretName. Issue the certificate for these DNS names:
```
aerospike-operator-webhook-service.NAMESPACE_NAME.svc
aerospike-operator-webhook-service.NAMESPACE_NAME.svc.cluster.local
```
Base64-encode the CA certificate that signed the serving certificate. Pass the CA certificate, not the serving certificate.
Terminal window
```
base64 < ca.crt > ca.b64
```

Add the external certificate flags to the helm install command in Install AKO:

helm install aerospike-kubernetes-operator aerospike/aerospike-kubernetes-operator \
--namespace NAMESPACE_NAME \
--version=${version} \
--set watchNamespaces="aerospike" \
--set certs.webhook.provider=external \
--set-file certs.webhook.external.caBundle=ca.b64

The AKO pods stay in ContainerCreating until the Secret exists.

Switching an existing installation from one provider to another can interrupt admission until the new certificate is in place. For the switching procedure, see the AKO Helm chart README.

Install AKO

Add the Helm repository to get the AKO Helm charts. If you already have a Helm repo named aerospike, choose a different name.
Terminal window
```
helm repo add aerospike https://aerospike.github.io/aerospike-kubernetes-enterprise

helm repo update
```
This URL is a Helm chart repository. Helm reads the index.yaml at this location internally. If you open it in a browser you may see a 404. Go to https://aerospike.github.io/aerospike-kubernetes-enterprise/index.yaml to inspect the YAML manually.
Install AKO on your Kubernetes cluster. Replace the placeholder NAMESPACE_NAME with your own namespace name. If --namespace is not given, AKO uses a namespace called default.
Terminal window
```
helm install aerospike-kubernetes-operator aerospike/aerospike-kubernetes-operator --namespace NAMESPACE_NAME --version=4.6.0 --set watchNamespaces="aerospike"
```

Check AKO logs

AKO runs as two replicas by default for higher availability. Run the following command to follow the logs for the AKO pods.

kubectl -n NAMESPACE_NAME logs -f deployments/aerospike-kubernetes-operator manager

Sample output:

2026-01-08T14:27:14Z  INFO  setup  Initializing webhook certificate watcher using provided certificates  {"webhook-cert-path": "/tmp/k8s-webhook-server/serving-certs", "webhook-cert-name": "tls.crt", "webhook-cert-key": "tls.key"}
2026-01-08T14:27:14Z  INFO  controller-runtime.certwatcher  Updated current TLS certificate
2026-01-08T14:27:14Z  INFO  setup  Init aerospike-server config schemas
2026-01-08T14:27:14Z  DEBUG  setup  Config schema added  {"version": "6.0.0"}
2026-01-08T14:27:14Z  DEBUG  setup  Config schema added  {"version": "6.1.0"}
2026-01-08T14:27:14Z  DEBUG  setup  Config schema added  {"version": "6.2.0"}
2026-01-08T14:27:14Z  DEBUG  setup  Config schema added  {"version": "7.0.0"}
2026-01-08T14:27:14Z  DEBUG  setup  Config schema added  {"version": "8.0.0"}
2026-01-08T14:27:14Z  DEBUG  setup  Config schema added  {"version": "8.1.0"}
2026-01-08T14:27:14Z  DEBUG  setup  Config schema added  {"version": "8.2.0"}
2026-01-08T14:27:14Z  DEBUG  setup  Config schema added  {"version": "6.3.0"}
2026-01-08T14:27:14Z  DEBUG  setup  Config schema added  {"version": "6.4.0"}
2026-01-08T14:27:14Z  DEBUG  setup  Config schema added  {"version": "7.1.0"}
2026-01-08T14:27:14Z  DEBUG  setup  Config schema added  {"version": "7.2.0"}
2026-01-08T14:27:14Z  INFO  controller-runtime.builder  Registering a mutating webhook  {"GVK": "asdb.aerospike.com/v1, Kind=AerospikeCluster", "path": "/mutate-asdb-aerospike-com-v1-aerospikecluster"}
2026-01-08T14:27:14Z  INFO  controller-runtime.webhook  Registering webhook  {"path": "/mutate-asdb-aerospike-com-v1-aerospikecluster"}
2026-01-08T14:27:14Z  INFO  controller-runtime.builder  Registering a validating webhook  {"GVK": "asdb.aerospike.com/v1, Kind=AerospikeCluster", "path": "/validate-asdb-aerospike-com-v1-aerospikecluster"}
2026-01-08T14:27:14Z  INFO  controller-runtime.webhook  Registering webhook  {"path": "/validate-asdb-aerospike-com-v1-aerospikecluster"}
2026-01-08T14:27:14Z  INFO  controller-runtime.builder  Registering a mutating webhook  {"GVK": "asdb.aerospike.com/v1beta1, Kind=AerospikeBackupService", "path": "/mutate-asdb-aerospike-com-v1beta1-aerospikebackupservice"}
2026-01-08T14:27:14Z  INFO  controller-runtime.webhook  Registering webhook  {"path": "/mutate-asdb-aerospike-com-v1beta1-aerospikebackupservice"}
2026-01-08T14:27:14Z  INFO  controller-runtime.builder  Registering a validating webhook  {"GVK": "asdb.aerospike.com/v1beta1, Kind=AerospikeBackupService", "path": "/validate-asdb-aerospike-com-v1beta1-aerospikebackupservice"}
2026-01-08T14:27:14Z  INFO  controller-runtime.webhook  Registering webhook  {"path": "/validate-asdb-aerospike-com-v1beta1-aerospikebackupservice"}
2026-01-08T14:27:14Z  INFO  controller-runtime.builder  Registering a mutating webhook  {"GVK": "asdb.aerospike.com/v1beta1, Kind=AerospikeBackup", "path": "/mutate-asdb-aerospike-com-v1beta1-aerospikebackup"}
2026-01-08T14:27:14Z  INFO  controller-runtime.webhook  Registering webhook  {"path": "/mutate-asdb-aerospike-com-v1beta1-aerospikebackup"}
2026-01-08T14:27:14Z  INFO  controller-runtime.builder  Registering a validating webhook  {"GVK": "asdb.aerospike.com/v1beta1, Kind=AerospikeBackup", "path": "/validate-asdb-aerospike-com-v1beta1-aerospikebackup"}
2026-01-08T14:27:14Z  INFO  controller-runtime.webhook  Registering webhook  {"path": "/validate-asdb-aerospike-com-v1beta1-aerospikebackup"}
2026-01-08T14:27:14Z  INFO  controller-runtime.builder  Registering a mutating webhook  {"GVK": "asdb.aerospike.com/v1beta1, Kind=AerospikeRestore", "path": "/mutate-asdb-aerospike-com-v1beta1-aerospikerestore"}
2026-01-08T14:27:14Z  INFO  controller-runtime.webhook  Registering webhook  {"path": "/mutate-asdb-aerospike-com-v1beta1-aerospikerestore"}
2026-01-08T14:27:14Z  INFO  controller-runtime.builder  Registering a validating webhook  {"GVK": "asdb.aerospike.com/v1beta1, Kind=AerospikeRestore", "path": "/validate-asdb-aerospike-com-v1beta1-aerospikerestore"}
2026-01-08T14:27:14Z  INFO  controller-runtime.webhook  Registering webhook  {"path": "/validate-asdb-aerospike-com-v1beta1-aerospikerestore"}
2026-01-08T14:27:14Z  INFO  eviction-webhook  Eviction webhook metrics registered
2026-01-08T14:27:14Z  INFO  controller-runtime.webhook  Registering webhook  {"path": "/validate-eviction"}
2026-01-08T14:27:14Z  INFO  setup  Adding webhook certificate watcher to manager
2026-01-08T14:27:14Z  INFO  setup  Starting manager
2026-01-08T14:27:14Z  INFO  starting server  {"name": "health probe", "addr": "[::]:8081"}
2026-01-08T14:27:14Z  INFO  controller-runtime.webhook  Starting webhook server
2026-01-08T14:27:14Z  INFO  setup  disabling http/2
2026-01-08T14:27:14Z  INFO  controller-runtime.webhook  Serving webhook server  {"host": "", "port": 9443}

Grant permissions to the target namespaces (required before creating clusters)

AKO is installed in the namespace that you chose in step 2 in the “Install AKO” section. Grant additional permissions by configuring ServiceAccounts and RoleBindings or ClusterRoleBindings for the target Kubernetes namespace where the Aerospike clusters are created.

AKO can only create Aerospike clusters in namespaces where it has been granted the aerospike-cluster role. For a first‑time setup, grant permissions to a single namespace used for your test cluster.

You can use the kubectl or akoctl tools to grant permissions for the aerospike namespace.

kubectl
akoctl

Create the Kubernetes namespace if it doesn’t already exist.
```
kubectl create namespace aerospike
```

Create a service account.

kubectl -n aerospike create serviceaccount aerospike-operator-controller-manager

Create a RoleBinding or ClusterRoleBinding to attach this service account to the aerospike-cluster ClusterRole. This ClusterRole is created as part of AKO installation and grants Aerospike cluster permissions to the service account.
- For using the Kubernetes native pod-only network to connect to the Aerospike cluster:
  1. Create a RoleBinding with the following command:
    kubectl -n aerospike create rolebinding aerospike-cluster --clusterrole=aerospike-cluster --serviceaccount=aerospike:aerospike-operator-controller-manager
- For connecting to the Aerospike cluster from outside Kubernetes:
  1. Create a ClusterRoleBinding with the following command:
    kubectl create clusterrolebinding aerospike-cluster --clusterrole=aerospike-cluster --serviceaccount=aerospike:aerospike-operator-controller-manager
    Add multiple --serviceaccount parameters to the previous command to attach multiple service accounts of different namespaces at one time.
    Example: To attach service accounts of the aerospike and aerospike1 namespaces:
    kubectl create clusterrolebinding aerospike-cluster --clusterrole=aerospike-cluster --serviceaccount=aerospike:aerospike-operator-controller-manager --serviceaccount=aerospike1:aerospike-operator-controller-manager
  2. If the required ClusterRoleBinding already exists in the cluster, edit it to attach a new service account.
    kubectl edit clusterrolebinding aerospike-cluster
  3. The kubectl edit command launches an editor. Append the following lines to the subjects section:
    kind: ServiceAccount name: aerospike-operator-controller-manager namespace: aerospike
  4. Save and ensure that the changes are applied.

For instructions on installing the akoctl plugin, see akoctl installation.

For using the Kubernetes native pod-only network to connect to the Aerospike cluster, grant namespace scope permissions:
```
kubectl akoctl auth create -n aerospike --cluster-scope=false
```
For connecting to the Aerospike cluster from outside Kubernetes, grant cluster scope permissions:
```
kubectl akoctl auth create -n aerospike
```
To grant permissions for multiple namespaces at the same time, specify a comma-separated namespace list with the -n flag.
```
kubectl akoctl auth create -n aerospike,aerospike1
```

Configuration reference

The chart includes a values schema. Helm checks your values against it when you install, upgrade, or render the chart, and rejects a value of the wrong type or an unknown key inside a structured value such as operatorImage or certs.webhook.

Name	Description	Default
`replicas`	Number of AKO replicas	`2`
`operatorImage.repository`	AKO image repository	`aerospike/aerospike-kubernetes-operator`
`operatorImage.tag`	AKO image tag	4.6.0
`operatorImage.pullPolicy`	Image pull policy	`IfNotPresent`
`imagePullSecrets`	Secrets containing credentials to pull AKO image from a private registry	`{}` (nil)
`rbac.create`	Set this to `true` to let helm chart automatically create RBAC resources necessary for AKO	`true`
`rbac.serviceAccountName`	If `rbac.create=false`, provide a service account name to be used with the AKO deployment	`default`
`healthPort`	Health port	`8081`
`metricsPort`	Metrics port on the AKO container	`8443`
`certs.webhook.provider`	Source of the webhook serving certificate: `certManager`, `selfSigned`, or `external`. When empty, the chart uses `certs.webhook.create`. See Webhook certificates.	`""` (empty)
`certs.webhook.create`	Deprecated. Use `certs.webhook.provider`. Read only when `certs.webhook.provider` is empty: `true` behaves like `certManager`, and `false` keeps the previous AKO behavior of using a `Certificate` that you manage.	`true`
`certs.webhook.external.caBundle`	Base64-encoded PEM of the CA that signed the webhook serving certificate. Required when `certs.webhook.provider` is `external`.	`""` (empty)
`certs.webhook.webhookServerCertSecretName`	Kubernetes secret name for webhook server certificates	`webhook-server-cert`
`certs.metrics.create`	Set this to `true` to let the Helm chart create metrics TLS certificates using `cert-manager`	`false`
`certs.metrics.metricsServerCertSecretName`	Kubernetes secret name for metrics server certificates	`metrics-server-cert`
`watchNamespaces`	Namespaces to watch. AKO watches for `AerospikeCluster` custom resources in these namespaces	`default,aerospike`
`ignoreNamespaces`	Namespaces ignored by the eviction webhook (comma-separated)	`kube-system,kube-node-lease`
`safePodEviction.enable`	Enable the eviction webhook to safely block Aerospike pod evictions during node maintenance. Also enables Prometheus metrics (`aerospike_ako_eviction_webhook_requests_total` with labels: eviction_namespace, decision).	`false`
`safePodEviction.timeoutSeconds`	Timeout in seconds that the Kubernetes API server waits for the safe pod eviction webhook to respond on each eviction request.	`20`
`failedPodGracePeriodSeconds`	Grace period to delete/recover failed pods (in seconds)	`60`
`logging.development`	Zap development profile (`--zap-devel`); keep `true` unless you want production-style logging	`true`
`logging.level`	Optional; when set (non-empty), chart adds `--zap-log-level`. If omitted or `""`, no flag is emitted and Zap uses its default level (typically `info` unless overridden).	`""` (empty)
`logging.encoder`	Optional; when set (non-empty), chart adds `--zap-encoder` (`json` or `console`). If omitted or `""`, no flag is emitted and Zap uses its default encoder.	`""` (empty)
`metrics.secure`	Passed as `--metrics-secure` on the manager; when `true`, serves `/metrics` over HTTPS with auth (controller-runtime default)	`true`
`aerospikeKubernetesInitRegistry`	Registry used to pull aerospike-init image	`docker.io`
`resources`	Resource requests and limits for the AKO pods	`limits`: cpu `400m`, memory `512Mi`; `requests`: cpu `10m`, memory `64Mi`
`affinity`	Affinity rules for the AKO deployment	`{}` (nil)
`extraEnv`	Extra environment variables that are passed into the AKO pods	`{}` (nil)
`nodeSelector`	Node selectors for scheduling the AKO pods based on node labels	`{}` (nil)
`tolerations`	Tolerations for scheduling the AKO pods based on node taints	`{}` (nil)
`annotations`	Annotations for the AKO deployment	`{}` (nil)
`labels`	Labels for the AKO deployment	`{}` (nil)
`podAnnotations`	Annotations for the AKO pods	`{}` (nil)
`podLabels`	Labels for the AKO pods	`{}` (nil)
`metricsService.labels`	Labels for the AKO metrics service	`{}` (nil)
`metricsService.annotations`	Annotations for the AKO metrics service	`{}` (nil)
`metricsService.port`	The AKO metrics service port	`8443`
`metricsService.type`	The AKO metrics service type	`ClusterIP`
`webhookService.labels`	Labels for the AKO webhook service	`{}` (nil)
`webhookService.annotations`	Annotations for the AKO webhook service	`{}` (nil)
`webhookService.port`	The AKO webhook service port	`443`
`webhookService.targetPort`	The AKO webhook target port	`9443`
`webhookService.type`	The AKO webhook service type	`ClusterIP`
`podSecurityContext`	Security context for the AKO pods	`{}` (nil)
`securityContext`	Security context for the AKO container	`allowPrivilegeEscalation: false`
`livenessProbe`	Liveliness probe for the AKO container	`initialDelaySeconds: 15`, `periodSeconds: 20`, `timeoutSeconds: 1`, `successThreshold: 1`, `failureThreshold: 3`
`readinessProbe`	Readiness probe for the AKO container	`initialDelaySeconds: 5`, `periodSeconds: 10`, `timeoutSeconds: 1`, `successThreshold: 1`, `failureThreshold: 3`

Next steps

AKO is now installed and watching the namespaces you configured.

To deploy your first Aerospike cluster with Helm, continue to Use Helm to create an Aerospike Cluster on Kubernetes.
For a step‑by‑step tutorial including AKO and a sample cluster on GKE or EKS, see Get started with Aerospike Kubernetes Operator in the cloud.