Back up and restore

Overview

NGINX Instance Manager includes several scripts for backing up and restoring configuration files, secrets, and databases used by the platform.

The backup and restore scripts are provided for reference and may need to be adjusted to suit your specific deployment.

NGINX Instance Manager 2.14.1 and earlier:
If you’re using NGINX Instance Manager version 2.14.1 or earlier, you’ll need to install SQLite to run the backup and recovery scripts.

About nms in commands
Some commands and directories still use nms in their paths or names because they were established when NGINX Instance Manager was part of the NGINX Management Suite. These names remain unchanged in this version for consistency with the existing file structure.

NGINX Instance Manager deployed on a Virtual Machine or Bare Metal

Before you begin

To follow the instructions in this guide, make sure you have the following:

An installed version of NGINX Instance Manager
NGINX Instance Manager 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 Instance Manager host and log in.
Navigate 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 Instance Manager

To back up configuration files, secrets, and databases:

Open a secure shell (SSH) connection to the NGINX Instance Manager host and log in.
Run the following commands to back up NGINX Instance Manager:
```
cd /etc/nms/scripts
sudo ./backup.sh
```
The backup will be saved as a tarball, similar to this example: /tmp/nms-backup-<DATETIME>.tgz.

To restore NGINX Instance Manager:

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

Run the following commands to restore NGINX Instance Manager:

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

NGINX Instance Manager deployed in a Kubernetes Cluster

Before you begin

To complete the steps in this guide, ensure the following:

An installed version of NGINX Instance Manager

Root Access:
You’ll need superuser (sudo) access to run the backup and restore scripts, which use the kubectl command to interact with the Kubernetes API. Ensure that the root user has access to the Kubernetes cluster.

To verify root access to the Kubernetes API, run this command:
```
sudo kubectl -n nms get pods
```
If there are no errors and you see a list of running pods/nodes, root access is confirmed.

If the root user lacks access, configure the Kubernetes API access for root or provide the Kubernetes configuration file path through the KUBECONFIG environment variable:
```
KUBECONFIG=/etc/kubernetes/admin.conf
```
Replace /etc/kubernetes/admin.conf with the actual configuration path for your cluster if it differs.
Utility Pod:
Ensure the utility pod is installed in your Kubernetes cluster:
1. Update your Helm Deployment values.yaml file, adding the following line to enable the utility pod:
```
global:
    utility: true
```
1. Upgrade your NGINX Instance Manager deployment.
2. Download the Helm chart for the installed version of NGINX Instance Manager:
```
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 Instance Manager

To back up NGINX Instance Manager deployed in a Kubernetes cluster:

Copy the backup script k8s-backup.sh from the extracted Helm chart to your working directory:
```
cp nms-<version>/charts/nms-hybrid/backup-restore/k8s-backup.sh .
```
Make the script executable:
```
chmod +x k8s-backup.sh
```
Run the backup script:
```
./k8s-backup.sh
```
Note:
The backup script does not require sudo permissions or the utility pod.
The script will prompt you for the NGINX Instance Manager namespace. It will create a backup archive called k8s-backup-<timestamp>.tar.gz.

Full restoration to the same Kubernetes Cluster

To restore NGINX Instance Manager to the same Kubernetes cluster:

Copy the restore script k8s-restore.sh from the extracted Helm chart to your working directory:
```
cp nms-<version>/charts/nms-hybrid/backup-restore/k8s-restore.sh .
```
Make the script executable:
```
chmod +x k8s-restore.sh
```
Copy your backup file (k8s-backup-<timestamp>.tar.gz) to the same directory as k8s-restore.sh.
Run the restore script:
```
sudo KUBECONFIG=/etc/kubernetes/admin.conf ./k8s-restore.sh -i k8s-backup-<timestamp>.tar.gz -r
```
If the Kubernetes configuration is different, update the path accordingly.

Note:
The restore script requires root access.
After specifying the NGINX Instance Manager namespace, the script will use the provided backup archive.

Note:
The script uses the utility pod to restore databases and core secrets. It stops service pods during the restoration and restarts them afterward.

Data-only restoration to a different Kubernetes Cluster

To restore NGINX Instance Manager to a different Kubernetes cluster:

Copy the restore script k8s-restore.sh from the extracted Helm chart to your working directory:
```
cp nms-<version>/charts/nms-hybrid/backup-restore/k8s-restore.sh .
```
Make the script executable:
```
chmod +x k8s-restore.sh
```
Copy your backup file (k8s-backup-<timestamp>.tar.gz) to the same directory as k8s-restore.sh.
Run the restore script:
```
sudo KUBECONFIG=/etc/kubernetes/admin.conf ./k8s-restore.sh -i k8s-backup-<timestamp>.tar.gz -r -d
```
If the Kubernetes configuration differs, update the path accordingly.

Note:
The restore script requires root access.
After specifying the NGINX Instance Manager namespace, the script will restore the databases and core secrets.

If you want to restore user passwords, extract the backup archive 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.

Refer to ClickHouse’s documentation for backup and restore instructions.

To check your ClickHouse version, run:

clickhouse-server --version

Last modified November 8, 2024