Azure repository

To enable Azure repositories, first configure an Azure repository client by specifying one or more settings of the form azure.client.CLIENT_NAME.SETTING_NAME. By default, azure repositories use a client named default, but you may specify a different client name when registering each repository.

The only mandatory Azure repository client setting is account, which is a secure setting defined in the Elasticsearch keystore. To provide this setting, use the elasticsearch-keystore tool on each node:

bin/elasticsearch-keystore add azure.client.default.account

If you adjust this setting after a node has started, call the Nodes reload secure settings API to reload the new value.

You may define more than one client by setting their account values. For instance, to set the default client and another client called secondary, run the following commands on each node:

bin/elasticsearch-keystore add azure.client.default.account
bin/elasticsearch-keystore add azure.client.secondary.account

The key and sas_token settings are also secure settings and can be set using commands like the following:

bin/elasticsearch-keystore add azure.client.default.key
bin/elasticsearch-keystore add azure.client.secondary.sas_token

Other Azure repository client settings must be set in elasticsearch.yml before the node starts. For example:

azure.client.default.timeout: 10s
azure.client.default.max_retries: 7
azure.client.default.endpoint_suffix: core.chinacloudapi.cn
azure.client.secondary.timeout: 30s

In this example, the client side timeout is 10s per try for repositories which use the default client, with 7 retries before failing and an endpoint suffix of core.chinacloudapi.cn. Repositories which use the secondary client will have a timeout of 30s per try, but will use the default endpoint and will fail after the default number of retries.

Once an Azure repository client is configured correctly, register an Azure repository as follows, providing the client name using the client repository setting:

resp = client.snapshot.create_repository(
    name="my_backup",
    repository={
        "type": "azure",
        "settings": {
            "client": "secondary"
        }
    },
)
print(resp)

const response = await client.snapshot.createRepository({
  name: "my_backup",
  repository: {
    type: "azure",
    settings: {
      client: "secondary",
    },
  },
});
console.log(response);

PUT _snapshot/my_backup
{
  "type": "azure",
  "settings": {
    "client": "secondary"
  }
}

If you are using the default client, you may omit the client repository setting:

resp = client.snapshot.create_repository(
    name="my_backup",
    repository={
        "type": "azure"
    },
)
print(resp)

const response = await client.snapshot.createRepository({
  name: "my_backup",
  repository: {
    type: "azure",
  },
});
console.log(response);

PUT _snapshot/my_backup
{
  "type": "azure"
}

The following list describes the available client settings. Those that must be stored in the keystore are marked as (Secure, reloadable); the other settings must be stored in the elasticsearch.yml file. The default CLIENT_NAME is default but you may configure a client with a different name and specify that client by name when registering a repository.

The Azure repository supports the following settings, which may be specified when registering an Azure repository as follows:

resp = client.snapshot.create_repository(
    name="my_backup",
    repository={
        "type": "azure",
        "settings": {
            "client": "secondary",
            "container": "my_container",
            "base_path": "snapshots_prefix"
        }
    },
)
print(resp)

const response = await client.snapshot.createRepository({
  name: "my_backup",
  repository: {
    type: "azure",
    settings: {
      client: "secondary",
      container: "my_container",
      base_path: "snapshots_prefix",
    },
  },
});
console.log(response);

PUT _snapshot/my_backup
{
  "type": "azure",
  "settings": {
    "client": "secondary",
    "container": "my_container",
    "base_path": "snapshots_prefix"
  }
}

According to the containers naming guide, a container name must be a valid DNS name, conforming to the following naming rules:

The linearizable register implementation for Azure repositories is based on Azure’s support for strongly consistent leases. Each lease may only be held by a single node at any time. The node presents its lease when performing a read or write operation on a protected blob. Lease-protected operations fail if the lease is invalid or expired. To perform a compare-and-exchange operation on a register, Elasticsearch first obtains a lease on the blob, then reads the blob contents under the lease, and finally uploads the updated blob under the same lease. This process ensures that the read and write operations happen atomically.