1. Operating StreamNative Platform
  2. Maintenance

Backup and restore with metadata tool

StreamNative Platform is a distributed messaging system with multi-layer architecture and uses Apache ZooKeeper as the metadata service. Both StreamNative Platform storage layer and ZooKeeper provide multiple data replicas. To further enhance data fault tolerance and prevent data loss, you can backup and restore with the metadata tool. Currently, the tool enables you to backup and restore Pulsar cluster's metadata to or from the cloud storage.

Backup ZooKeeper metadata

By default, the backup service is disabled. To enable the backup service, you need to set the zookeeper.backup.enable to true, and set the bucket and secrets accordingly in the values.yaml file that you use to deploy your cluster.

To backup ZooKeeper metadata of your cluster, complete the following steps:

  1. Create a bucket in AWS S3 to save the backup files.

  2. Create the credential to access AWS S3.

  3. Create a secret to save your AWS credentials with the following command.

    kubectl create secret generic aws-secret          --from-literal=AWS_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>    --from-literal=AWS_SECRET_ACCESS_KEY=<YOUR_AWS_SECRET_ACCESS_KEY>
  4. Enable backup service in the zookeeper.customTools section in the values.yaml file.

          use: true
          create: true
          name: ''
          annotations: {}
          clusterRole: true
          component: 'backup'
          enable: true
          webServerPort: '8088'
          backupInterval: '600'
          bucket: 's3a://<your-bucket-name>'
          backupPrefix: 'pulsar-backup'
          managedLedgerPath: '/managed-ledgers'
            OPTS: ''
            use: false
              secretName: 'aws-secret'


    If you want to use the AWS Identity and Access Management (IAM) roles to operate the AWS resources, follow the AWS documentation to obtain the Amazon Resource Name (ARN) and then apply the ARN through the serviceAccount.annotations option. In addition, you need to set the backup.configData.secrets.use to false to disable the secret.

  5. Create your cluster with the values.yaml file.

    helm install -f values.yaml <release_name> streamnative/sn-platform --set initialize=true -n <k8s_namespace>
  6. Check whether the backup service is running.

    kubectl get pods <release_name>-restore-pulsar-backup-0

    If the status is running, the backup service starts. You can also check the backup files in your bucket.

Restore metadata from an old cluster

The restore service works only when you start a new cluster by using the old backup metadata, and it only restores data from tiered storage. If a cluster is running, you cannot restore it.

By default, the restore service is disabled. To restore your cluster to a backup point, complete the following steps:

  1. Decide the restore point by finding a restore file from your bucket, for example: s3a://my-backuprestore/pulsar-backup-1623721488825.tar.gz.

  2. Enable the restore service in the ZooKeeper customTools section in the values.yaml file that you use to deploy the cluster.

      component: 'restore'
      enable: true
      restorePoint: 's3a://<your-bucket-name>/<backup-file>'
      restoreVersion: '1'
      bucket: 's3a://<your-bucket-name>'
        OPTS: ''
        use: true
          secretName: 'aws-secret'
  3. Restore your cluster with the values.yaml.

    helm install -f values.yaml <release_name> streamnative/sn-platform  --set initialize=true -n <k8s_namespace>
  4. Check the restore service and make sure that ZooKeeper pods start.

    kubectl get pods | grep zookeeper

    You can also check the topics and namespaces created in the new cluster.


The following table lists the properties, description and default values of the backup and restore services.

PropertyDescriptionDefault value
webServerPortThe backup HTTP service port for metrics and administration.8088
backupIntervalThe backup service running interval. The time unit is measured in seconds.600
bucketThe bucket for saving backup files.s3a://metadata-backup
backupPrefixThe prefix of the backup file name.metadata-backup
managedLedgerPathThe Pulsar managed ledger path in ZooKeeper./managed-ledgers
restorePointThe specific time point that you want to restore your cluster. You can set the restorePoint to a cloud storage file path to restore the cluster with a specified restore point.
restoreVersionA unique number for restoration. If you want to restore the ZooKeeper multiple times with the same restore point, you need to specify a different restore version number for each restore.1


The backup service provides some REST APIs for administration.

/backup/latestGet the latest backup filecurl localhost:8088/backup/latest
/backup/listGet all the backup filescurl localhost:8088/backup/list


The backup service provides the metrics endpoint to monitor the following metrics.

backup_countCounterThe count of running backups.
backup_failure_countCounterThe count of failed backups.
backup_size_non_compressedGaugeThe size of the backup files.
backup_size_compressedGaugeThe size of the backup compressed file.
backup_size_totalGaugeThe size of all the backup compressed files.
backup_execution_time_totalGaugeThe time of the backup execution process.
backup_execution_time_prepareGaugeThe time of the backup preparation process.
backup_execution_time_compressionGaugeThe time of compressing the backup files.
backup_execution_time_uploadGaugeThe time of uploading the backup files.
Restart Clusters