Upgrade NebulaGraph clusters created with NebulaGraph Operator

This topic introduces how to upgrade a NebulaGraph cluster created with NebulaGraph Operator.

Legacy version compatibility

The 1.x version NebulaGraph Operator is not compatible with NebulaGraph of version below v3.x.

Limits

• Only for upgrading the NebulaGraph clusters created with NebulaGraph Operator.

• Only support upgrading the NebulaGraph version from 3.5.0 to 3.6.0.

• For upgrading NebulaGraph Enterprise Edition clusters, contact us.

Prerequisites

You have created a NebulaGraph cluster. For details, see Create a NebulaGraph cluster.

Upgrade a NebulaGraph cluster with kubectl

The following steps upgrade a NebulaGraph cluster from version 3.5.0 to v3.8.0.

1. Check the image version of the services in the cluster.

   kubectl get pods -l app.kubernetes.io/cluster=nebula  -o jsonpath="{.items[*].spec.containers[*].image}" |tr -s '[[:space:]]' '\n' |sort |uniq -c
   

   Output:

         1 vesoft/nebula-graphd:3.5.0
         1 vesoft/nebula-metad:3.5.0
         3 vesoft/nebula-storaged:3.5.0  
   

2. Edit the nebula cluster configuration to change the version value of the cluster services from 3.5.0 to v3.8.0.

   1. Open the YAML file for the nebula cluster.

      kubectl edit nebulacluster nebula -n <namespace>
      

   2. Change the value of version.

      After making these changes, the YAML file should look like this:

      apiVersion: apps.nebula-graph.io/v1alpha1
      kind: NebulaCluster
      metadata:
        name: nebula
      spec:
        graphd:
          version: v3.8.0 // Change the value from 3.5.0 to v3.8.0.
          ...
        metad:
          version: v3.8.0 // Change the value from 3.5.0 to v3.8.0.
          ...
        storaged:
          version: v3.8.0 // Change the value from 3.5.0 to v3.8.0.
          ...
      

3. Apply the configuration.

   After saving the YAML file and exiting, Kubernetes automatically updates the cluster's configuration and starts the cluster upgrade.

4. After waiting for about 2 minutes, run the following command to see if the image versions of the services in the cluster have been changed to v3.8.0.

   kubectl get pods -l app.kubernetes.io/cluster=nebula  -o jsonpath="{.items[*].spec.containers[*].image}" |tr -s '[[:space:]]' '\n' |sort |uniq -c
   

   Output:

         1 vesoft/nebula-graphd:v3.8.0
         1 vesoft/nebula-metad:v3.8.0
         3 vesoft/nebula-storaged:v3.8.0 
   

Upgrade a NebulaGraph cluster with helm

1. Update the information of available charts locally from chart repositories.

   helm repo update
   

2. Set environment variables to your desired values.

   export NEBULA_CLUSTER_NAME=nebula         # The desired NebulaGraph cluster name.
   export NEBULA_CLUSTER_NAMESPACE=nebula    # The desired namespace where your NebulaGraph cluster locates.
   

3. Upgrade a NebulaGraph cluster.

   For example, upgrade a cluster to v3.8.0.

   helm upgrade "${NEBULA_CLUSTER_NAME}" nebula-operator/nebula-cluster \
       --namespace="${NEBULA_CLUSTER_NAMESPACE}" \
       --set nameOverride=${NEBULA_CLUSTER_NAME} \
       --set nebula.version=v3.8.0
   

   The value of --set nebula.version specifies the version of the cluster you want to upgrade to.

4. Run the following command to check the status and version of the upgraded cluster.

   Check cluster status:

   $ kubectl -n "${NEBULA_CLUSTER_NAMESPACE}" get pod -l "app.kubernetes.io/cluster=${NEBULA_CLUSTER_NAME}"
   NAME                READY   STATUS    RESTARTS   AGE
   nebula-graphd-0     1/1     Running   0          2m
   nebula-graphd-1     1/1     Running   0          2m
   nebula-metad-0      1/1     Running   0          2m
   nebula-metad-1      1/1     Running   0          2m
   nebula-metad-2      1/1     Running   0          2m
   nebula-storaged-0   1/1     Running   0          2m
   nebula-storaged-1   1/1     Running   0          2m
   nebula-storaged-2   1/1     Running   0          2m
   

   Check cluster version:

   $ kubectl get pods -l app.kubernetes.io/cluster=nebula  -o jsonpath="{.items[*].spec.containers[*].image}" |tr -s '[[:space:]]' '\n' |sort |uniq -c
         1 vesoft/nebula-graphd:v3.8.0
         1 vesoft/nebula-metad:v3.8.0
         3 vesoft/nebula-storaged:v3.8.0
   

Accelerate the upgrade process

The upgrade process of a cluster is a rolling update process and can be time-consuming due to the state transition of the leader partition replicas in the Storage service. You can configure the enableForceUpdate field in the cluster instance's YAML file to skip the leader partition replica transfer operation, thereby accelerating the upgrade process. For more information, see Specify a rolling update strategy.

Troubleshooting

If you encounter issues during the upgrade process, you can check the logs of the cluster service pods.

kubectl logs <pod-name> -n <namespace>

Additionally, you can inspect the cluster's status and events.

kubectl describe nebulaclusters <cluster-name> -n <namespace>

---

Last update: November 10, 2023