Install a NebulaGraph cluster using NebulaGraph Operator¶

Using NebulaGraph Operator to install NebulaGraph clusters enables automated cluster management with automatic error recovery. This topic covers two methods, kubectl apply and helm, for installing clusters using NebulaGraph Operator.

Historical version compatibility

NebulaGraph Operator versions 1.x are not compatible with NebulaGraph versions below 3.x.

Prerequisites¶

Use `kubectl apply`¶

Create a namespace for storing NebulaGraph cluster-related resources. For example, create the nebula namespace.
```
kubectl create namespace nebula
```

Create a YAML configuration file nebulacluster.yaml for the cluster. For example, create a cluster named nebula.

Expand to view an example configuration for the nebula cluster

apiVersion: apps.nebula-graph.io/v1alpha1
kind: NebulaCluster
metadata:
  name: nebula
  namespace: default
spec:
  # Control the Pod scheduling strategy.
  topologySpreadConstraints:
  - topologyKey: "kubernetes.io/hostname"
    whenUnsatisfiable: "ScheduleAnyway"
  # Enable PV recycling.
  enablePVReclaim: false
  # Enable monitoring.
  exporter:
    image: vesoft/nebula-stats-exporter
    version: v3.3.0
    replicas: 1
    maxRequests: 20
  # Custom Agent image for cluster backup and restore, and log cleanup.
  agent:
    image: vesoft/nebula-agent
    version: latest
    resources:
      requests:
        cpu: "100m"
        memory: "128Mi"
      limits:
        cpu: "200m"
        memory: "256Mi"  
  # Configure the image pull policy.
  imagePullPolicy: Always
  # Select the nodes for Pod scheduling.
  nodeSelector:
    nebula: cloud
  # Dependent controller name.
  reference:
    name: statefulsets.apps
    version: v1
  # Scheduler name.
  schedulerName: default-scheduler   
  # Start NebulaGraph Console service for connecting to the Graph service.
  console:
    image: vesoft/nebula-console
    version: nightly
    username: "demo"
    password: "test"                 
  # Graph service configuration. 
  graphd:
  # Used to check if the Graph service is running normally.
  #  readinessProbe:
  #    failureThreshold: 3
  #    httpGet:
  #      path: /status
  #      port: 19669
  #      scheme: HTTP
  #    initialDelaySeconds: 40
  #    periodSeconds: 10
  #    successThreshold: 1
  #    timeoutSeconds: 10
    # Container image for the Graph service.
    image: vesoft/nebula-graphd
    logVolumeClaim:
      resources:
        requests:
          storage: 2Gi
      # Storage class name for storing Graph service logs.
      storageClassName: local-sc
    # Number of replicas for the Graph service Pod.
    replicas: 1
    # Resource configuration for the Graph service.
    resources:
      limits:
        cpu: "1"
        memory: 1Gi
      requests:
        cpu: 500m
        memory: 500Mi
    # Version of the Graph service.
    version: vmaster
    # Custom flags configuration for the Graph service.
    config: {}
  # Meta service configuration.
  metad:
  #  readinessProbe:
  #    failureThreshold: 3
  #    httpGet:
  #      path: /status
  #      port: 19559
  #      scheme: HTTP
  #    initialDelaySeconds: 5
  #    periodSeconds: 5
  #    successThreshold: 1
  #    timeoutSeconds: 5
    # Container image for the Meta service.
    image: vesoft/nebula-metad
    logVolumeClaim:
      resources:
        requests:
          storage: 2Gi
      storageClassName: local-sc
    dataVolumeClaim:
      resources:
        requests:
          storage: 2Gi
      storageClassName: local-sc
    replicas: 1
    resources:
      limits:
        cpu: "1"
        memory: 1Gi
      requests:
        cpu: 500m
        memory: 500Mi
    version: vmaster
    # Custom flags configuration for the Meta service.
    config: {}          
  # Storage service configuration.
  storaged:
  #  readinessProbe:
  #    failureThreshold: 3
  #    httpGet:
  #      path: /status
  #      port: 19779
  #      scheme: HTTP
  #    initialDelaySeconds: 40
  #    periodSeconds: 10
  #    successThreshold: 1
  #    timeoutSeconds: 5
    # Container image for the Storage service.
    image: vesoft/nebula-graphd
    logVolumeClaim:
      resources:
        requests:
          storage: 2Gi
      storageClassName: local-sc
    dataVolumeClaims:
    - resources:
        requests:
          storage: 2Gi
      storageClassName: local-sc
    replicas: 1
    resources:
      limits:
        cpu: "1"
        memory: 1Gi
      requests:
        cpu: 500m
        memory: 500Mi
    version: vmaster
    # Custom flags configuration for the Storage service.
    config: {}

