OpenSearch/docs/plugins/repository-azure.asciidoc

[[repository-azure]]
=== Azure Repository Plugin

The Azure Repository plugin adds support for using Azure as a repository for
{ref}/modules-snapshots.html[Snapshot/Restore].

[[repository-azure-install]]
[float]
==== Installation

This plugin can be installed using the plugin manager:

[source,sh]
----------------------------------------------------------------
sudo bin/elasticsearch-plugin install repository-azure
----------------------------------------------------------------

The plugin must be installed on every node in the cluster, and each node must
be restarted after installation.

[[repository-azure-remove]]
[float]
==== Removal

The plugin can be removed with the following command:

[source,sh]
----------------------------------------------------------------
sudo bin/elasticsearch-plugin remove repository-azure
----------------------------------------------------------------

The node must be stopped before removing the plugin.

[[repository-azure-usage]]
==== Azure Repository

To enable Azure repositories, you have first to set your azure storage settings in `elasticsearch.yml` file:

[source,yaml]
----
cloud:
    azure:
        storage:
            my_account:
                account: your_azure_storage_account
                key: your_azure_storage_key
----

Note that you can also define more than one account:

[source,yaml]
----
cloud:
    azure:
        storage:
            my_account1:
                account: your_azure_storage_account1
                key: your_azure_storage_key1
                default: true
            my_account2:
                account: your_azure_storage_account2
                key: your_azure_storage_key2
----

`my_account1` is the default account which will be used by a repository unless you set an explicit one.

You can set the timeout to use when making any single request. It can be defined globally, per account or both.
Defaults to `5m`.

[source,yaml]
----
cloud:
    azure:
        storage:
            timeout: 10s
            my_account1:
                account: your_azure_storage_account1
                key: your_azure_storage_key1
                default: true
            my_account2:
                account: your_azure_storage_account2
                key: your_azure_storage_key2
                timeout: 30s
----

In this example, timeout will be 10s for `my_account1` and 30s for `my_account2`.

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

The Azure repository supports following settings:

`account`::

    Azure account settings to use. Defaults to the only one if you set a single
    account or to the one marked as `default` if you have more than one.

`container`::

    Container name. Defaults to `elasticsearch-snapshots`

`base_path`::

    Specifies the path within container to repository data. Defaults to empty
    (root directory).

`chunk_size`::

    Big files can be broken down into chunks during snapshotting if needed.
    The chunk size can be specified in bytes or by using size value notation,
    i.e. `1g`, `10m`, `5k`. Defaults to `64m` (64m max)

`compress`::

    When set to `true` metadata files are stored in compressed format. This
    setting doesn't affect index files that are already compressed by default.
    Defaults to `false`.

`read_only`::

    Makes repository read-only. coming[2.1.0]  Defaults to `false`.

`location_mode`::

    `primary_only` or `secondary_only`. Defaults to `primary_only`. Note that if you set it
    to `secondary_only`, it will force `read_only` to true.

Some examples, using scripts:

[source,json]
----
# The simpliest one
PUT _snapshot/my_backup1
{
    "type": "azure"
}

# With some settings
PUT _snapshot/my_backup2
{
    "type": "azure",
    "settings": {
        "container": "backup-container",
        "base_path": "backups",
        "chunk_size": "32m",
        "compress": true
    }
}


# With two accounts defined in elasticsearch.yml (my_account1 and my_account2)
PUT _snapshot/my_backup3
{
    "type": "azure",
    "settings": {
        "account": "my_account1"
    }
}
PUT _snapshot/my_backup4
{
    "type": "azure",
    "settings": {
        "account": "my_account2",
        "location_mode": "primary_only"
    }
}
----
// AUTOSENSE

Example using Java:

[source,java]
----
client.admin().cluster().preparePutRepository("my_backup_java1")
    .setType("azure").setSettings(Settings.settingsBuilder()
        .put(Storage.CONTAINER, "backup-container")
        .put(Storage.CHUNK_SIZE, new ByteSizeValue(32, ByteSizeUnit.MB))
    ).get();
----

[[repository-azure-global-settings]]
===== Global repositories settings

All those repository settings can also be defined globally in `elasticsearch.yml` file using prefix
`repositories.azure.`. For example:

[source,yaml]
----
repositories.azure:
    container: backup-container
    base_path: backups
    chunk_size: 32m
    compress": true
----


[[repository-azure-validation]]
===== Repository validation rules

According to the http://msdn.microsoft.com/en-us/library/dd135715.aspx[containers naming guide], a container name must
be a valid DNS name, conforming to the following naming rules:

* Container names must start with a letter or number, and can contain only letters, numbers, and the dash (-) character.
* Every dash (-) character must be immediately preceded and followed by a letter or number; consecutive dashes are not
permitted in container names.
* All letters in a container name must be lowercase.
* Container names must be from 3 through 63 characters long.