apecloud/kubeblocks-addon-milvus

Deploy Milvus on KubeBlocks

Overview

Deploy Milvus vector database clusters on Kubernetes using KubeBlocks. Milvus powers embedding similarity search and AI applications. Supports standalone mode (single node, dev/test) and cluster mode (distributed, production) with etcd, MinIO, and optional Pulsar/Kafka for log storage.

Official docs: https://kubeblocks.io/docs/preview/kubeblocks-for-milvus/01-overview Quickstart: https://kubeblocks.io/docs/preview/kubeblocks-for-milvus/02-quickstart

Prerequisites

• A running Kubernetes cluster with KubeBlocks installed (see install-kubeblocks)
• The Milvus addon must be enabled:

# Check if milvus addon is installed
helm list -n kb-system | grep milvus

# Install if missing
helm install kb-addon-milvus kubeblocks/milvus --namespace kb-system --version 1.0.0

Available Topologies

| Topology | Value | Components | Use Case | |---|---|---|---| | Standalone | standalone | milvus + etcd + minio | Dev/test, single node | | Cluster | cluster | milvus-proxy, milvus-mixcoord, milvus-datanode, milvus-indexnode, milvus-querynode + etcd + minio (+ pulsar/kafka) | Production, distributed |

Default ports: 19530 (gRPC), 9091 (metrics).

Supported Versions

| Version | serviceVersion | |---|---| | Milvus 2.3 | v2.3.2 | | Milvus 2.5 | v2.5.13 |

List available: kubectl get cmpv milvus

Workflow

- [ ] Step 1: Ensure addon is installed
- [ ] Step 2: Create namespace
- [ ] Step 3: Create cluster (choose topology)
- [ ] Step 4: Dry-run, then apply
- [ ] Step 5: Watch until Running, verify success
- [ ] Step 6: Connect and verify

Step 1: Ensure Addon Is Installed

helm list -n kb-system | grep milvus

If not found:

helm install kb-addon-milvus kubeblocks/milvus --namespace kb-system --version 1.0.0

Step 2: Create Namespace

kubectl create namespace demo --dry-run=client -o yaml | kubectl apply -f -

Step 3: Create Cluster

Standalone (Dev/Test)

Single-node deployment with etcd and MinIO co-located. Suitable for development and testing:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: milvus-standalone
  namespace: demo
spec:
  clusterDef: milvus
  topology: standalone
  terminationPolicy: Delete
  componentSpecs:
    - name: etcd
      replicas: 1
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 20Gi}}
    - name: minio
      replicas: 1
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 20Gi}}
    - name: milvus
      replicas: 1
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 20Gi}}

Cluster (Production)

Distributed deployment with proxy, mixcoord, datanode, indexnode, querynode. Requires pre-created etcd, minio, and optionally Pulsar/Kafka clusters. See cluster topology docs for full setup.

Key components: milvus-proxy (access), milvus-mixcoord (coordination), milvus-datanode, milvus-indexnode, milvus-querynode (compute), plus etcd, minio. Cluster mode uses serviceRef to reference external etcd, minio, and pulsar/kafka clusters.

Step 4: Dry-Run and Apply

Before applying, run server-side dry-run to catch RBAC, webhook, or schema errors:

kubectl apply -f cluster.yaml --dry-run=server

If dry-run succeeds, apply:

kubectl apply -f cluster.yaml

Step 5: Wait for Cluster Ready

kubectl -n demo get cluster <cluster-name> -w

Success condition: STATUS shows Running. Typical duration: 2–5 min. Investigate after 10 min if still Creating/Updating (see safety-patterns).

Check pods:

kubectl -n demo get pods -l app.kubernetes.io/instance=<cluster-name>

Step 6: Connect

Port-Forward (Standalone)

kubectl port-forward pod/<cluster-name>-milvus-0 -n demo 19530:19530

Connect via localhost:19530 (gRPC). For cluster mode, port-forward to the proxy pod.

Verify with Python

from pymilvus import connections
connections.connect(host="localhost", port=19530)

Troubleshooting

Cluster stuck in Creating:

kubectl -n demo describe cluster <cluster-name>
kubectl -n demo get events --sort-by='.lastTimestamp'

Milvus pod not starting:

kubectl -n demo logs <milvus-pod>

etcd or minio dependency issues:

• Ensure etcd and minio pods are Running before milvus starts
• Check component order in componentSpecs

Out of memory:

• Increase resources.limits.memory for milvus component
• For cluster mode, scale datanode/indexnode/querynode resources

Day-2 Operations

| Operation | Skill | External Docs | |---|---|---| | Stop / Start / Restart | cluster-lifecycle | Docs | | Scale CPU / Memory | vertical-scaling | Docs | | Add / Remove replicas | horizontal-scaling | Docs | | Expose externally | expose-service | Docs |

Safety Patterns

Follow safety-patterns: dry-run before apply, confirm success condition after watch, pre-deletion checklist before delete.