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/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/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:
            account: your_azure_storage_account
            key: your_azure_storage_key
----

For information, in previous version of the azure plugin, settings were:

[source,yaml]
----
cloud:
    azure:
        storage_account: your_azure_storage_account
        storage_key: your_azure_storage_key
----

The Azure repository supports following settings:

`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`.

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
    }
}
----
// AUTOSENSE

Example using Java:

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

[[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.

[[repository-azure-testing]]
==== Testing Azure

Integrations tests in this plugin require working Azure configuration and therefore disabled by default.
To enable tests prepare a config file `elasticsearch.yml` with the following content:

[source,yaml]
----
cloud:
  azure:
    storage:
      account: "YOUR-AZURE-STORAGE-NAME"
      key: "YOUR-AZURE-STORAGE-KEY"
----

Replaces `account`, `key` with your settings. Please, note that the test will delete all snapshot/restore related
files in the specified bucket.

To run test:

[source,sh]
----
mvn -Dtests.azure=true -Dtests.config=/path/to/config/file/elasticsearch.yml clean test
----