# Get started with AKO locally

This tutorial describes how to create an Aerospike Database Enterprise Edition deployment using the Aerospike Kubernetes Operator (AKO) on a local Kubernetes cluster with Minikube or MicroK8s.

Minikube creates a temporary, single-node cluster that you start and stop as needed. MicroK8s installs as a persistent, lightweight Kubernetes distribution that runs continuously on your machine. The setup and deployment steps are nearly identical — where they differ, choose the tab that applies to your platform.

::: tip
If you’re on macOS and want to try AKO quickly, use Minikube. MicroK8s on macOS requires a Multipass VM, which adds extra setup. MicroK8s is simpler on Linux, where it runs natively.
:::

## Prerequisites

-   [Minikube](https://minikube.sigs.k8s.io/docs/start/) or [MicroK8s](https://canonical.com/microk8s/docs/getting-started) installed
-   Helm
-   Git
-   Kubectl
-   An Aerospike Enterprise Edition feature-key file
    -   Download a free Enterprise Edition feature-key file good for 60 days at this link: [Get Started with Aerospike](https://aerospike.com/get-started-aerospike-database/)

This tutorial assumes basic conceptual knowledge of Kubernetes.

## Pre-install

Start your local cluster and verify that your terminal can communicate with it.

-   [Minikube](#tab-panel-3063)
-   [MicroK8s](#tab-panel-3064)

Start a new Minikube cluster. If you already have one running, you can skip the `minikube start` command.

Terminal window

```bash
# Start a local Kubernetes cluster

minikube start

# Check connectivity and versions

kubectl cluster-info                 # API-server reachable?

kubectl get nodes -o wide            # Node visible?

helm version --short                 # Helm installed?

git --version                        # Git installed?
```

MicroK8s runs as a persistent service after installation. Enable the required add-ons and export its kubeconfig so that standard `kubectl` and `helm` commands work.

Terminal window

```bash
# Enable required add-ons

microk8s enable dns hostpath-storage

# Export kubeconfig for standard kubectl access

mkdir -p ~/.kube

microk8s config > ~/.kube/config

# Check connectivity and versions

kubectl cluster-info                 # API-server reachable?

kubectl get nodes -o wide            # Node visible?

helm version --short                 # Helm installed?

git --version                        # Git installed?
```

::: caution
The `microk8s config` command overwrites your existing `~/.kube/config`. If you manage other clusters, merge the configuration manually or use the `KUBECONFIG` environment variable instead.
:::

## Install AKO

In this section, you use Helm to install AKO on your Kubernetes cluster and configure the Kubernetes namespace to watch for your Aerospike Database deployment.

1.  Add the JetStack Helm repository so you can install `cert-manager`, a utility that AKO relies on to manage certificates.
    
    Terminal window
    
    ```shell
    helm repo add jetstack https://charts.jetstack.io --force-update
    ```
    
2.  Install the `cert-manager` Helm chart.
    
    Terminal window
    
    ```shell
    helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --version v1.17.0 --set crds.enabled=true
    ```
    
3.  Add the AKO Helm repository.
    
    Terminal window
    
    ```shell
    helm repo add aerospike https://aerospike.github.io/aerospike-kubernetes-enterprise
    ```
    
4.  Install AKO to your cluster. The `watchNamespaces` parameter tells AKO which Kubernetes namespace to monitor for AerospikeCluster custom resources.
    
    Terminal window
    
    ```bash
    helm install aerospike-kubernetes-operator aerospike/aerospike-kubernetes-operator --version=4.3.0 --set watchNamespaces="aerospike"
    ```
    

AKO is now running on your cluster and is ready to create a new Aerospike Database deployment.

## Deploy an Aerospike database

In this section, you use `kubectl` to deploy Aerospike Database. This tutorial uses a pre-built sample configuration for Aerospike Database deployment.

1.  Create a dedicated Kubernetes namespace for your Aerospike Database deployment. This must match the `watchNamespaces` value you set when installing AKO.
    
    Terminal window
    
    ```shell
    kubectl create namespace aerospike
    ```
    
2.  Download the Aerospike Kubernetes Operator repository from GitHub to your local machine. This repository contains sample configuration files for an Aerospike Database deployment. You can modify these files on your local machine before using `kubectl` to apply the changes to the cluster.
    
    Terminal window
    
    ```shell
    git clone https://github.com/aerospike/aerospike-kubernetes-operator.git
    ```
    
    The only directory you need to interact with during this tutorial is `config/samples/` as shown in the following diagram:
    
    -   Directoryaerospike-kubernetes-operator
        
        -   Directoryapi/
            
            -   …
            
        -   Directorycmd/
            
            -   …
            
        -   Directory**config/**
            
            -   Directory**samples/**
                
                -   …
                
            -   … **(sample configuration files)**
            
        -   … (other directories)
        
    
3.  Navigate to the repository and check out the release tag that matches your AKO version.
    
    Terminal window
    
    ```bash
    cd aerospike-kubernetes-operator
    
    git checkout v4.3.0
    ```
    
    Your working directory should remain `aerospike-kubernetes-operator/` for the rest of this tutorial. All `config/samples/...` paths are relative to this directory.
    
4.  Copy your feature-key file, typically named `features.conf`, into the existing `config/samples/secrets/` directory. Aerospike Enterprise Edition requires this file to start.
    
5.  Create the Kubernetes Secrets that the Aerospike cluster needs at runtime. The first secret loads everything in the secrets directory, including your feature-key file. The second sets a placeholder initial password for the Aerospike `admin` user.
    
    Terminal window
    
    ```shell
    kubectl -n aerospike create secret generic aerospike-secret --from-file=config/samples/secrets
    
    kubectl -n aerospike create secret generic auth-secret --from-literal=password='admin123'
    ```
    
6.  Create a ServiceAccount for AKO in the `aerospike` Kubernetes namespace. AKO uses this identity when it manages pods, services, and other resources for your database.
    
    Terminal window
    
    ```shell
    kubectl -n aerospike create serviceaccount aerospike-operator-controller-manager
    ```
    
7.  Bind the `aerospike-cluster` ClusterRole to the ServiceAccount you just created. This grants AKO the permissions it needs to manage Aerospike cluster resources.
    
    Terminal window
    
    ```shell
    kubectl create clusterrolebinding aerospike-cluster --clusterrole=aerospike-cluster --serviceaccount=aerospike:aerospike-operator-controller-manager
    ```
    
8.  Configure storage for the cluster. The sample CR expects a storage class named `ssd` for its persistent volume. Neither Minikube nor MicroK8s includes this class by default, so you must create it or apply a sample from the repository.
    
    -   [Minikube](#tab-panel-3065)
    -   [MicroK8s](#tab-panel-3066)
    
    Create an `ssd` storage class that uses Minikube’s built-in hostpath provisioner:
    
    Terminal window
    
    ```shell
    kubectl apply -f - <<EOF
    
    apiVersion: storage.k8s.io/v1
    
    kind: StorageClass
    
    metadata:
    
      name: ssd
    
    provisioner: k8s.io/minikube-hostpath
    
    reclaimPolicy: Delete
    
    volumeBindingMode: Immediate
    
    EOF
    ```
    
    Apply the MicroK8s filesystem storage class from the sample files in the GitHub repository.
    
    Terminal window
    
    ```shell
    kubectl apply -f config/samples/storage/microk8s_filesystem_storage_class.yaml
    ```
    
9.  Create the Aerospike cluster by applying a sample Custom Resource (CR). AKO watches for this resource and automatically provisions the Aerospike Database pods. This sample stores data in memory, which is the simplest configuration for local development and testing.
    
    Terminal window
    
    ```shell
    kubectl apply -f config/samples/dim_nostorage_cluster_cr.yaml
    ```
    
    ::: note
    This CR uses data-in-memory storage, so data does not persist across pod restarts. For persistent storage on MicroK8s, use a storage-backed CR file from the `config/samples` directory.
    :::
    
    After you apply the CR, the cluster starts initializing or updating.
    
10.  Watch the cluster status. The `-w` flag streams updates so you can see the phase change in real time.
     
     Terminal window
     
     ```shell
     kubectl get aerospikeclusters aerocluster -n aerospike -w
     ```
     
     Wait until the **PHASE** column shows `Completed`, then press Ctrl+C to stop watching. This can take a few minutes depending on the resources available.
     
     Terminal window
     
     ```shell
     NAME          SIZE   IMAGE                                           MULTIPODPERHOST   HOSTNETWORK   AGE   PHASE
     
     aerocluster   2      aerospike/aerospike-server-enterprise:8.1.1.0   true                            2s    InProgress
     
     aerocluster   2      aerospike/aerospike-server-enterprise:8.1.1.0   true                            21s   InProgress
     
     aerocluster   2      aerospike/aerospike-server-enterprise:8.1.1.0   true                            21s   InProgress
     
     aerocluster   2      aerospike/aerospike-server-enterprise:8.1.1.0   true                            27s   InProgress
     
     aerocluster   2      aerospike/aerospike-server-enterprise:8.1.1.0   true                            28s   Completed
     ```
     
11.  Find the access endpoints for your cluster. These are the `host:port` pairs that client applications use to connect to your Aerospike database.
     
     Terminal window
     
     ```shell
     kubectl -n aerospike describe aerospikeclusters aerocluster | grep -E 'Access Endpoints|Alternate Access Endpoints' -A1
     ```
     
     You can use any of the Aerospike client libraries to write tests for reading and writing to this Aerospike Database.
     

You now have a locally running Aerospike Database deployment using AKO!

## Cleanup

When you are finished with your local deployment, clean up the cluster resources.

-   [Minikube](#tab-panel-3067)
-   [MicroK8s](#tab-panel-3068)

Delete the entire Minikube cluster. This removes all Kubernetes resources including the Aerospike deployment.

Terminal window

```bash
minikube delete
```

The next time you need a cluster, start fresh with `minikube start`.

Since MicroK8s is a persistent installation, delete the Aerospike cluster and AKO resources rather than the entire Kubernetes environment.

Terminal window

```bash
kubectl delete -f config/samples/dim_nostorage_cluster_cr.yaml

helm uninstall aerospike-kubernetes-operator

helm uninstall cert-manager -n cert-manager

kubectl delete clusterrolebinding aerospike-cluster

kubectl delete ns aerospike
```

## Next steps

The biggest difference between the cluster created in this tutorial and a production cluster is in the storage class and CR file configurations. See the [AKO Configuration](https://aerospike.com/docs/kubernetes/4.3.x/manage/configure/overview) section to learn how to configure your deployment for your own application needs.

Become familiar with the [Aerospike Backup Service (ABS)](https://aerospike.com/docs/kubernetes/4.3.x/tools/backup/overview) and the [monitoring stack](https://aerospike.com/docs/kubernetes/4.3.x/observe/operator-monitoring). They are separate services that run alongside the database in your cluster. ABS listens for REST requests to perform backups and restores of the database, while the monitoring stack lets you visualize cluster statistics on Grafana dashboards.