Skip to content

Commit bb01934

Browse files
lcawllcawl
committed
[DOCS] Identify reloadable Azure repository plugin settings (#46358)
1 parent 4e3ecf0 commit bb01934

File tree

2 files changed

+96
-50
lines changed

2 files changed

+96
-50
lines changed

‎docs/plugins/repository-azure.asciidoc‎

Lines changed: 95 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,6 @@ bin/elasticsearch-keystore add azure.client.default.account
1919
bin/elasticsearch-keystore add azure.client.default.key
2020
----------------------------------------------------------------
2121

22-
Where `account` is the azure account name and `key` the azure secret key. Instead of an azure secret key under `key`, you can alternatively
23-
define a shared access signatures (SAS) token under `sas_token` to use for authentication instead. When using an SAS token instead of an
24-
account key, the SAS token must have read (r), write (w), list (l), and delete (d) permissions for the repository base path and
25-
all its contents. These permissions need to be granted for the blob service (b) and apply to resource types service (s), container (c), and
26-
object (o).
27-
These settings are used by the repository's internal azure client.
28-
2922
Note that you can also define more than one account:
3023

3124
[source,sh]
@@ -36,42 +29,8 @@ bin/elasticsearch-keystore add azure.client.secondary.account
3629
bin/elasticsearch-keystore add azure.client.secondary.sas_token
3730
----------------------------------------------------------------
3831

39-
`default` is the default account name which will be used by a repository,
40-
unless you set an explicit one in the
41-
<<repository-azure-repository-settings, repository settings>>.
42-
43-
The `account`, `key`, and `sas_token` storage settings are
44-
{ref}/secure-settings.html#reloadable-secure-settings[reloadable]. After you
45-
reload the settings, the internal azure clients, which are used to transfer the
46-
snapshot, will utilize the latest settings from the keystore.
47-
48-
NOTE: In progress snapshot/restore jobs will not be preempted by a *reload*
49-
of the storage secure settings. They will complete using the client as it was built
50-
when the operation started.
51-
52-
You can set the client side timeout to use when making any single request. It can be defined globally, per account or both.
53-
It's not set by default which means that Elasticsearch is using the
54-
http://azure.github.io/azure-storage-java/com/microsoft/azure/storage/RequestOptions.html#setTimeoutIntervalInMs(java.lang.Integer)[default value]
55-
set by the azure client (known as 5 minutes).
56-
57-
`max_retries` can help to control the exponential backoff policy. It will fix the number of retries
58-
in case of failures before considering the snapshot is failing. Defaults to `3` retries.
59-
The initial backoff period is defined by Azure SDK as `30s`. Which means `30s` of wait time
60-
before retrying after a first timeout or failure. The maximum backoff period is defined by Azure SDK as
61-
`90s`.
62-
63-
`endpoint_suffix` can be used to specify Azure endpoint suffix explicitly. Defaults to `core.windows.net`.
64-
65-
[source,yaml]
66-
----
67-
azure.client.default.timeout: 10s
68-
azure.client.default.max_retries: 7
69-
azure.client.default.endpoint_suffix: core.chinacloudapi.cn
70-
azure.client.secondary.timeout: 30s
71-
----
72-
73-
In this example, timeout will be `10s` per try for `default` with `7` retries before failing
74-
and endpoint suffix will be `core.chinacloudapi.cn` and `30s` per try for `secondary` with `3` retries.
32+
For more information about these settings, see
33+
<<repository-azure-client-settings>>.
7534

7635
[IMPORTANT]
7736
.Supported Azure Storage Account types
@@ -86,18 +45,104 @@ The Azure Repository plugin works with all Standard storage accounts
8645
https://azure.microsoft.com/en-gb/documentation/articles/storage-premium-storage[Premium Locally Redundant Storage] (`Premium_LRS`) is **not supported** as it is only usable as VM disk storage, not as general storage.
8746
===============================================
8847

89-
You can register a proxy per client using the following settings:
48+
[[repository-azure-client-settings]]
49+
==== Client settings
9050

91-
[source,yaml]
51+
The client that you use to connect to Azure has a number of settings available.
52+
The settings have the form `azure.client.CLIENT_NAME.SETTING_NAME`. By default,
53+
`azure` repositories use a client named `default`, but this can be modified using
54+
the <<repository-azure-repository-settings,repository setting>> `client`.
55+
For example:
56+
57+
[source,js]
9258
----
93-
azure.client.default.proxy.host: proxy.host
94-
azure.client.default.proxy.port: 8888
95-
azure.client.default.proxy.type: http
59+
PUT _snapshot/my_backup
60+
{
61+
"type": "azure",
62+
"settings": {
63+
"client": "secondary"
64+
}
65+
}
9666
----
67+
// CONSOLE
68+
// TEST[skip:we don't have azure setup while testing this]
9769

98-
Supported values for `proxy.type` are `direct` (default), `http` or `socks`.
99-
When `proxy.type` is set to `http` or `socks`, `proxy.host` and `proxy.port` must be provided.
70+
Most client settings can be added to the `elasticsearch.yml` configuration file.
71+
For example:
72+
73+
[source,yaml]
74+
----
75+
azure.client.default.timeout: 10s
76+
azure.client.default.max_retries: 7
77+
azure.client.default.endpoint_suffix: core.chinacloudapi.cn
78+
azure.client.secondary.timeout: 30s
79+
----
10080

81+
In this example, the client side timeout is `10s` per try for the `default`
82+
account with `7` retries before failing. The endpoint suffix is
83+
`core.chinacloudapi.cn` and `30s` per try for the `secondary` account with `3`
84+
retries.
85+
86+
The `account`, `key`, and `sas_token` storage settings are reloadable secure
87+
settings, which you add to the {es} keystore. For more information about
88+
creating and updating the {es} keystore, see
89+
{ref}/secure-settings.html[Secure settings]. After you reload the settings, the
90+
internal Azure clients, which are used to transfer the snapshot, utilize the
91+
latest settings from the keystore.
92+
93+
NOTE: In progress snapshot or restore jobs will not be preempted by a *reload*
94+
of the storage secure settings. They will complete using the client as it was
95+
built when the operation started.
96+
97+
The following list contains the available client settings. Those that must be
98+
stored in the keystore are marked as "secure"; the other settings belong in the
99+
`elasticsearch.yml` file.
100+
101+
`account` ({ref}/secure-settings.html[Secure], {ref}/secure-settings.html#reloadable-secure-settings[reloadable])::
102+
The Azure account name, which is used by the repository's internal Azure client.
103+
104+
`endpoint_suffix`::
105+
The Azure endpoint suffix to connect to. The default value is
106+
`core.windows.net`.
107+
108+
`key` ({ref}/secure-settings.html[Secure], {ref}/secure-settings.html#reloadable-secure-settings[reloadable])::
109+
The Azure secret key, which is used by the repository's internal Azure client. Alternatively, use `sas_token`.
110+
111+
`max_retries`::
112+
The number of retries to use when an Azure request fails. This setting helps
113+
control the exponential backoff policy. It specifies the number of retries
114+
that must occur before the snapshot fails. The default value is `3`. The
115+
initial backoff period is defined by Azure SDK as `30s`. Thus there is `30s`
116+
of wait time before retrying after a first timeout or failure. The maximum
117+
backoff period is defined by Azure SDK as `90s`.
118+
119+
`proxy.host`::
120+
The host name of a proxy to connect to Azure through. For example: `azure.client.default.proxy.host: proxy.host`.
121+
122+
`proxy.port`::
123+
The port of a proxy to connect to Azure through. For example, `azure.client.default.proxy.port: 8888`.
124+
125+
`proxy.type`::
126+
Register a proxy type for the client. Supported values are `direct`, `http`,
127+
and `socks`. For example: `azure.client.default.proxy.type: http`. When
128+
`proxy.type` is set to `http` or `socks`, `proxy.host` and `proxy.port` must
129+
also be provided. The default value is `direct`.
130+
131+
`sas_token` ({ref}/secure-settings.html[Secure], {ref}/secure-settings.html#reloadable-secure-settings[reloadable])::
132+
A shared access signatures (SAS) token, which the repository's internal Azure
133+
client uses for authentication. The SAS token must have read (r), write (w),
134+
list (l), and delete (d) permissions for the repository base path and all its
135+
contents. These permissions must be granted for the blob service (b) and apply
136+
to resource types service (s), container (c), and object (o). Alternatively,
137+
use `key`.
138+
139+
`timeout`::
140+
The client side timeout for any single request to Azure. The value should
141+
specify the time unit. For example, a value of `5s` specifies a 5 second
142+
timeout. There is no default value, which means that {es} uses the
143+
http://azure.github.io/azure-storage-java/com/microsoft/azure/storage/RequestOptions.html#setTimeoutIntervalInMs(java.lang.Integer)[default value]
144+
set by the Azure client (known as 5 minutes). This setting can be defined
145+
globally, per account, or both.
101146

102147
[[repository-azure-repository-settings]]
103148
==== Repository settings

‎docs/reference/setup/secure-settings.asciidoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,7 @@ of reloading after each modification.
122122

123123
There are reloadable secure settings for:
124124

125+
* {plugins}/repository-azure-client-settings.html[The Azure repository plugin]
125126
* {plugins}/discovery-ec2-usage.html#_configuring_ec2_discovery[The EC2 discovery plugin]
126127
* {plugins}/repository-gcs-client.html[The GCS repository plugin]
127128
* {plugins}/repository-s3-client.html[The S3 repository plugin]

0 commit comments

Comments
 (0)