Deployment Checklist
Choose how the service will run before provisioning infrastructure. If you already have an endpoint and API key, connect through the CLI quick start.
| Goal | Deployment path | Next step |
|---|---|---|
| Let the platform operate the infrastructure | Volcengine hosted OpenViking | Hosted service entry |
| Run the open-source service yourself | Python, Docker, or the open-source Helm chart | Server deployment |
| Deploy VikingDB / OpenViking on your infrastructure | Kubernetes, Operators, and ovadmin | Enterprise Deployment |
Private delivery has its own components, licensing, and configuration lifecycle. Requirements marked as private delivery do not apply to every OpenViking installation.
For every self-managed installation
| Area | Decide before deployment | Reference |
|---|---|---|
| Workload | Document count and size, vector dimensions, concurrency, ingestion frequency, retention | Observability |
| Models | Provider, model name, API base, credentials, output dimensions, rate limits, timeouts, connectivity from the runtime | Configuration |
| Storage | Persistent workspace location, capacity, permissions, backup destination, restore procedure | Storage, snapshots |
| Network and identity | Client endpoint, TLS, DNS, proxy, administrator and application keys | Public access, authentication |
| Operations | Owners for alerts, upgrades, credentials, and recovery | Diagnostics |
Measure capacity with representative data. A running container or a successful health probe does not demonstrate that the deployment can handle your workload.
Private delivery: versions and environment
Review the environment and version requirements below, then confirm component compatibility against your deployment package.
| Area | Requirement | Verify |
|---|---|---|
| OS / CPU | Linux, x86_64 by default | arm64 requires matching images and binaries |
| Kubernetes | Compatibility matrix specifies 1.24+ | Actual version, CRDs, CNI, CSI, RBAC; no maximum version is declared |
| Helm / kubectl | Helm 3.x, not Helm 4; kubectl within one minor of the cluster | Tool versions on the deployment host |
| Profile | standalone for demos and reproductions; cluster for cluster evaluation | Choose a profile for the environment and verify replicas, scheduling, and recovery |
| Release combination | ovadmin, VikingDB, OpenViking runtime, and Operators form a delivery set | Record ovadmin version --output json; the archive version is not the runtime version |
The package gives a cluster planning reference of at least three machines with 32 CPU cores, 256 GiB RAM, and 2 TiB local disk per machine. These are not minimum requirements for open-source OpenViking or a validated capacity guarantee. Suitability depends on index size, vector dimensions, QPS, build concurrency, replicas, and dependency placement. A three-node deployment that also hosts infrastructure dependencies is a starting point for development, demos, or POCs.
Private delivery: infrastructure checklist
| Area | Confirm |
|---|---|
| Permissions | Deployment kubeconfig; CRD and RBAC creation; Operator access to target namespaces; use the package permission matrix |
| Cluster exclusivity | One private delivery per Kubernetes cluster; see below |
| Namespaces | Application and Operator namespaces, illustrated as vikingdb and viking-system; Secret scope |
| Scheduling | Default cluster selectors are nodeLevel=online / nodeLevel=offline; matching labels, tolerations, and resources |
| Registry | Full repository prefix, delivery tags, pull credentials; validate host login and cluster pulls separately; create repositories first if the Registry does not create them on push (for example Amazon ECR) |
| Storage | Available StorageClass; separate settings for VikingDB data, OpenViking workspace PVCs, and external dependencies |
| Network | Pod / Service DNS, API Server, dependency and model access, cluster DNS suffix, external endpoint and TLS |
| License | Offline: a license file matching the cluster fingerprint. Online: a one-time activation code and the HTTPS license endpoint, reachable from both the deployment host and the cluster. Confirm expiry, renewal, and telemetry arrangements |
Review generated local-path, disk capacity, and node selectors before use. The default OpenViking workspace requests and limits are both 2 CPU / 4 GiB; these are configuration defaults, not workload sizing results.
The VikingDB defaults generated by the cluster profile assume the large machines described above; for example, viking defaults to 2 replicas at 16 CPU / 128 GiB each. Before deploying, add up replicas × requests for every component in vdb.yaml and compare the total with the allocatable capacity of the target node pools. setup apply --dry-run does not check capacity; an oversized plan only shows up after deployment as many Pending Pods.
Cluster exclusivity. The VikingDB / OpenViking CRDs are cluster-scoped, the VikingDB Operator watches all namespaces, the license webhook is always named vikingdb-license-guard.openviking.ai, and the Operator always reads licensing from the viking-system namespace. A second installation in the same cluster, even in a different application namespace, overwrites the CRDs, runs two Operators against the same resources, and competes for the webhook and license Secrets. Use separate clusters for separate environments.
Impact on shared clusters. The managed-workload.openviking.ai entry of the license webhook has no namespace selector. It validates updates and deletions of every Deployment, StatefulSet, and Job labeled app.kubernetes.io/managed-by=Helm in the cluster, with failure policy Fail. While the VikingDB Operator is unavailable, upgrades and deletions of other Helm applications in the cluster are rejected too. Assess this before sharing a cluster with other workloads, and include Operator availability in your operations scope.
The cluster delivery expects infrastructure supplied by the customer or prepared through the delivery plan:
| Component | Package recommendation | Declared minimum / condition |
|---|---|---|
| MySQL | 8.0 | 5.7+ |
| Redis | 6.2.x | No minimum declared |
| Kafka | 3.x | 3.0+ |
| ZooKeeper | 3.7.2 | No minimum declared |
| HDFS | 3.3.x | High-availability topology |
| HBase | 2.5.x | Depends on HDFS and ZooKeeper |
This records the package's compatibility statement, not an ongoing certification. In addition to connectivity, verify databases, topics, namespaces, directories, permissions, and initialization against the bundled infrastructure requirements. Re-run acceptance checks after dependency changes.
The HDFS model directory (default /home/vikingdb_data) must be writable by the identity VikingDB runs as. fermat and other components run as root in their containers and do not set HADOOP_USER_NAME, so under simple authentication they reach HDFS as user root. When HDFS permission checks are enabled and root is not a superuser (for example, the Amazon EMR defaults), grant root write access to the directory; see enterprise deployment.
Model integration checks
- Embedding must return fixed-size dense vectors. Align actual output,
embedding.dense.dimension, and vector database dimensions. - Confirm whether the API base includes
/v1or/api/v3. Text and multimodal embedding may use different paths and request bodies; “OpenAI compatible” alone is insufficient. - VLM / LLM supports understanding, summaries, and memory extraction. Validate image input for image tasks and tool calls for agents that use tools.
- Test authentication, DNS, certificates, and timeouts from the Pod network. Connectivity from a laptop does not establish Pod connectivity.
- Changing embedding models can change vector semantics even when dimensions match. Plan index rebuilding before switching an existing dataset.
In private delivery, OpenVikingWorkspace.spec.vectordb.dimension overrides the template's storage dimension, but does not change embedding.dense.dimension. Check both.
Continue to Enterprise Deployment and upgrades and troubleshooting.