Using the ArangoDB Kubernetes Operator

Installation

The ArangoDB Kubernetes Operator needs to be installed in your Kubernetes cluster first. Make sure you have access to this cluster and the rights to deploy resources at cluster level.

The following cloud provider Kubernetes offerings are officially supported:

  • Amazon Elastic Kubernetes Service (EKS)
  • Google Kubernetes Engine (GKE)
  • Microsoft Azure Kubernetes Service (AKS)

If you have Helm available, use it for the installation as it is the recommended installation method.

Installation with Helm

To install the ArangoDB Kubernetes Operator with helm, run the following commands (replace <version> with the version of the operator that you want to install):

export URLPREFIX=https://github.com/arangodb/kube-arangodb/releases/download/<version>
helm install --generate-name $URLPREFIX/kube-arangodb-<version>.tgz

This installs operators for the ArangoDeployment and ArangoDeploymentReplication resource types, which are used to deploy ArangoDB and ArangoDB Datacenter-to-Datacenter Replication respectively.

If you want to avoid the installation of the operator for the ArangoDeploymentReplication resource type, add --set=DeploymentReplication.Create=false to the helm install command.

To use ArangoLocalStorage resources, also run:

helm install --generate-name $URLPREFIX/kube-arangodb-<version>.tgz --set "operator.features.storage=true"

The default CPU architecture of the operator is amd64 (x86-64). To enable ARM support (arm64) in the operator, overwrite the following setting:

helm install --generate-name $URLPREFIX/kube-arangodb-<version>.tgz --set "operator.architectures={amd64,arm64}"

Note that you need to set spec.architecture in the deployment specification, too, in order to create a deployment that runs on ARM chips.

For more information on installing with Helm and how to customize an installation, see Using the ArangoDB Kubernetes Operator with Helm.

Installation with Kubectl

To install the ArangoDB Kubernetes Operator without Helm, run (replace <version> with the version of the operator that you want to install):

export URLPREFIX=https://raw.githubusercontent.com/arangodb/kube-arangodb/<version>/manifests
kubectl apply -f $URLPREFIX/arango-crd.yaml
kubectl apply -f $URLPREFIX/arango-deployment.yaml

To use ArangoLocalStorage resources to provision PersistentVolumes on local storage, also run:

kubectl apply -f $URLPREFIX/arango-storage.yaml

Use this when running on bare-metal or if there is no provisioner for fast storage in your Kubernetes cluster.

To use ArangoDeploymentReplication resources for ArangoDB Datacenter-to-Datacenter Replication, also run:

kubectl apply -f $URLPREFIX/arango-deployment-replication.yaml

See ArangoDeploymentReplication Custom Resource for details and an example.

You can find the latest release of the ArangoDB Kubernetes Operator in the kube-arangodb repository.

ArangoDB deployment creation

After deploying the latest ArangoDB Kubernetes operator, use the command below to deploy your license key as a secret which is required for the Enterprise Edition starting with version 3.9:

# For the License Key
kubectl create secret generic arango-license-key --from-literal=token-v2="<license-string>"

# For the License Manager Key
kubectl create secret generic arango-license-key --from-literal=license-client-id="<license-client-id>" --from-literal=license-client-secret="<license-client-secret>"

Once the operator is running, you can create your ArangoDB database deployment by creating a ArangoDeployment custom resource and deploying it into your Kubernetes cluster.

For example (all examples can be found in the kube-arangodb repository):

kubectl apply -f examples/simple-cluster.yaml

Additionally, you can specify the license key required for the Enterprise Edition starting with version 3.9 as seen below:

spec:
  # [...]
  image: arangodb/enterprise:3.9.1
  license:
    secretName: arango-license-key

Connecting to your database

Access to ArangoDB deployments from outside the Kubernetes cluster is provided using an external-access service. By default, this service is of type LoadBalancer. If this type of service is not supported by your Kubernetes cluster, it is replaced by a service of type NodePort after a minute.

To see the type of service that has been created, run (replace <service-name> with the metadata.name you set in the deployment configuration, e.g. example-simple-cluster):

kubectl get service <service-name>-ea

