Step 1: Get the installation information
You receive a package configuration file and license credentials from the Arango team.
The Contextual Data Platform package configuration is a YAML file that defines which services to install and their configurations.
The license credentials are composed of a client ID and client secret that you need to activate a deployment online or to generate license keys for offline deployments (e.g. air-gapped).
In case of an installation on hardware with internet access, everything needed to install the services of the Platform Suite is downloaded during the setup.
The internet access needs to be persistent for the license activation and continuous renewal of the license.
Step 2: Create a namespace
Ensure kubectl is properly configured and can communicate with your
Kubernetes cluster, e.g. by running the following commands:
kubectl cluster-info
kubectl get nodes
Create a Kubernetes namespace for ArangoDB and the Platform Suite resources.
The namespace used throughout this guide is called arango, but you can use
a different name.
kubectl create namespace arango
When you specify the namespace for a command, you can do that in two ways:
--namespace arango(long-form option)-n arango(short-form option)
This guide uses long-form options for clarity.
Step 3: Create a secret for the license
Create a Kubernetes secret with your license credentials. The ArangoDB
Kubernetes Operator uses them to activate the deployment and renew the
license automatically. For the renewal lifecycle, required network access
(*.license.arango.ai), and configuration options, see
License Management.
Substitute <license-client-id> and <license-client-secret>
with the actual license credentials:
kubectl create secret generic arango-license-key \
--namespace arango \
--from-literal=license-client-id="<license-client-id>" \
--from-literal=license-client-secret="<license-client-secret>"
You may run the following command to verify that the secret was created:
kubectl get secret arango-license-key --namespace arango
Expected output:
NAME TYPE DATA AGE
arango-license-key Opaque 2 10s
Step 4: Install the Operator
Install the ArangoDB Kubernetes Operator
(kube-arangodb) with Helm. It is the core component that manages ArangoDB
deployments and the Contextual Data Platform. It watches for custom resources and creates
the necessary Kubernetes resources.
You can find the latest release on GitHub: https://github.com/arangodb/kube-arangodb/releases/latest/
Make sure to set the options as shown below to enable webhooks, certificates, the gateway feature, and machine learning:
VERSION_OPERATOR='1.4.6' # Use a newer version if available
helm upgrade --install operator \
--namespace arango \
"https://github.com/arangodb/kube-arangodb/releases/download/$VERSION_OPERATOR/kube-arangodb-enterprise-$VERSION_OPERATOR.tgz" \
--set "webhooks.enabled=true" \
--set "operator.args[0]=--deployment.feature.gateway=true" \
--set "operator.architectures={amd64}"
Use --set "operator.architectures={arm64}" instead if your Kubernetes nodes
run on ARM CPUs, such as on Macs with Apple silicon (M1 and later). If the
configured architecture doesn’t match the nodes, the operator cannot start the
deployment.
The output looks similar to the following on success:
Release "operator" does not exist. Installing it now.
NAME: operator
LAST DEPLOYED: Thu Feb 5 16:12:21 2026
NAMESPACE: arango
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
TEST SUITE: None
NOTES:
You have installed Kubernetes ArangoDB Operator in version 1.4.6
To access ArangoDeployments you can use:
kubectl --namespace "arango" get arangodeployments
More details can be found on https://github.com/arangodb/kube-arangodb/tree/1.4.6/docs
You may use the following commands to wait for the operator to be ready and verify it is running:
kubectl wait --for=condition=ready pod --selector app.kubernetes.io/name=kube-arangodb-enterprise --namespace arango --timeout=120s
kubectl get deployment --namespace arango --selector app.kubernetes.io/name=kube-arangodb-enterprise
kubectl get pods --namespace arango --selector app.kubernetes.io/name=kube-arangodb-enterprise
Expected output (x stands for varying letter or digit):
NAME READY UP-TO-DATE AVAILABLE AGE
arango-operator-operator 1/1 1 1 45s
NAME READY STATUS RESTARTS AGE
arango-operator-operator-xxxxxxxxxx-xxxxx 1/1 Running 0 45s
Step 5: Create a deployment
Create an ArangoDeployment specification for ArangoDB. See the
ArangoDeployment Custom Resource Overview
and the linked reference.
You need to enable the gateway feature by setting spec.gateway.enabled and
spec.gateway.dynamic to true in the specification. Enable vector indexes
(on DB-Servers and Coordinators respectively on single server) because they are
required by features such as GraphRAG (from ArangoDB version 4.0.0 onward, the
vector index feature is enabled by default). You also need to set spec.license to
the secret created earlier.
Example for an ArangoDB cluster deployment using version 3.12.12 with three
DB-Servers and two Coordinators with the name deployment-example:
apiVersion: "database.arangodb.com/v1"
kind: "ArangoDeployment"
metadata:
name: "deployment-example"
spec:
architecture:
- amd64
mode: Cluster
image: "arangodb/enterprise:3.12.12"
gateway:
enabled: true
dynamic: true
gateways:
count: 1
dbservers:
count: 3
args:
- --vector-index # For ArangoDB versions before 4.0.0
coordinators:
count: 2
args:
- --vector-index # For ArangoDB versions before 4.0.0
license:
secretName: arango-license-key
# ...
The example sets spec.architecture to amd64 for x86-64 nodes. On ARM-based
Kubernetes nodes, such as Macs with Apple silicon, set it to arm64 instead:
spec:
architecture:
- arm64
This setting is independent of the architecture option of the operator
described in the previous step. If the architecture doesn’t match the nodes,
the pods of the deployment remain in the Pending state.
You can save the specification as a YAML file, e.g. deployment.yaml.
Apply the specification using the previously created name (here: arango)
and wait for the pods to be ready:
kubectl apply --namespace arango -f deployment.yaml
kubectl get pods --namespace arango --watch
You can stop watching the pods with the key combination Ctrl + C .
Given the above specification using the name deployment-example, you should
eventually see pods with the following names with a status of Running:
deployment-example-agnt-*(3 Agents)deployment-example-crdn-*(2 Coordinators)deployment-example-prmr-*(3 DB-Servers)deployment-example-gway-*(1 Gateway)
If the pods remain Pending and never start, the architecture of the
deployment most likely doesn’t match the nodes. Inspect the pod to confirm:
kubectl get pod <pod-name> --namespace arango -o yaml
A message such as 0/1 nodes are available: 1 node(s) didn't match Pod's node affinity/selector in the status section indicates a mismatch. Correct
spec.architecture, apply the specification again, and then delete the stuck
pod so that the Operator recreates it with the correct architecture:
kubectl delete pod <pod-name> --namespace arango
Step 6: Get the Contextual Data Platform CLI tool
Download the Arango Contextual Data Platform CLI tool arangodb_operator_platform from
https://github.com/arangodb/kube-arangodb/releases/latest.
It is available for Linux, macOS, and Windows for the x86-64 as well as 64-bit ARM
architecture (e.g. arangodb_operator_platform_linux_amd64).
It is recommended to rename the downloaded executable to
arangodb_operator_platform (with an .exe extension on Windows) and add it to
the PATH environment variable to make it available as a command in the system.
The Platform CLI tool simplifies the further setup and later management of the Platform’s Kubernetes services.
Step 7: Set up object storage
Features like GraphML require an additional storage system to save model training data, for instance.
The following example shows how to set up a local SeaweedFS and integrate it
with the Arango Contextual Data Platform, but you can also use a remote object
storage like S3. For the supported storage systems, see the
kube-arangodb documentation.
Install SeaweedFS with the platform-storage Helm chart of the ArangoDB
Kubernetes Operator. It deploys a single SeaweedFS instance with a Persistent
Volume Claim (PVC) of five gibibytes in the namespace of your
ArangoDeployment, which is arango in this example, generates the access
credentials, and creates the ArangoPlatformStorage resource that integrates
the object storage with the Contextual Data Platform. The value of
deployment.name (deployment-example) must match the name of the
ArangoDeployment:
helm install seaweedfs \
--namespace arango \
"https://github.com/arangodb/kube-arangodb/releases/download/$VERSION_OPERATOR/platform-storage-$VERSION_OPERATOR.tgz" \
--set backend=seaweedfs \
--set deployment.name=deployment-example
You can change the size of the volume with --set storage.size=<SIZE>, for
example, --set storage.size=20Gi, and the storage class with
--set storage.class=<STORAGE_CLASS>. If you don’t set a storage class, the
default storage class of your cluster is used.
Verify that the storage integration is ready. The READY column needs to show
True before you proceed:
kubectl get arangoplatformstorage --namespace arango
Expected output:
NAME READY
deployment-example True
You don’t need to create the bucket yourself. The platform services create it on startup if it doesn’t exist yet.
Set up the object storage before you install the data platform package.
The storage configuration is injected into the pods of the platform services
when the pods are created. If you set up the storage after installing the data
platform package, restart the services that use the storage so that they are
recreated with the storage configuration. Only do so after the storage reports
READY as True. The following command restarts all services that use the
storage by matching their storage integration label:
kubectl delete pod --namespace arango \
--selector integration.profiles.arangodb.com/storage=v2
If a service started before the storage was ready, operations that need the
storage fail and the service logs show errors such as
unknown service storage.StorageV2. Restarting the affected pods as shown
above resolves this.
Step 8: Install the Contextual Data Platform package
Install the package using the package configuration you received from the
Arango team (platform.yaml). This requires license credentials and internet
access to *.license.arango.ai.
The package installation creates and enables various services, including the unified web interface of the Contextual Data Platform.
Substitute <license-client-id> and <license-client-secret>
with the actual license credentials and ./platform.yaml with the path to the
package configuration file. The platform name (deployment-example) needs to
match the name as specified in the ArangoDeployment configuration.
arangodb_operator_platform --namespace arango package install \
--license.client.id "<license-client-id>" \
--license.client.secret "<license-client-secret>" \
--platform.name deployment-example \
./platform.yaml
The command can take a while to complete because it pulls the container images of all the services in the package.
Step 9: Verify the installation
The Operator downloads and starts the platform services. Watch the pods until they are all up:
kubectl get pods --namespace arango --watch
You can stop watching the pods with the key combination Ctrl + C .
The first run takes several minutes because the service images are large and
are pulled for the first time. Eventually, every pod reaches the Running
state with all of its containers ready.
The pod list shows the readiness at a glance, but the reliable way to confirm
that the platform is fully up is to check the platform services. They should
all report READY as True:
kubectl get arangoplatformservices --namespace arango
If a pod stays in Pending or keeps restarting, the nodes most likely ran out
of resources. To find out why a pod doesn’t start, describe it and check its
events and logs. Most platform pods run multiple containers, so pass
--all-containers=true to get the logs of all of them:
kubectl describe pod <pod-name> --namespace arango
kubectl logs <pod-name> --namespace arango --all-containers=true
Step 10: Open the web interface
The platform exposes all of its services through the gateway on port 8529
inside Kubernetes. Forward that port to your machine:
kubectl port-forward --namespace arango \
service/deployment-example-ea 8529:8529
Leave that command running and open the unified web interface in your browser:
Log in with the default user root and an empty password. These defaults are
fine for a local evaluation but are not secure; set a password before you
expose a deployment beyond your own machine.
For the browser warning about the self-signed certificate, how to stop the port forwarding, and how to reach the other interfaces, see Interfaces.
