Chapter 2. Restoring from a backup
You can restore Red Hat Advanced Cluster Security for Kubernetes from an existing backup by using the roxctl command-line interface (CLI).
Depending upon your requirements and the data you have backed up, you can restore from the following types of backups:
- Restore Central database from the Central database backup: Use this to recover from a database failure or data corruption event. It allows you to restore and recover the Central database to its earlier functional state.
- Restore Central from the Central deployment backup: Use this if you are migrating Central to another cluster or namespace. This option restores the configurations of your Central installation.
2.1. Restoring Central database by using the roxctl CLI
You can use the roxctl CLI to restore Red Hat Advanced Cluster Security for Kubernetes by using the restore command. You require an API token or your administrator password to run this command.
2.1.1. Restoring by using an API token
You can restore the entire database of Red Hat Advanced Cluster Security for Kubernetes by using an API token.
Prerequisites
- You must have a Red Hat Advanced Cluster Security for Kubernetes backup file.
- You must have an API token with the administrator role.
-
You must have installed the
roxctlCLI.
Procedure
Set the
ROX_API_TOKENand theROX_CENTRAL_ADDRESSenvironment variables:$ export ROX_API_TOKEN=<api_token>
$ export ROX_CENTRAL_ADDRESS=<address>:<port_number>
Run the
restorecommand:$ roxctl -e "$ROX_CENTRAL_ADDRESS" central db restore <backup_file>
2.1.2. Restoring by using the administrator password
You can restore the entire database of Red Hat Advanced Cluster Security for Kubernetes by using your administrator password.
Prerequisites
- You must have a Red Hat Advanced Cluster Security for Kubernetes backup file.
- You must have the administrator password.
-
You must have installed the
roxctlCLI.
Procedure
Set the
ROX_CENTRAL_ADDRESSenvironment variable:$ export ROX_CENTRAL_ADDRESS=<address>:<port_number>
Run the
restorecommand:$ roxctl -p <admin_password> -e "$ROX_CENTRAL_ADDRESS" central db restore <backup_file>
2.1.3. Resuming the restore operation
During a restore operation, if your connection is interrupted or you need to go offline, you can resume the restore operation.
-
If you do not have access to the machine running the resume operation, use the
roxctl central db restore statuscommand to check the status of an ongoing restore operation. -
In case of connection interruptions, the
roxctlCLI automatically tries to restore a task when the connection becomes available. The automatic connection retries depend on the duration specified by thetimeoutoption. -
Use the
--timeoutoption to specify the time in seconds, minutes, or hours, after which theroxctlCLI stops trying to resume a restore operation. If not specified, the default timeout is 10 minutes (10m). -
If a restore operation is stuck or if you want to cancel it, use the
roxctl central db restore cancelcommand to cancel an ongoing restore operation. - If a restore operation is stuck, or you have canceled it, or it timed out, you can resume the previous restore by re-running the original command.
- During interruptions, Red Hat Advanced Cluster Security for Kubernetes caches an ongoing restore operation for 24 hours. You can resume this operation by re-running the original restore command.
-
The
--timeoutoption only governs client-side connection retries and does not affect the 24 hours server-side restore cache. - You cannot resume restore operations across restarts of the Central pod.
- If a restore operation is interrupted, you must restart it within 24 hours and before Central restarts, otherwise Red Hat Advanced Cluster Security for Kubernetes cancels the restore operation.
2.2. Restoring Central deployment using the roxctl CLI
You can restore your Central deployment to its original configuration by using the backups you made.
You must first restore certificates by using the roxctl CLI, and then restore the Central deployment by running the Central installation scripts.
2.2.1. Restore certificates using the roxctl CLI
Use the roxctl CLI to generate Kubernetes manifests to install the RHACS Central component to your cluster. Doing this allows you to ensure that authentication certificates for Secured clusters and the API tokens remain valid for the restored version. If you backed up another instance of RHACS Central, you can use the certificate files from that backup.
With the roxctl CLI, you can not restore the entire Central deployment. Instead, first you use the roxctl CLI to generate new manifests using the certificates in your central data backup. Afterwards, you use those manifests to install Central.
Prerequisites
- You must have the Red Hat Advanced Cluster Security for Kubernetes backup file.
-
You must have installed the
roxctlCLI.
Procedure
Run the interactive install command:
$ roxctl central generate interactive
For the following prompt, enter the path of the Red Hat Advanced Cluster Security for Kubernetes backup file:
Enter path to the backup bundle from which to restore keys and certificates (optional): _<backup-file-path>_
- For other following prompts, press Enter to accept the default value or enter custom values as required.
On completion, the interactive install command creates a folder named central-bundle, which has the necessary YAML manifests and scripts to deploy Central.
2.2.2. Running the Central installation scripts
After you run the interactive installer, you can run the setup.sh script to install Central.
Procedure
Run the
setup.shscript to configure image registry access:$ ./central-bundle/central/scripts/setup.sh
Create the necessary resources:
$ oc create -R -f central-bundle/central
Check the deployment progress:
$ oc get pod -n stackrox -w
After Central is running, find the RHACS portal IP address and open it in your browser. Depending on the exposure method you selected when answering the prompts, use one of the following methods to get the IP address.
Exposure method Command Address Example Route
oc -n stackrox get route centralThe address under the
HOST/PORTcolumn in the outputhttps://central-stackrox.example.routeNode Port
oc get node -owide && oc -n stackrox get svc central-loadbalancerIP or hostname of any node, on the port shown for the service
https://198.51.100.0:31489Load Balancer
oc -n stackrox get svc central-loadbalancerEXTERNAL-IP or hostname shown for the service, on port 443
https://192.0.2.0None
central-bundle/central/scripts/port-forward.sh 8443https://localhost:8443https://localhost:8443
If you have selected autogenerated password during the interactive install, you can run the following command to see it for logging into Central:
$ cat central-bundle/password
2.3. Restore Central deployment using the RHACS Operator
You can restore your Central deployment to its original configuration by using the RHACS Operator. To successfully restore, you need the backup of your Central custom resource, central-tls, and the administrator password.
Prerequisites
-
You must have the
central-tlsbackup file. - You must have the Central custom resource backup file.
- You must have the administrator password backup file.
Procedure
Use the
central-tlsbackup file to create resources:$ oc apply -f central-tls.json
Use the
central-htpasswdbackup file to create secrets:$ oc apply -f central-htpasswd.json
Use the
central-cr.yamlfile to create the Central deployment:$ oc apply -f central-cr.yaml
2.4. Restore Central deployment using Helm
You can restore your Central deployment to its original configuration by using Helm. To successfully restore, you need the backup of your Central custom resource, the central-tls secret, and the administrator password.
Prerequisites
- You must have the Helm values backup file.
- You must have a Red Hat Advanced Cluster Security for Kubernetes backup file.
-
You must have installed the
roxctlCLI.
Procedure
Generate
values-private.yamlfrom the RHACS database backup file:$ roxctl central generate k8s pvc --backup-bundle _<path-to-backup-file>_ --output-format "helm-values"
Run the
helm installcommand and specify your backup files:$ helm install -n stackrox --create-namespace stackrox-central-services rhacs/central-services -f central-values-backup.yaml -f central-bundle/values-private.yaml
2.5. Restoring central to another cluster or namespace
You can use the backups of the RHACS Central database and the deployment to restore Central to another cluster or namespace.
The following list provides a high-level overview of installation steps:
Depending upon your installation method, you must first restore Central deployment by following the instructions in the following topics:
Important- Make sure to use the backed-up Central certificates so that secured clusters and API tokens issued by the old Central instance remain valid.
- If you are deploying to another namespace, you must change the namespace in backed-up resources or commands.
- Restore Central database by following the instruction in the Restoring Central database by using the roxctl CLI topic.
- If you have an external DNS entry pointing to your old RHACS Central instance, you must reconfigure it to point to the new RHACS Central instance that you create.