Expand to view all configurable parameters and descriptions

Parameter	Default Value	Description
`metadata.name`	-	The name of the created NebulaGraph cluster.
`spec.console`	-	Launches a Console container for connecting to the Graph service. For configuration details, see nebula-console.
`spec.topologySpreadConstraints`	-	Controls the scheduling strategy for Pods. For more details, see Topology Spread Constraints. When the value of `topologyKey` is `kubernetes.io/zone`, the value of `whenUnsatisfiable` must be set to `DoNotSchedule`, and the value of `spec.schedulerName` should be `nebula-scheduler`.
`spec.graphd.replicas`	`1`	The number of replicas for the Graphd service.
`spec.graphd.image`	`vesoft/nebula-graphd`	The container image for the Graphd service.
`spec.graphd.version`	`master`	The version of the Graphd service.
`spec.graphd.service`		Configuration for accessing the Graphd service via a Service.
`spec.graphd.logVolumeClaim.storageClassName`	-	The storage class name for the log volume claim of the Graphd service. When using sample configuration, replace it with the name of the pre-created storage class. See Storage Classes for creating a storage class.
`spec.metad.replicas`	`1`	The number of replicas for the Metad service.
`spec.metad.image`	`vesoft/nebula-metad`	The container image for the Metad service.
`spec.metad.version`	`master`	The version of the Metad service.
`spec.metad.dataVolumeClaim.storageClassName`	-	Storage configuration for the data disk of the Metad service. When using sample configuration, replace it with the name of the pre-created storage class. See Storage Classes for creating a storage class.
`spec.metad.logVolumeClaim.storageClassName`	-	Storage configuration for the log disk of the Metad service. When using sample configuration, replace it with the name of the pre-created storage class. See Storage Classes for creating a storage class.
`spec.storaged.replicas`	`3`	The number of replicas for the Storaged service.
`spec.storaged.image`	`vesoft/nebula-storaged`	The container image for the Storaged service.
`spec.storaged.version`	`master`	The version of the Storaged service.
`spec.storaged.dataVolumeClaims.resources.requests.storage`	-	The storage size for the data disk of the Storaged service. You can specify multiple data disks. When specifying multiple data disks, the paths are like `/usr/local/nebula/data1`, `/usr/local/nebula/data2`, and so on.
`spec.storaged.dataVolumeClaims.storageClassName`	-	Storage configuration for the data disks of the Storaged service. When using sample configuration, replace it with the name of the pre-created storage class. See Storage Classes for creating a storage class.
`spec.storaged.logVolumeClaim.storageClassName`	-	Storage configuration for the log disk of the Storaged service. When using sample configuration, replace it with the name of the pre-created storage class. See Storage Classes for creating a storage class.
`spec.<metad\|storaged\|graphd>.securityContext`	`{}`	Defines the permission and access control for the cluster containers to control access and execution of container operations. For details, see SecurityContext.
`spec.agent`	`{}`	Configuration for the Agent service used for backup and recovery, and log cleaning functions. If you don't customize this configuration, the default configuration is used.
`spec.reference.name`	`{}`	The name of the controller it depends on.
`spec.schedulerName`	`default-scheduler`	The name of the scheduler.
`spec.imagePullPolicy`	`Always`	The image pull policy for NebulaGraph images. For more details on pull policies, please see Image pull policy.
`spec.logRotate`	`{}`	Log rotation configuration. For details, see Managing Cluster Logs.
`spec.enablePVReclaim`	`false`	Defines whether to automatically delete PVCs after deleting the cluster to release data. For details, see Reclaim PV.
`spec.metad.licenseManagerURL`	-	Configures the URL pointing to the License Manager (LM), consisting of the access address and port (default port `9119`). For example, `192.168.8.xxx:9119`. For creating the NebulaGraph Enterprise Edition only.
`spec.storaged.enableAutoBalance`	`false`	Whether to enable automatic balancing. For details, see Balancing Storage Data After Scaling Out.
`spec.enableBR`	`false`	Defines whether to enable the BR tool. For details, see Backup and Restore.
`spec.imagePullSecrets`	`[]`	Defines the Secret required to pull images from a private repository.

