This is an automated email from the ASF dual-hosted git repository.
houston pushed a commit to branch branch_9_0
in repository https://gitbox.apache.org/repos/asf/solr.git
The following commit(s) were added to refs/heads/branch_9_0 by this push:
new 2521e49 SOLR-16021: Improve docs for S3 location option (#652)
2521e49 is described below
commit 2521e49fea6868e37ff098fdcf890f4e80cce6e3
Author: Houston Putman <[email protected]>
AuthorDate: Mon Feb 21 16:42:54 2022 -0500
SOLR-16021: Improve docs for S3 location option (#652)
(cherry picked from commit 3fba195e16995040ef604efd23cdce137cfc3e74)
---
.../deployment-guide/pages/backup-restore.adoc | 24 +++++++++++++++++++---
.../pages/collection-management.adoc | 16 +++++++++++++--
2 files changed, 35 insertions(+), 5 deletions(-)
diff --git
a/solr/solr-ref-guide/modules/deployment-guide/pages/backup-restore.adoc
b/solr/solr-ref-guide/modules/deployment-guide/pages/backup-restore.adoc
index 70c6267..12ba11f 100644
--- a/solr/solr-ref-guide/modules/deployment-guide/pages/backup-restore.adoc
+++ b/solr/solr-ref-guide/modules/deployment-guide/pages/backup-restore.adoc
@@ -671,9 +671,27 @@ This plugin uses the
https://docs.aws.amazon.com/sdk-for-java/v2/developer-guide
[NOTE]
====
-When using the Backup & Restore Collections API Calls, you can provide a
**location** that either starts with `s3://` or not.
-Either way, if your **location** (or s3 object prefix) starts with a `/`, it
will be removed automatically.
-The repository does not allow backup locations that begin with a `/`.
+There are a few nuances to using the **`location`** option with the S3
Repository.
+The `location` option specifies the sub-directory to store backup information
in.
+
+Location Format::
+When using the Backup & Restore Collections API Calls, the **`location`**
option can be presented in a number of ways:
++
+* `dir/in/bucket`
+* `/dir/in/bucket`
+* `s3:/dir/in/bucket`
+* `s3://dir/in/bucket`
++
+All the above options will resolve to the same directory in your S3 Bucket:
`dir/in/bucket`.
+
+Pre-Creation::
+The location must already exist within your S3 bucket before you can preform
any backup operations with that location.
++
+**Please note that the directory you create in S3 cannot begin with a `/`, as
`locations` are stripped of any `/` prefix (shown in `Location Format`).**
+
+Empty Location::
+If you do not want to use a sub-directory within your bucket to store your
backup, you can use any of the following location options: `/`, `s3:/`, `s3://`.
+However the location option is mandatory and you will recieve an error when
trying to perform backup operations without it.
====
An example configuration to enable S3 backups and restore can be seen below:
diff --git
a/solr/solr-ref-guide/modules/deployment-guide/pages/collection-management.adoc
b/solr/solr-ref-guide/modules/deployment-guide/pages/collection-management.adoc
index 95e0a9b..50e4da6 100644
---
a/solr/solr-ref-guide/modules/deployment-guide/pages/collection-management.adoc
+++
b/solr/solr-ref-guide/modules/deployment-guide/pages/collection-management.adoc
@@ -1569,9 +1569,13 @@ The BACKUP command will backup Solr indexes and
configurations for a specified c
The BACKUP command xref:backup-restore.adoc[takes one copy from each shard for
the indexes].
For configurations, it backs up the configset that was associated with the
collection and metadata.
-Backup data is stored in the repository based on the provided `name` and
`location`.
+Solr ships with backup support for a number of repositories.
+Please refer to the
xref:backup-restore.adoc#backuprestore-storage-repositories[Backup Storage
Repositories] section for a complete list.
+
+Backup data is stored in a directory in the specified repository based on the
provided `name` and `location`.
Each backup location can hold multiple backups for the same collection,
allowing users to later restore from any of these "backup points" as desired.
Within a location backups are done incrementally, so that index files uploaded
previously are skipped and not duplicated in the backup repository.
+Multiple collections cannot be backed up to the same location.
[NOTE]
====
@@ -1616,6 +1620,8 @@ Since any node can take the overseer role at any time, a
best practice to avoid
+
Each backup location can only hold a backup for one collection, however the
same location can be used for repeated backups of the same collection.
Repeated backups of the same collection are done incrementally, so that files
unchanged since the last backup are not duplicated in the backup repository.
++
+If you are using the xref:backup-restore.adoc#s3backuprepository[S3 Backup
Repository], then please read the S3-specific warnings about the `location`
option.
`async`::
+
@@ -1727,6 +1733,8 @@ This parameter is required, unless a default location is
defined on the reposito
+
If the location path is on a mounted drive, the mount must be available on the
node that serves as the overseer, even if the overseer node does not host a
replica of the collection being backed up.
Since any node can take the overseer role at any time, a best practice to
avoid possible backup failures is to ensure the mount point is available on all
nodes of the cluster.
++
+This must be the same value as was given as the `location` option when
<<#backup,creating the backup>>.
`repository`::
+
@@ -1893,7 +1901,9 @@ The name of the existing backup that you want to restore.
|===
+
The location on a shared drive for the RESTORE command to read from.
-Alternately it can be set as a
xref:cluster-node-management.adoc#clusterprop[cluster property].
+Alternately it can be set as a
xref:cluster-node-management.adoc#clusterprop[cluster property].+
++
+This must be the same value as was given as the `location` option when
<<#backup,creating the backup>>.
`async`::
+
@@ -2033,6 +2043,8 @@ This parameter is required, unless a default location is
defined on the reposito
+
If the location path is on a mounted drive, the mount must be available on the
node that serves as the overseer, even if the overseer node does not host a
replica of the collection being backed up.
Since any node can take the overseer role at any time, a best practice to
avoid possible backup failures is to ensure the mount point is available on all
nodes of the cluster.
++
+This must be the same value as was given as the `location` option when
<<#backup,creating the backup>>.
`repository`::
+
