--- layout: page title: Usage instructions nav_order: 1 --- # 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`](https://www.helm.sh/), run the following commands (replace `` with the [version of the operator](https://github.com/arangodb/kube-arangodb/releases) that you want to install): ```bash export URLPREFIX=https://github.com/arangodb/kube-arangodb/releases/download/ helm install --generate-name $URLPREFIX/kube-arangodb-.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: ```bash helm install --generate-name $URLPREFIX/kube-arangodb-.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: ```bash helm install --generate-name $URLPREFIX/kube-arangodb-.tgz --set "operator.architectures={amd64,arm64}" ``` Note that you need to set [`spec.architecture`](deployment-resource-reference.md#specarchitecture-string) 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](helm.md). ### Installation with Kubectl To install the ArangoDB Kubernetes Operator without `Helm`, run (replace `` with the version of the operator that you want to install): ```bash export URLPREFIX=https://raw.githubusercontent.com/arangodb/kube-arangodb//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: ```bash 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: ```bash kubectl apply -f $URLPREFIX/arango-deployment-replication.yaml ``` See [ArangoDeploymentReplication Custom Resource](deployment-replication-resource-reference.md) for details and an example. You can find the latest release of the ArangoDB Kubernetes Operator in the [kube-arangodb repository](https://github.com/arangodb/kube-arangodb/releases/latest). ## ArangoDB deployment creation After deploying the latest ArangoDB Kubernetes operator, use the command below to deploy your [license key](https://docs.arangodb.com/stable/operations/administration/license-management/) as a secret which is required for the Enterprise Edition starting with version 3.9: ```bash kubectl create secret generic arango-license-key --from-literal=token-v2="" ``` 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](https://github.com/arangodb/kube-arangodb/tree/master/examples)): ```bash 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: ```yaml 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 `` with the `metadata.name` you set in the deployment configuration, e.g. `example-simple-cluster`): ```bash kubectl get service -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://:/` (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: ```bash 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: ```bash helm delete # If `ArangoLocalStorage` operator is installed helm delete ``` or when you used `kubectl` to install the operator, run: ```bash 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](https://minikube.sigs.k8s.io/) and follow the installation instructions and start the cluster with `minikube start`. Next, go to to find out the latest version of the ArangoDB Kubernetes Operator. Then run the following commands, with `` replaced by the version you looked up: ```bash minikube kubectl -- apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb//manifests/arango-crd.yaml minikube kubectl -- apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb//manifests/arango-deployment.yaml minikube kubectl -- apply -f https://raw.githubusercontent.com/arangodb/kube-arangodb//manifests/arango-storage.yaml ``` To deploy a single server, create a file called `single-server.yaml` with the following content: ```yaml apiVersion: "database.arangodb.com/v1" kind: "ArangoDeployment" metadata: name: "single-server" spec: mode: Single ``` Insert this resource in your Kubernetes cluster using: ```bash minikube kubectl -- apply -f single-server.yaml ``` To deploy an ArangoDB cluster instead, create a file called `cluster.yaml` with the following content: ```yaml 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: ```bash minikube kubectl -- describe ArangoDeployment single-server # or shorter minikube kubectl -- describe arango single-server ``` To inspect the pods created for this deployment, run: ```bash 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: ```bash 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: ```bash minikube kubectl -- delete ArangoDeployment single-server ``` To shut down `minikube`, run: ```bash minikube stop ``` ## See also - [Driver configuration](driver-configuration.md) - [Scaling](scaling.md) - [Upgrading](upgrading.md) - [Using the ArangoDB Kubernetes Operator with Helm](helm.md)