Back Up and Recovery
Follow the steps in this guide to back up and restore the essential system files for the NGINX Management Suite platform and modules.
Overview
-
NGINX Management Suite includes several scripts, which you can run to back up and restore the configuration files, secrets, and databases used by the NGINX Management Suite platform.
-
Additionally, to back up and restore data for specific modules, such as API Connectivity Manager, you can edit the provided scripts and uncomment the commands in the relevant sections.
Important:
The backup and recovery scripts are provided for reference and may need to be adapted to suit the requirements of your deployment.
NGINX Management Suite and modules 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
-
(optional) An installed version of API Connectivity Manager
-
(optional) An installed version of App Delivery Manager
-
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 backup-acm.sh sudo chmod +x restore-acm.sh sudo chmod +x backup-adm.sh sudo chmod +x restore-adm.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
Back Up and Restore Individual Modules
By default, the data for modules isn’t included in backups for NGINX Management Suite. If you’d like to back up the module data, follow these steps:
-
Open a secure shell (SSH) connection to the NGINX Management Suite host and log in.
-
Edit the
backup.sh
andrestore.sh
scripts and uncomment the commands in the relevant sections.To back up and restore data for API Connectivity Manager, uncomment the following lines, like so:
backup.sh: enable backups for API Connectivity Manager
## Back up API Connectivity Manager # Uncomment the following line to back up API Connectivity Manager. ./backup-acm.sh
Uncomment the following section as well:
## Back up API Connectivity Manager # Uncomment the following line to back up API Connectivity Manager. ACM_ACTIVE=$(systemctl is-active --quiet nms-acm) IS_ACM_ACTIVE=$? if [ $IS_ACM_ACTIVE -ne 0 ]; then echo "You need to start the required NGINX Management Suite services before running the backup script." echo "Please ensure the following nms service is running:" echo "nms-acm" exit 1 fi
restore.sh: enable restore for API Connectivity Manager
## Restore the API Connectivity Manager database. # Uncomment the following line to restore API Connectivity Manager. ./restore-acm.sh
To back up and restore data for App Delivery Manager, uncomment the following lines, like so:
This topic documents an early access feature. These features are provided for you to try before they are generally available. You shouldn't use early access features for production purposes.
backup.sh: enable backups for App Delivery Manager
## Back up App Delivery Manager # Uncomment the following line to back up App Delivery Manager. ./backup-adm.sh
restore.sh: enable restore for App Delivery Manager
## Restore the App Delivery Manager database. # Uncomment the following line to restore App Delivery Manager. ./restore-adm.sh
-
To create a backup, run the back up script:
sudo ./backup.sh
-
To restore from a backup:
-
Run
sudo rm -rf /var/lib/nms/dqlite/*
to remove the existing database files. -
Make sure the NGINX Management Suite service is stopped
sudo systemctl stop nms
- Run the restore script:
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
- (optional) An installed version of API Connectivity Manager
- (optional) An installed version of App Delivery Manager
- An installed version of SQLite. Refer to the Install SQLite guide for installation instructions.
-
Root Access
The Kubernetes backup and restore scripts for NGINX Management Suite are executed using
sudo
and use the Kubernetes commandkubectl
internally to access 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 configure 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:-
To back up NGINX Management Suite:
sudo KUBECONFIG=/etc/kubernetes/admin.conf ./k8s-backup.sh
-
To restore NGINX Management Suite:
sudo KUBECONFIG=/etc/kubernetes/admin.conf ./k8s-restore.sh -i <path to backup file> -r
In the examples 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 commands above accordingly. -
-
Utility pod
This topic documents an early access feature. These features are provided for you to try before they are generally available. You shouldn't use early access features for production purposes.
To back up and restore NGINX Management Suite in a Kubernetes cluster, you need to install the
utility
pod in your Kubernetes cluster. Optionally, for each module you want to back up and restore, you need to configure theutility
pod accordingly:-
Update your Helm Deployment values.yaml file, add the
utility: true
line to enable the utility pod, and the required sections undernmsModules
to enable the modules you want to back up and restore. For example, if you have API Connectivity Manager and App Delivery Manager installed, add the following:global: utility: true nmsModules : nsm—acm: enabled: true addClaimsToUtility: true nms—adm : enabled: true addClaimsToUtility: true
-
Upgrade your NGINX Management Suite deployment to apply the changes.
-
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
To back up NGINX Management Suite deployed in a Kubernetes cluster, follow these steps:
-
Copy the extracted backup scripts to your working directory:
- For NGINX Management Suite and API Connectivity Manager, copy
k8s-backup.sh
from thenms-<version>/charts/nms-hybrid/backup-restore/
directory. - (Optional) For App Delivery Manager, copy
k8s-backup-adm.sh
from thenms-<version>/charts/nms-adm/backup-restore/
directory.
cp nms-<version>/charts/nms-hybrid/backup-restore/k8s-backup.sh . cp nms-<version>/charts/nms-adm/backup-restore/k8s-backup-adm.sh .
- For NGINX Management Suite and API Connectivity Manager, copy
-
Make the scripts executable:
chmod +x k8s-backup.sh chmod +x k8s-backup-adm.sh
-
(Optional) For App Delivery Manager modules, uncomment the related section in the
k8s-backup.sh
script as follows:## Back up App Delivery Manager # Uncomment the following lines to back up App Delivery Manager. export PACKAGE_DIR NMS_HELM_NAMESPACE ./k8s-backup-adm.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: Same Kubernetes Cluster
To restore NGINX Management Suite and the installed modules deployed in the same Kubernetes cluster, follow these steps:
-
Copy the extracted backup scripts to your working directory:
- For NGINX Management Suite and API Connectivity Manager, copy
k8s-restore.sh
from thenms-<version>/charts/nms-hybrid/backup-restore/
directory. - (Optional) For App Delivery Management, copy
k8s-restore-adm.sh
from thenms-<version>/charts/nms-adm/backup-restore/
directory.
cp nms-<version>/nms/charts/nms-hybrid/backup-restore/k8s-restore.sh . cp nms-<version>/nms/charts/nms-adm/backup-restore/k8s-restore-adm.sh .
- For NGINX Management Suite and API Connectivity Manager, copy
-
Make the scripts executable:
chmod +x k8s-restore.sh chmod +x k8s-restore-adm.sh
-
Copy your k8s-backup-
.tar.gz file to the same directory as the k8s-restore.sh script. -
Run the restore script:
sudo ./k8s-restore.sh -r -i k8s-backup-<timestamp>.tar.gz
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 consume 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 k8s 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: Restoration to a Different Cluster
To restore NGINX Management Suite and the installed modules into a different Kubernetes cluster, follow these steps:
-
Copy the extracted backup scripts to your working directory:
- For NGINX Management Suite and API Connectivity Manager, copy
k8s-restore.sh
from thenms-<version>/charts/nms-hybrid/backup-restore/
directory. - (Optional) For App Delivery Management, copy
k8s-restore-adm.sh
from thenms-<version>/charts/nms-adm/backup-restore/
directory.
cp nms-<version>/nms/charts/nms-hybrid/backup-restore/k8s-restore.sh . cp nms-<version>/nms/charts/nms-adm/backup-restore/k8s-restore-adm.sh .
- For NGINX Management Suite and API Connectivity Manager, copy
-
Make the scripts executable:
chmod +x k8s-restore.sh chmod +x k8s-restore-adm.sh
-
Copy your k8s-backup-
.tar.gz file to the same directory as the k8s-restore.sh script. -
Run the restore script:
sudo ./k8s-restore.sh -r -i k8s-backup-<timestamp>.tar.gz -d
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 consume the specified backup archive.
The restore script will only restore the databases and core secrets. If you want to restore the user passwords too, run the following commands:
cd nms-<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