.. _ref-fs-s3:

=========
Amazon S3
=========

Pour qu'un fichier soit déposé et/ou lu depuis un serveur cloud de type S3, il
faut que le chemin complet du fichier (après concaténation des éventuels chemins
de règle et/ou de serveur) forme un chemin distant ayant la syntaxe : ::

   instance:chemin/du/fichier

Pour ce faire, l'instance en question doit avoir été pré-configurée dans Waarp 
Transfer, par exemple via la :ref:`commande CLI<reference-cli-client-cloud>`.

Identifiants
------------

Pour se connecter à une instance S3, Waarp Transfer a besoin d'identifiants.
Ces identifiants peuvent être fournis de 2 manières différentes :

- soit en les renseignant directement à la création de l'instance cloud
- soit en les renseignant dans des variables d'environnement

Ces variables d'environnement sont :

- :envvar:`AWS_ACCESS_KEY_ID` pour la clé d'accès AWS
- :envvar:`AWS_SECRET_ACCESS_KEY` pour la clé secrète associée à la clé d'accès

Options
-------

Waarp Transfer permet de stocker les fichier envoyés et reçu sur un serveur cloud
de stockage S3 (AWS ou autre). Pour cela, l'instance cloud à créer doit contenir
les options suivantes :

* **bucket**: *REQUIS* - Le nom du bucket dans lequel le fichier sera déposé.
* **region**: La région du serveur S3. Peut également être renseigné via la
  variable d'environnement :envvar:`AWS_REGION`.
* **endpoint**: L'adresse du serveur S3 (si celle-ci est différente de l'adresse
  par défaut ``amazonaws.com``). Peut également être renseigné via la
  variable d'environnement :envvar:`AWS_ENDPOINT_URL`.

Exemple
-------

Prenons le cas de figure suivant :

  - fichier: ``doc/waarp-transfer.pdf``
  - bucket: ``archive``
  - point de terminaison: ``s3.eu-west-3.amazonaws.com``
  - région: ``eu-west-3`` (Paris)
  - clé d'accès: ``toto``
  - clé d'accès secrète: ``sesame``

Dans un premier temps, l'instance cloud doit être définie. Dans cet exemple, nous
lui donnerons le nom "instance-exemple".

La commande de création pour cette instance cloud est donc :

.. code-block:: shell
   waarp-transfer cloud add -n "instance-exemple" -t "s3" -k "toto" -s "sesame" -o "bucket:archive" -o "region:eu-west-3" -o "endpoint:s3.eu-west-3.amazonaws.com"

Par la suite, lors de mon transfert, le chemin du fichier devra donc ressembler à : ::

    instance-exemple:doc/waarp-transfer.pdf