udpated restore docs, closes #2333, closes #2335

influxdata · Mar 25, 2021 · 62e1d3e · 62e1d3e
1 parent 668a0c8
commit 62e1d3e
Show file tree

Hide file tree

Showing 3 changed files with 112 additions and 19 deletions.
diff --git a/content/influxdb/v2.0/backup-restore/restore.md b/content/influxdb/v2.0/backup-restore/restore.md
@@ -20,25 +20,103 @@ Use the `influx restore` command to restore backup data and metadata from Influx
 The `influx restore` command only restores data to InfluxDB OSS, **not {{< cloud-name "short" >}}**.
 {{% /cloud %}}
 
-When restoring data from a backup file set, InfluxDB temporarily moves existing
-data and metadata while the restore process runs.
-Once the process completes, the temporary data is deleted.
+- [Restore data with the influx CLI](#restore-data-with-the-influx-cli)
+- [Recover from a failed restore](#recover-from-a-failed-restore)
+
+When restoring data from a backup file set, InfluxDB temporarily moves existing data and metadata.
+Once the process completes, InfluxDB deletes the temporary data.
 If the restore process fails, InfluxDB preserves the data in the temporary location.
 _See [Recover from a failed restore](#recover-from-a-failed-restore)._
 
+{{% note %}}
+#### Cannot restore to existing buckets
+The `influx restore` command cannot restore data to existing buckets.
+Use the `--new-bucket` flag to specify the new bucket to restore data to.
+To restore data and retain bucket names, [delete existing buckets](/influxdb/v2.0/organizations/buckets/delete-bucket/)
+and then begin the restore process.
+{{% /note %}}
+
 ## Restore data with the influx CLI
-Use the `influx restore` command and specify the path to the backup directory in the first argument.
+Use the `influx restore` command and specify the path to the backup directory.
+
+_For more information about restore options and flags, see the
+[`influx restore` documentation](/influxdb/v2.0/reference/cli/influx/restore/)._
+
+- [Restore all time series data](#restore-all-time-series-data)
+- [Restore data from a specific bucket](#restore-data-from-a-specific-bucket)
+- [Restore and replace all InfluxDB data](#restore-and-replace-all-influxdb-data)
+
+### Restore all time series data
+To restore all time series data from a bucket directory into buckets with the
+same name as the backup source buckets, provide the following:
+
+- backup directory path
+
+```sh
+influx restore \
+  --input /backups/2020-01-20_12-00/
+```
+
+### Restore data from a specific bucket
+To restore data from a specific bucket in a backup directory, provide the following:
+
+- backup directory path
+- bucket name or ID
+
+```sh
+influx restore \
+  --input /backups/2020-01-20_12-00/ \
+  --bucket example-bucket
+
+# OR
+
+influx restore \
+  --input /backups/2020-01-20_12-00/ \
+  --bucket-id 000000000000
+```
+
+If a bucket with the same name as the backed up bucket already exists, use the
+`--new-bucket` flag to specify a new bucket to restore the data to.
 
 ```sh
-# Syntax
-influx restore <path-to-backup-directory>
+influx restore \
+  --input /backups/2020-01-20_12-00/ \
+  --bucket example-bucket \
+  --new-bucket new-example-bucket
+```
+
+### Restore and replace all InfluxDB data
+To restore and replace all time series data _and_ InfluxDB key-value data such as
+tokens, users, dashboards, etc., include the following:
 
-# Example
-influx restore ~/backups/2020-01-20_12-00/
+- `--full` flag
+- backup directory path
+
+```sh
+influx restore \
+  --input /backups/2020-01-20_12-00/ \
+  --full
 ```
 
-_For more information about restore options and flags, see the
-[`influx restore` documentation](/influxdb/v2.0/reference/cli/influx/restore/)._
+{{% note %}}
+#### Restore to a brand new InfluxDB server
+If using a backup to populate a new InfluxDB server:
+
+1. Retrieve the [admin token](/influxdb/v2.0/security/tokens/#admin-token) from your source InfluxDB instance.
+2. Set up your new InfluxDB instance, but use the `-t`, `--token` flag to use the
+   **admin token** from your source instance as the admin token on your new instance.
+
+    ```sh
+    influx setup --token My5uP3rSecR37t0keN
+    ```
+3. Restore the backup to the new server.
+
+    ```sh
+    influx restore \
+      --input /backups/2020-01-20_12-00/ \
+      --full
+    ```
+{{% /note %}}
 
 
 ## Recover from a failed restore

diff --git a/content/influxdb/v2.0/reference/cli/influx/backup/_index.md b/content/influxdb/v2.0/reference/cli/influx/backup/_index.md
@@ -9,6 +9,7 @@ weight: 101
 influxdb/v2.0/tags: [backup]
 related:
   - /influxdb/v2.0/backup-restore/backup/
+  - /influxdb/v2.0/reference/cli/influx/restore/
   - /influxdb/v2.0/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials
   - /influxdb/v2.0/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions
 ---

diff --git a/content/influxdb/v2.0/reference/cli/influx/restore/index.md b/content/influxdb/v2.0/reference/cli/influx/restore/index.md
@@ -10,6 +10,7 @@ alias:
   - /influxdb/v2.0/reference/cli/influxd/restore/
 related:
   - /influxdb/v2.0/backup-restore/restore/
+  - /influxdb/v2.0/reference/cli/influx/backup/
   - /influxdb/v2.0/reference/cli/influx/#provide-required-authentication-credentials, influx CLI—Provide required authentication credentials
   - /influxdb/v2.0/reference/cli/influx/#flag-patterns-and-conventions, influx CLI—Flag patterns and conventions
 ---
@@ -25,6 +26,14 @@ If the restore process fails, InfluxDB preserves the data in the temporary locat
 _For information about recovering from a failed restore process, see
 [Restore data](/influxdb/v2.0/backup-restore/restore/#recover-from-a-failed-restore)._
 
+{{% note %}}
+#### Cannot restore to existing buckets
+The `influx restore` command cannot restore data to existing buckets.
+Use the `--new-bucket` flag to specify the new bucket to restore data to.
+To restore data and retain bucket names, [delete existing buckets](/influxdb/v2.0/organizations/buckets/delete-bucket/)
+and then begin the restore process.
+{{% /note %}}
+
 ## Usage
 
 ```
@@ -56,25 +65,30 @@ influx restore [flags]
 
 {{< cli/influx-creds-note >}}
 
+- [Restore backup data](#restore-backup-data)
+- [Restore backup data for a specific bucket into a new bucket](#restore-backup-data-for-a-specific-bucket-into-a-new-bucket)
 - [Restore and replace all data](#restore-and-replace-all-data)
-- [Restore backup data to an existing bucket](#restore-backup-data-to-an-existing-bucket)
-- [Create a bucket and restore data to it](#create-a-bucket-and-restore-data-to-it)
 
-##### Restore and replace all data
+##### Restore backup data
 ```sh
-influx restore --full --input /path/to/backup/dir/
+influx restore \
+  --input /path/to/backup/dir/
 ```
 
-##### Restore backup data to an existing bucket
+##### Restore backup data for a specific bucket into a new bucket
 ```sh
 influx restore \
   --bucket example-bucket \
+  --new-bucket new-example-bucket \
   --input /path/to/backup/dir/
 ```
 
-##### Create a bucket and restore data to it
+##### Restore and replace all data
+{{% note %}}
+`influx restore --full` restores all time series data _and_ InfluxDB key-value
+data such as tokens, dashboards, users, etc.
+{{% /note %}}
+
 ```sh
-influx restore \
-  --new-bucket new-example-bucket \
-  --input /path/to/backup/dir/
+influx restore --full --input /path/to/backup/dir/
 ```