Create the NebulaGraph cluster.
```
kubectl create -f nebulacluster.yaml -n nebula
```
Output:
```
nebulacluster.apps.nebula-graph.io/nebula created
```
If you don't specify the namespace using -n, it will default to the default namespace.

Check the status of the NebulaGraph cluster.

kubectl get nebulaclusters nebula -n nebula

Output:

NAME      READY   GRAPHD-DESIRED   GRAPHD-READY   METAD-DESIRED   METAD-READY   STORAGED-DESIRED   STORAGED-READY   AGE
nebula    True    1                1              1               1             1                  1                86s

Use `helm`¶

Add the NebulaGraph Operator Helm repository (if it's already added, run the next step directly).
```
helm repo add nebula-operator https://vesoft-inc.github.io/nebula-operator/charts
```
Update the Helm repository to fetch the latest resources.
```
helm repo update nebula-operator
```

Set environment variables for the configuration parameters required for installing the cluster.

export NEBULA_CLUSTER_NAME=nebula         # Name of the NebulaGraph cluster.
export NEBULA_CLUSTER_NAMESPACE=nebula    # Namespace for the NebulaGraph cluster.
export STORAGE_CLASS_NAME=local-sc       # StorageClass for the NebulaGraph cluster.

Create a namespace for the NebulaGraph cluster if it is not created.
```
kubectl create namespace "${NEBULA_CLUSTER_NAMESPACE}"
```

Check the customizable configuration parameters for the nebula-cluster Helm chart of the nebula-operator when creating the cluster.

Visit nebula-cluster/values.yaml to see all the configuration parameters for the NebulaGraph cluster.

Run the following command to view all the configurable parameters.

helm show values nebula-operator/nebula-cluster

Example to view all configurable parameters

nebula:
  version: master
  imagePullPolicy: Always
  storageClassName: ""
  enablePVReclaim: false
  enableBR: false
  enableForceUpdate: false
  schedulerName: default-scheduler 
  topologySpreadConstraints:
  - topologyKey: "kubernetes.io/hostname"
    whenUnsatisfiable: "ScheduleAnyway"
  logRotate: {}
  reference:
    name: statefulsets.apps
    version: v1
  graphd:
    image: vesoft/nebula-graphd
    replicas: 2
    serviceType: NodePort
    env: []
    config: {}
    resources:
      requests:
        cpu: "500m"
        memory: "500Mi"
      limits:
        cpu: "1"
        memory: "500Mi"
    logVolume:
      enable: true
      storage: "500Mi"
    podLabels: {}
    podAnnotations: {}
    securityContext: {}
    nodeSelector: {}
    tolerations: []
    affinity: {}
    readinessProbe: {}
    livenessProbe: {}
    initContainers: []
    sidecarContainers: []
    volumes: []
    volumeMounts: []

  metad:
    image: vesoft/nebula-metad
    replicas: 3
    env: []
    config: {}
    resources:
      requests:
        cpu: "500m"
        memory: "500Mi"
      limits:
        cpu: "1"
        memory: "1Gi"
    logVolume:
      enable: true
      storage: "500Mi"
    dataVolume:
      storage: "2Gi"
    licenseManagerURL: ""
    license: {}
    podLabels: {}
    podAnnotations: {}
    securityContext: {}
    nodeSelector: {}
    tolerations: []
    affinity: {}
    readinessProbe: {}
    livenessProbe: {}
    initContainers: []
    sidecarContainers: []
    volumes: []
    volumeMounts: []

  storaged:
    image: vesoft/nebula-storaged
    replicas: 3
    env: []
    config: {}
    resources:
      requests:
        cpu: "500m"
        memory: "500Mi"
      limits:
        cpu: "1"
        memory: "1Gi"
    logVolume:
      enable: true
      storage: "500Mi"
    dataVolumes:
    - storage: "10Gi"
    enableAutoBalance: false
    podLabels: {}
    podAnnotations: {}
    securityContext: {}
    nodeSelector: {}
    tolerations: []
    affinity: {}
    readinessProbe: {}
    livenessProbe: {}
    initContainers: []
    sidecarContainers: []
    volumes: []
    volumeMounts: []

  exporter:
    image: vesoft/nebula-stats-exporter
    version: v3.3.0
    replicas: 1
    env: []
    resources:
      requests:
        cpu: "100m"
        memory: "128Mi"
      limits:
        cpu: "200m"
        memory: "256Mi"
    podLabels: {}
    podAnnotations: {}
    securityContext: {}
    nodeSelector: {}
    tolerations: []
    affinity: {}
    readinessProbe: {}
    livenessProbe: {}
    initContainers: []
    sidecarContainers: []
    volumes: []
    volumeMounts: []
    maxRequests: 20

  agent:
    image: vesoft/nebula-agent
    version: latest
    resources:
      requests:
        cpu: "100m"
        memory: "128Mi"
      limits:
        cpu: "200m"
        memory: "256Mi"

  console:
    username: root
    password: nebula
    image: vesoft/nebula-console
    version: latest
    nodeSelector: {}

  alpineImage: ""

imagePullSecrets: []
nameOverride: ""
fullnameOverride: ""

Expand to view parameter descriptions

Parameter	Default Value	Description
`nebula.version`	master	Version of the cluster.
`nebula.imagePullPolicy`	`Always`	Container image pull policy. `Always` means always attempting to pull the latest image from the remote.
`nebula.storageClassName`	`""`	Name of the Kubernetes storage class for dynamic provisioning of persistent volumes.
`nebula.enablePVReclaim`	`false`	Enable persistent volume reclaim. See Reclaim PV for details.
`nebula.enableBR`	`false`	Enable the backup and restore feature. See Backup and Restore with NebulaGraph Operator for details.
`nebula.enableForceUpdate`	`false`	Force update the Storage service without transferring the leader partition replicas. See Optimize leader transfer in rolling updates for details.
`nebula.schedulerName`	`default-scheduler`	Name of the Kubernetes scheduler. Must be configured as `nebula-scheduler` when using the Zone feature.
`nebula.topologySpreadConstraints`	`[]`	Control the distribution of pods in the cluster.
`nebula.logRotate`	`{}`	Log rotation configuration. See Manage cluster logs for details.
`nebula.reference`	`{"name": "statefulsets.apps", "version": "v1"}`	The workload referenced for a NebulaGraph cluster.
`nebula.graphd.image`	`vesoft/nebula-graphd`	Container image for the Graph service.
`nebula.graphd.replicas`	`2`	Number of replicas for the Graph service.
`nebula.graphd.serviceType`	`NodePort`	Service type for the Graph service, defining how the Graph service is accessed. See Connect to the Cluster for details.
`nebula.graphd.env`	`[]`	Container environment variables for the Graph service.
`nebula.graphd.config`	`{}`	Configuration for the Graph service. See Customize the configuration of the NebulaGraph cluster for details.
`nebula.graphd.resources`	`{"resources":{"requests":{"cpu":"500m","memory":"500Mi"},"limits":{"cpu":"1","memory":"500Mi"}}}`	Resource limits and requests for the Graph service.
`nebula.graphd.logVolume`	`{"logVolume": {"enable": true,"storage": "500Mi"}}`	Log storage configuration for the Graph service. When `enable` is `false`, log volume is not used.
`nebula.metad.image`	`vesoft/nebula-metad`	Container image for the Meta service.
`nebula.metad.replicas`	`3`	Number of replicas for the Meta service.
`nebula.metad.env`	`[]`	Container environment variables for the Meta service.
`nebula.metad.config`	`{}`	Configuration for the Meta service. See Customize the configuration of the NebulaGraph cluster for details.
`nebula.metad.resources`	`{"resources":{"requests":{"cpu":"500m","memory":"500Mi"},"limits":{"cpu":"1","memory":"1Gi"}}}`	Resource limits and requests for the Meta service.
`nebula.metad.logVolume`	`{"logVolume": {"enable": true,"storage": "500Mi"}}`	Log storage configuration for the Meta service. When `enable` is `false`, log volume is not used.
`nebula.metad.dataVolume`	`{"dataVolume": {"storage": "2Gi"}}`	Data storage configuration for the Meta service.
`nebula.metad.licenseManagerURL`	`""`	URL for the license manager (LM) to obtain license information. For creating the NebulaGraph Enterprise Edition only.
`nebula.storaged.image`	`vesoft/nebula-storaged`	Container image for the Storage service.
`nebula.storaged.replicas`	`3`	Number of replicas for the Storage service.
`nebula.storaged.env`	`[]`	Container environment variables for the Storage service.
`nebula.storaged.config`	`{}`	Configuration for the Storage service. See Customize the configuration of the NebulaGraph cluster for details.
`nebula.storaged.resources`	`{"resources":{"requests":{"cpu":"500m","memory":"500Mi"},"limits":{"cpu":"1","memory":"1Gi"}}}`	Resource limits and requests for the Storage service.
`nebula.storaged.logVolume`	`{"logVolume": {"enable": true,"storage": "500Mi"}}`	Log storage configuration for the Storage service. When `enable` is `false`, log volume is not used.
`nebula.storaged.dataVolumes`	`{"dataVolumes": [{"storage": "10Gi"}]}`	Data storage configuration for the Storage service. Supports specifying multiple data volumes.
`nebula.storaged.enableAutoBalance`	`false`	Enable automatic balancing. See Balance storage data after scaling out for details.
`nebula.exporter.image`	`vesoft/nebula-stats-exporter`	Container image for the Exporter service.
`nebula.exporter.version`	`v3.3.0`	Version of the Exporter service.
`nebula.exporter.replicas`	`1`	Number of replicas for the Exporter service.
`nebula.exporter.env`	`[]`	Environment variables for the Exporter service.
`nebula.exporter.resources`	`{"resources":{"requests":{"cpu":"100m","memory":"128Mi"},"limits":{"cpu":"200m","memory":"256Mi"}}}`	Resource limits and requests for the Exporter service.
`nebula.agent.image`	`vesoft/nebula-agent`	Container image for the agent service.
`nebula.agent.version`	`latest`	Version of the agent service.
`nebula.agent.resources`	`{"resources":{"requests":{"cpu":"100m","memory":"128Mi"},"limits":{"cpu":"200m","memory":"256Mi"}}}`	Resource limits and requests for the agent service.
`nebula.console.username`	`root`	Username for accessing the NebulaGraph Console client. See Connect to the cluster for details.
`nebula.console.password`	`nebula`	Password for accessing the NebulaGraph Console client.
`nebula.console.image`	`vesoft/nebula-console`	Container image for the NebulaGraph Console client.
`nebula.console.version`	`latest`	Version of the NebulaGraph Console client.
`nebula.alpineImage`	`""`	Alpine Linux container image used to obtain zone information for nodes.
`imagePullSecrets`	`[]`	Names of secrets to pull private images.
`nameOverride`	`""`	Cluster name.
`fullnameOverride`	`""`	Name of the released chart instance.
`nebula.<graphd\|metad\|storaged\|exporter>.podLabels`	`{}`	Additional labels to be added to the pod.
`nebula.<graphd\|metad\|storaged\|exporter>.podAnnotations`	`{}`	Additional annotations to be added to the pod.
`nebula.<graphd\|metad\|storaged\|exporter>.securityContext`	`{}`	Security context for setting pod-level security attributes, including user ID, group ID, Linux Capabilities, etc.
`nebula.<graphd\|metad\|storaged\|exporter>.nodeSelector`	`{}`	Label selectors for determining which nodes to run the pod on.
`nebula.<graphd\|metad\|storaged\|exporter>.tolerations`	`[]`	Tolerations allow a pod to be scheduled to nodes with specific taints.
`nebula.<graphd\|metad\|storaged\|exporter>.affinity`	`{}`	Affinity rules for the pod, including node affinity, pod affinity, and pod anti-affinity.
`nebula.<graphd\|metad\|storaged\|exporter>.readinessProbe`	`{}`	Probe to check if a container is ready to accept service requests. When the probe returns success, traffic can be routed to the container.
`nebula.<graphd\|metad\|storaged\|exporter>.livenessProbe`	`{}`	Probe to check if a container is still running. If the probe fails, Kubernetes will kill and restart the container.
`nebula.<graphd\|metad\|storaged\|exporter>.initContainers`	`[]`	Special containers that run before the main application container starts, typically used for setting up the environment or initializing data.
`nebula.<graphd\|metad\|storaged\|exporter>.sidecarContainers`	`[]`	Containers that run alongside the main application container, typically used for auxiliary tasks such as log processing, monitoring, etc.
`nebula.<graphd\|metad\|storaged\|exporter>.volumes`	`[]`	Storage volumes to be attached to the service pod.
`nebula.<graphd\|metad\|storaged\|exporter>.volumeMounts`	`[]`	Specifies where to mount the storage volume inside the container.

Create the NebulaGraph cluster.

You can use the --set flag to customize the default values of the NebulaGraph cluster configuration. For example, --set nebula.storaged.replicas=3 sets the number of replicas for the Storage service to 3.

helm install "${NEBULA_CLUSTER_NAME}" nebula-operator/nebula-cluster \ 
    # Specify the version of the cluster chart. If not specified, it will install the latest version by default.
    # You can check all chart versions by running the command: helm search repo -l nebula-operator/nebula-cluster
    --version=1.8.0 \
    # Specify the namespace for the NebulaGraph cluster.
    --namespace="${NEBULA_CLUSTER_NAMESPACE}" \
    # Customize the cluster name.
    --set nameOverride="${NEBULA_CLUSTER_NAME}" \
    --set nebula.storageClassName="${STORAGE_CLASS_NAME}" \
    # Specify the version for the NebulaGraph cluster.
    --set nebula.version=vmaster

Check the status of NebulaGraph cluster pods.

kubectl -n "${NEBULA_CLUSTER_NAMESPACE}" get pod -l "app.kubernetes.io/cluster=${NEBULA_CLUSTER_NAME}"

Output:

NAME                               READY   STATUS    RESTARTS   AGE
nebula-exporter-854c76989c-mp725   1/1     Running   0          14h
nebula-graphd-0                    1/1     Running   0          14h
nebula-graphd-1                    1/1     Running   0          14h
nebula-metad-0                     1/1     Running   0          14h
nebula-metad-1                     1/1     Running   0          14h
nebula-metad-2                     1/1     Running   0          14h
nebula-storaged-0                  1/1     Running   0          14h
nebula-storaged-1                  1/1     Running   0          14h
nebula-storaged-2                  1/1     Running   0          14h

Last update: March 7, 2024

Install a NebulaGraph cluster using NebulaGraph Operator¶

Prerequisites¶

Use kubectl apply¶

Use helm¶

Use `kubectl apply`¶

Use `helm`¶