When the service is of the LoadBalancer type, use the IP address listed in the EXTERNAL-IP column with port 8529. When the service is of the NodePort type, use the IP address of any of the nodes of the cluster, combine with the high (>30000) port listed in the PORT(S) column.

Point your browser to https://<ip>:<port>/ (note the https protocol). Your browser shows a warning about an unknown certificate. Accept the certificate for now. Then log in using the username root and an empty password.

Deployment removal

To remove an existing ArangoDB deployment, delete the custom resource. The operator deletes all created resources.

For example:

kubectl delete -f examples/simple-cluster.yaml

Note that this will also delete all data in your ArangoDB deployment!

If you want to keep your data, make sure to create a backup before removing the deployment.

Operator removal

To remove the entire ArangoDB Kubernetes Operator, remove all clusters first and then remove the operator by running:

helm delete <release-name-of-kube-arangodb-chart>
# If `ArangoLocalStorage` operator is installed
helm delete <release-name-of-kube-arangodb-storage-chart>

or when you used kubectl to install the operator, run:

kubectl delete deployment arango-deployment-operator
# If `ArangoLocalStorage` operator is installed
kubectl delete deployment -n kube-system arango-storage-operator
# If `ArangoDeploymentReplication` operator is installed
kubectl delete deployment arango-deployment-replication-operator

Example deployment using minikube

If you want to get your feet wet with ArangoDB and Kubernetes, you can deploy your first ArangoDB instance with minikube, which lets you easily set up a local Kubernetes cluster.

Visit the minikube website and follow the installation instructions and start the cluster with minikube start.

Next, go to https://github.com/arangodb/kube-arangodb/releases to find out the latest version of the ArangoDB Kubernetes Operator. Then run the following commands, with <version> replaced by the version you looked up:

minikube kubectl -- apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb/<version>/manifests/arango-crd.yaml
minikube kubectl -- apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb/<version>/manifests/arango-deployment.yaml
minikube kubectl -- apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb/<version>/manifests/arango-storage.yaml

To deploy a single server, create a file called single-server.yaml with the following content:

apiVersion: "database.arangodb.com/v1"
kind: "ArangoDeployment"
metadata:
  name: "single-server"
spec:
  mode: Single

Insert this resource in your Kubernetes cluster using:

minikube kubectl -- apply -f single-server.yaml

To deploy an ArangoDB cluster instead, create a file called cluster.yaml with the following content:

apiVersion: "database.arangodb.com/v1"
kind: "ArangoDeployment"
metadata:
  name: "cluster"
spec:
  mode: Cluster

The same commands used in the single server deployment can be used to inspect your cluster. Just use the correct deployment name (cluster instead of single-server).

The ArangoDeployment operator in kube-arangodb inspects the resource you just deployed and starts the process to run ArangoDB.

To inspect the current status of your deployment, run:

minikube kubectl -- describe ArangoDeployment single-server
# or shorter
minikube kubectl -- describe arango single-server

To inspect the pods created for this deployment, run:

minikube kubectl -- get pods --selector=arango_deployment=single-server

The result looks similar to this:

NAME                                 READY     STATUS    RESTARTS   AGE
single-server-sngl-cjtdxrgl-fe06f0   1/1       Running   0          1m

Once the pod reports that it is has a Running status and is ready, your ArangoDB instance is available.

To access ArangoDB, run:

minikube service single-server-ea

This creates a temporary tunnel for the single-server-ea service and opens your browser. You need change the URL to start with https://. By default, it is http://, but the deployment uses TLS encryption for the connection. For example, if the address is http://127.0.0.1:59050, you need to change it to https://127.0.0.1:59050.

Your browser warns about an unknown certificate. This is because a self-signed certificate is used. Continue anyway. The exact steps for this depend on your browser.

You should see the login screen of ArangoDB’s web interface. Enter root as the username, leave the password field empty, and log in. Select the default _system database. You should see the dashboard and be able to interact with ArangoDB.

If you want to delete your single server ArangoDB database, just run:

minikube kubectl -- delete ArangoDeployment single-server

To shut down minikube, run:

minikube stop

See also