apecloud/kubeblocks-addon-elasticsearch

Deploy Elasticsearch on KubeBlocks

Overview

Deploy Elasticsearch clusters on Kubernetes using KubeBlocks. Elasticsearch is a distributed, RESTful search engine for full-text search, log analytics, and observability. Supports single-node (dev/test) and multi-node topologies.

Official docs: https://kubeblocks.io/docs/preview/kubeblocks-for-elasticsearch/01-overview Quickstart: https://kubeblocks.io/docs/preview/kubeblocks-for-elasticsearch/02-quickstart Operations: https://kubeblocks.io/docs/preview/kubeblocks-for-elasticsearch/04-operations/

Note: Backup and restore are not supported for Elasticsearch in KubeBlocks currently.

Prerequisites

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

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

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

Available Topologies

| Topology | Value | Components | Use Case | |---|---|---|---| | Single-node | (default) | elasticsearch | Dev/test, one node handles all roles | | Multi-node | (default) | elasticsearch | Production, replicas > 1 |

Elasticsearch uses a single topology; the component name is elasticsearch. For single-node mode, set replicas: 1 and configure mode: "single-node" in configs. For production, use replicas: 3 or more.

Supported Versions

| Major | serviceVersion Examples | |---|---| | 6.x | 6.8.23 | | 7.x | 7.10.2, 7.10.1, 7.8.1, 7.7.1 | | 8.x | 8.15.5, 8.8.2, 8.1.3 |

List available versions: kubectl get cmpv elasticsearch

Workflow

- [ ] Step 1: Ensure addon is installed
- [ ] Step 2: Create namespace
- [ ] Step 3: Create cluster (single-node or multi-node)
- [ ] Step 4: Wait for cluster to be ready
- [ ] Step 5: Connect and verify

Step 1: Ensure Addon Is Installed

helm list -n kb-system | grep elasticsearch

If not found:

helm install kb-addon-elasticsearch kubeblocks/elasticsearch --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

Single-Node (Dev/Test)

One node handles all roles (master, data, ingest). Suitable for development:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: es-singlenode
  namespace: demo
spec:
  clusterDef: elasticsearch
  terminationPolicy: Delete
  componentSpecs:
    - name: elasticsearch
      serviceVersion: "8.8.2"
      replicas: 1
      configs:
        - name: es-cm
          variables:
            mode: "single-node"
      resources:
        limits: {cpu: "1", memory: "2Gi"}
        requests: {cpu: "1", memory: "2Gi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 20Gi}}

Multi-Node (Production)

Multiple replicas for high availability and shard distribution:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: es-cluster
  namespace: demo
spec:
  clusterDef: elasticsearch
  terminationPolicy: Delete
  componentSpecs:
    - name: elasticsearch
      serviceVersion: "8.8.2"
      replicas: 3
      resources:
        limits: {cpu: "1", memory: "2Gi"}
        requests: {cpu: "1", memory: "2Gi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 20Gi}}

Key points:

• Do not set mode: "single-node" for multi-node clusters
• Use odd replica counts (3, 5) for master quorum
• Default ports: 9200 (HTTP), 9300 (transport)

Apply with Dry-Run

Per safety-patterns, always dry-run before apply:

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

If dry-run succeeds:

kubectl apply -f cluster.yaml

Step 4: Wait for Cluster Ready

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

Success condition: STATUS shows Running. Typical duration: 1–5 min. If not Running after 10 min, investigate:

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

Check pods:

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

Step 5: Connect and Verify

Port-Forward

kubectl -n demo port-forward svc/<cluster-name>-elasticsearch-http 9200:9200

Health Check

curl -s http://localhost:9200/_cluster/health?pretty

Expected: "status" : "green" or "yellow" (yellow is acceptable for single-node).

Cluster Info

curl -s http://localhost:9200

Troubleshooting

Cluster stuck in Creating:

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

Pod not starting:

kubectl -n demo logs <elasticsearch-pod>
kubectl -n demo describe pod <elasticsearch-pod>

Out of memory:

• Increase resources.limits.memory and resources.requests.memory
• Elasticsearch typically needs at least 2Gi for production

Single-node cluster in yellow:

• Normal for single-node; replicas cannot be allocated. Use multi-node for green status.

Day-2 Operations

Note: Backup and restore are not supported for Elasticsearch in KubeBlocks currently.

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

Safety Patterns

Follow safety-patterns.md for dry-run before apply, status confirmation after watch, and pre-deletion checklist.