Browse Source

[DOCS] Fix clarity of URL snapshot repo docs (#56920)

Makes following changes to better clarify docs for read-only URL
snapshot repositories:

* Adds an example snippet for registering a URL repository
* Rewrites the protocols paragraph
* Adds a note to explicitly point out that only URLs using the `ftp`,
  `http`, `http`, and `jar` protocols do not need the `path.repo`
  setting.

Fixes #16280
James Rodewig 5 years ago
parent
commit
626f67e651
1 changed files with 43 additions and 12 deletions
  1. 43 12
      docs/reference/snapshot-restore/register-repository.asciidoc

+ 43 - 12
docs/reference/snapshot-restore/register-repository.asciidoc

@@ -163,24 +163,55 @@ unit, for example: `1GB`, `10MB`, `5KB`, `500B`. Defaults to `null` (unlimited c
 [[snapshots-read-only-repository]]
 === Read-only URL repository
 
-The URL repository (`"type": "url"`) can be used as an alternative read-only way to access data created by the shared file
-system repository. The URL specified in the `url` parameter should point to the root of the shared filesystem repository.
-The following settings are supported:
+If you register the same snapshot repository with multiple clusters, only one
+cluster should have write access to the repository. Having multiple clusters
+write to the repository at the same time risks corrupting the contents of the
+repository.
 
-[horizontal]
-`url`:: Location of the snapshots. Mandatory.
+To reduce this risk, you can use URL repositories (`"type": "url"`) to give one
+or more clusters read-only access to a shared file system repository. As URL
+repositories are always read-only, they are a safer and more convenient
+alternative to registering a read-only shared filesystem repository.
+
+The URL specified in the `url` parameter should point to the root of the shared
+filesystem repository.
+
+[source,console]
+----
+PUT /_snapshot/my_read_only_url_repository
+{
+  "type": "url",
+  "settings": {
+    "url": "file:/mount/backups/my_fs_backup_location"
+  }
+}
+----
+// TEST[skip:no access to url file path]
+
+The `url` parameter supports the following protocols:
+
+* `file`
+* `ftp`
+* `http`
+* `https`
+* `jar`
 
-URL Repository supports the following protocols: "http", "https", "ftp", "file" and "jar". URL repositories with `http:`,
-`https:`, and `ftp:` URLs has to be whitelisted by specifying allowed URLs in the `repositories.url.allowed_urls` setting.
-This setting supports wildcards in the place of host, path, query, and fragment. For example:
+URLs using the `file` protocol must point to the location of a shared filesystem
+accessible to all master and data nodes in the cluster. This location must be
+registered in the `path.repo` setting, similar to a
+<<snapshots-filesystem-repository,shared file system repository>>.
+
+URLs using the `ftp`, `http`, or `https` protocols must be whitelisted in the
+`repositories.url.allowed_urls` setting. This setting supports wildcards (`*`)
+in place of a host, path, query, or fragment in the URL. For example:
 
 [source,yaml]
------------------------------------
+----
 repositories.url.allowed_urls: ["http://www.example.org/root/*", "https://*.mydomain.com/*?*#*"]
------------------------------------
+----
 
-URL repositories with `file:` URLs can only point to locations registered in the `path.repo` setting similar to
-shared file system repository.
+NOTE: URLs using the `ftp`, `http`, `https`, or `jar` protocols do not need to
+be registered in the `path.repo` setting.
 
 [float]
 [role="xpack"]