Back up and recovery

Overview

F5 NGINX Management Suite includes several scripts for backing up and restoring the configuration files, secrets, and databases used by the platform.

Important:
The back up and recovery scripts are provided for reference and may need to be changed for your deployment.

NGINX Management Suite deployed in a Virtual Machine or Bare Metal

Before you begin

To complete the instructions in this guide, you need the following:

An installed version of Instance Manager
Instance Manager versions older than 2.15.0 will require an installed version of SQLite. Refer to the Install SQLite guide for installation instructions.
The NGINX Management Suite services must be running:
```
sudo systemctl start nms
```

Make scripts executable

To run the backup and restore scripts, you need to set their permissions to make them executable.

Open a secure shell (SSH) connection to the NGINX Management Suite host and log in.
Change to the directory where the scripts are located:
```
cd /etc/nms/scripts
```

Run the following commands to make the scripts executable:

sudo chmod +x backup.sh
sudo chmod +x restore.sh
sudo chmod +x support-package.sh

Back up and restore NGINX Management Suite

To back up the NGINX Management Suite configuration files, secrets, and databases:

Open a secure shell (SSH) connection to the NGINX Management Suite host and log in.
To back up NGINX Management Suite, run the following commands:
```
cd /etc/nms/scripts
sudo ./backup.sh
```
The backup is saved to a tarball file similar to the following example: /tmp/nms-backup-<DATETIME>.tgz

To restore NGINX Management Suite:

Open a secure shell (SSH) connection to the NGINX Management Suite host and log in.

To restore NGINX Management Suite, run the following commands:

cd /etc/nms/scripts
sudo ./restore.sh /tmp/nms-backup-<DATETIME>.tgz

NGINX Management Suite and modules deployed in a Kubernetes Cluster

Before you begin

To complete the instructions in this guide, you need the following:

An installed version of NGINX Management Suite and Instance Manager
Instance Manager versions older than 2.15.0 will require an installed version of SQLite. Refer to the Install SQLite guide for installation instructions.

Root Access

To back up and restore the NGINX Management Suite on Kubernetes, run the scripts as a superuser with sudo. These scripts use the kubectl command to interact with the Kubernetes API. It is necessary to ensure the target Kubernetes cluster is accessible to the root user.

To confirm that the root user has access to the Kubernetes API, execute the following command:
```
sudo kubectl -n nms get pods
```
If the result is error-free and the output is the list of currently running pods/nodes the root user has the required access.

If the root user does not have the required access, you will need to run the root user to have Kubernetes API access, or provide the script with the location of the Kubernetes configuration via the environment variable KUBECONFIG. For example:
```
 KUBECONFIG=/etc/kubernetes/admin.conf
```
In the example above, /etc/kubernetes/admin.conf is the default configuration location of a Kubernetes cluster. If the configuration location is different for the target Kubernetes cluster, update the location accordingly.
Utility pod

To back up and restore NGINX Management Suite in a Kubernetes cluster, you need to install the utility pod in your Kubernetes cluster:
1. Update your Helm Deployment values.yaml file, add the utility: true line to enable the utility pod under global.
```
global:
    utility: true
```
2. Upgrade your NGINX Management Suite deployment to apply the changes.
3. Download the NGINX Management Suite Helm chart for your currently installed version of NGINX Management Suite:
```
helm repo add nginx-stable https://helm.nginx.com/stable
helm repo update
helm pull nginx-stable/nms
tar zxvf nms-<version>.tgz
```

Back up NGINX Management Suite

To back up NGINX Management Suite deployed in a Kubernetes cluster, follow these steps:

Copy the backup script k8s-backup.sh extracted from nms-<version>.tgz to your working directory:
```
cp nms-<version>/charts/nms-hybrid/backup-restore/k8s-backup.sh .
```
Make the scripts executable:
```
chmod +x k8s-backup.sh
```
Run the backup script:
```
./k8s-backup.sh
```
Note:
The backup script does not need the utility pod or sudo permissions to create a backup.
The command will ask for the NGINX Management Suite namespace. The script will create a backup archive in the same directory called k8s-backup-<timestamp>.tar.gz.

Full restoration to the same Kubernetes Cluster

To restore NGINX Management Suite and the installed modules deployed in the same Kubernetes cluster, follow these steps:

Copy the restore script k8s-restore.sh extracted from nms-<version>.tgz to your working directory:
```
cp nms-<version>/nms/charts/nms-hybrid/backup-restore/k8s-restore.sh .
```
Make the scripts executable:
```
chmod +x k8s-restore.sh
```
Copy your k8s-backup-<timestamp>.tar.gz file to the same directory as the k8s-restore.sh script.
Run the restore script:
```
sudo KUBECONFIG=/etc/kubernetes/admin.conf ./k8s-restore.sh -i k8s-backup-<timestamp>.tar.gz -r
```
In the command above, /etc/kubernetes/admin.conf is the default configuration location of a Kubernetes cluster. If the configuration location is different for the target Kubernetes cluster, update the command accordingly.

Note:
The restore script needs root access to Kubernetes for the restore operation.
The script will ask for the NGINX Management Suite namespace. Once the namespace has been provided, the script will use the specified backup archive.

Note:
The script will use the utility pod to access all the mounted volumes to restore database directories and core secrets; and kubectl to restore the Kubernetes configmaps and secrets. Before starting the restoration, the script will stop all service pods and start the utility pod. After finishing the restore, it will stop the utility pod and start all service pods.

Data-only restoration to a different Kubernetes Cluster

To restore NGINX Management Suite and the installed modules into a different Kubernetes cluster, follow these steps:

Copy the restore script k8s-restore.sh extracted from nms-<version>.tgz to your working directory:
```
cp nms-<version>/nms/charts/nms-hybrid/backup-restore/k8s-restore.sh .
```
Make the scripts executable:
```
chmod +x k8s-restore.sh
```
Copy your k8s-backup-<timestamp>.tar.gz file to the same directory as the k8s-restore.sh script.
Run the restore script:
```
sudo KUBECONFIG=/etc/kubernetes/admin.conf ./k8s-restore.sh -i k8s-backup-<timestamp>.tar.gz -r -d
```
In the command above, /etc/kubernetes/admin.conf is the default configuration location of a Kubernetes cluster. If the configuration location is different for the target Kubernetes cluster, update the command accordingly.

Note:
The restore script needs root access to Kubernetes for the restore operation.
The script will ask for the NGINX Management Suite namespace. Once the namespace has been provided, the script will use the specified backup archive.

The restore script will only restore the databases and core secrets. If you want to restore the user passwords too, extract the k8s-backup-<timestamp>.tar.gz file and run the following commands:

cd k8s-backup-<version>/secrets
kubectl -n nms apply -f nms-auth.json
kubectl -n nms delete pod apigw-<hash>

ClickHouse

ClickHouse supports backup and restore on versions greater than v22.

For instructions on how to back up and restore the ClickHouse database, please refer to ClickHouse’s documentation.

To check your ClickHouse version, run the following command:

clickhouse-server --version

Last modified August 22, 2024