honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

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
This commit is contained in:
James Rodewig 2020-05-27 10:48:19 -04:00 committed by GitHub
parent 0e34b2f42e
commit 5ae650ecfd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 43 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
docs/reference/snapshot-restore/register-repository.asciidoc
View File

@ -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.
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:
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`
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"]