Utilisation de l'outil s3cmd¶
s3cmd est un outil en ligne de commande qui permet de gérer le stockage objet (S3).
s3cmd permet entre autres de :
- Créer et supprimer des compartiments
- Modifier les politiques d'accès à vos compartiments
- Synchroniser une source et une destination, que ce soit :
- D’un dossier local vers du stockage S3
- D’un stockage S3 vers un dossier local
Installation¶
Le logiciel s3cmd est disponible pour téléchargement sur le site de s3tools et également à partir de la plateforme de calcul de VALERIA, autant par connexion SSH que par Jupyter.
Configuration¶
Astuce techno
Cette procédure présente la configuration de l'application client sur votre poste de travail. Un outil est disponible pour automatiser la configuration de différents clients S3 (Rclone, s3cmd, s3fs et awscli), il suffit de lancer la commande val-generate-s3-config sur une invite de commande sur la plateforme de calcul.
Pour utiliser s3cmd avec le stockage objet (S3) VALERIA, il faut fournir les clés d'accès. Ces informations sont conservées dans le fichier .s3cfg, qui se trouve à la racine du dossier « home ». Un fichier préconfiguré pour se connecter au stockage objet (S3) VALERIA est disponible et voici les étapes de configuration, à partir d’une session Jupyter :
- Connectez-vous à la plateforme de calcul: https://jupyter.valeria.science/.
- À l'aide de l'explorateur de fichier, dirigez-vous dans le dossier suivant :
public/exemples/config/ - Copiez le fichier
dots3cfgà la racine de votre dossier 'home' - Remplacer
# VOTRE IDULpar# votreidul123 - Insérer vos clés d'accès sur les lignes correspondantes. Vos clés sont disponibles sur le tableau de bord du portail de VALERIA dans la carte « Clé de stockage S3 ».
- Vous pourrez ensuite effectuer des commandes avec s3cmd à partir du terminal (voir le menu File/New/Terminal)
Voici en référence le fichier dots3cfg.
Quelques commandes utiles¶
Afficher vos compartiments¶
Créer un nouveau compartiement¶
Convention de nom pour les compartiments
Le nom du compartiment peut compter entre 3 et 63 caractères et contenir uniquement des caractères minuscules, des chiffres, des points et des tirets. Pour plus d'informations, consulter la documentation d'Amazon sur la convention de noms d'un compartiment.
$ s3cmd ls
2021-09-23 19:47 s3://projet1
2021-10-07 12:27 s3://projet2
2021-10-07 14:06 s3://projet3
Ajout de nouveaux fichiers dans le compartiment¶
Pour téléverser un fichier unique ou un dossier, utiliser la commande s3cmd put .... Par exemple, pour téléverser le dossier local nommé docs vers le dossier documents dans le compartiment projet3 :
$ s3cmd put --recursive docs/ s3://projet3/documents/
upload: 'docs/doc1.txt' -> 's3://projet3/documents/doc1.txt' [1 of 3]
561543 of 561543 100% in 0s 9.82 MB/s done
upload: 'docs/doc2.txt' -> 's3://projet3/documents/doc2.md' [2 of 3]
11460 of 11460 100% in 0s 1145.49 KB/s done
upload: 'docs/sous-dossier/doc3.txt' -> 's3://projet3/documents/sous-dossier/doc3.txt' [3 of 3]
À noter que la structure de dossiers est conservée lors du téléversement sur la plateforme.
Synchroniser des fichiers¶
Les dossiers sont identifiés par un / à la fin de leur nom
Pour S3, il est important de marquer la différence entre un fichier et un dossier. Dans le cas d'un dossier, il est nécessaire de spécifier le caractères / à la fin du nom du dossier.
Pour une synchronization du dossier resultats, à partir de votre poste, vers le dossier resultats du compartiment projet3 S3 :
$ s3cmd sync resultats/ s3://project-de-recherche/resultats/
upload: 'resultats/fichier1.txt' -> 's3://projet3/resultats/fichier1.txt' [1 of 3]
0 of 0 0% in 0s 0.00 B/s done
upload: 'resultats/fichier2.txt' -> 's3://projet3/resultats/fichier2.txt' [2 of 3]
0 of 0 0% in 0s 0.00 B/s done
upload: 'resultats/fichier3.txt' -> 's3://projet3/resultats/fichier3.txt' [3 of 3]
0 of 0 0% in 0s 0.00 B/s done
Vérifier la politique d'accès d'un compartiment¶
Pour consulter la politique d'accès en place, utiliser la commande suivante :
$ s3cmd info s3://projet3
s3://projet3/ (bucket):
Location: ul
Payer: BucketOwner
Expiration Rule: none
Policy: none
CORS: none
ACL: <identifiant utilisateur>: FULL_CONTROL
Le résultat Policy: none indique qu'aucune politique n'est en place.
Dans le cas contraire, la politique sera affichée :
$ s3cmd info s3://projet3
s3://projet3/ (bucket):
Location: ul
Payer: BucketOwner
Expiration Rule: none
Policy: {
"Version": "2012-10-17",
"Id": "read-write",
"Statement": [
{
"Sid": "Le nom de la politique. ex: Accès Complet",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam:::user/<IDUL-COLLABORATEUR>",
"arn:aws:iam:::user/nom-collaborateur-1"
]
},
"Action": [
"s3:ListBucket",
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:GetBucketPolicy"
],
"Resource": [
"arn:aws:s3:::projet3",
"arn:aws:s3:::projet3/*"
]
}
]
}
CORS: none
ACL: <UTILISATEUR>: FULL_CONTROL
Exemple détaillé d'une politique d'accès¶
Dans cette section, la politique d'accès suivante est présentée en détails :
{
"Version": "2012-10-17",
"Id": "read-write",
"Statement": [
{
"Sid": "Le nom de la politique. ex: Accès Complet",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam:::user/<identifiant utilisateur>",
"arn:aws:iam:::user/nom-collaborateur-1"
]
},
"Action": [
"s3:ListBucket",
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:GetBucketPolicy"
],
"Resource": [
"arn:aws:s3:::projet3",
"arn:aws:s3:::projet3/*"
]
}
]
}
Les champs d'une politique¶
Les champs à la racine de la structure JSON ne changent jamais :
Version: Permet d'identifier la version de la structure de politique Amazon. Ce champ doit toujours être défini à"2012-10-17".Statement: Défini une liste de règles à appliquer au compartiment. ex:"Statement": [ {règle 1}, {règle 2}, {règle 3} ]. C'est dans cette valeur que sera définit une règle d'accès.
Les champs d'une règle d'accès¶
Les champs disponibles d'une règle d'accès sont :
Sid: Ce champ permet de donner un nom à votre règle, permettant d'identifier clairement son intention.Effect: Ce champ peut avoir l'une des deux valeurs suivantes:AllowouDeny, pour permettre ou empêcher lesActiondéterminées.Principal: Définit de la liste des utilisatrices et des utilisateurs concernés par la règle.Action: Liste les actions autorisées ou refusées par la règle.Resource: Identifie les objets concernés par la règle.
Le champ Effect identifie si la règle autorise ou refuse les actions listées¶
Info
Un Deny a préséance sur un Allow.
Dans le cas suivant :
- La première règle donne un accès public au compartiment.
- La seconde règle interdit l'accès à collaborateur suspect.
"Statement": [
{
"Sid": "Accès Complet pour la planète",
"Effect": "Allow",
"Principal": {
"AWS": [
"*"
]
},
"Action": [
"s3:*"
],
"Resource": [
"arn:aws:s3:::projet3",
"arn:aws:s3:::projet3/*"
]
},
{
"Sid": "Interdire l'accès à collaborateur-suspect",
"Effect": "Deny",
"Principal": {
"AWS": [
"arn:aws:iam:::user/collaborateur-suspect"
]
},
"Action": [
"s3:*"
],
"Resource": [
"arn:aws:s3:::projet3",
"arn:aws:s3:::projet3/*"
]
},
]
Principal identifie les utilisatrices et les utilisateurs concernés par la règle¶
L'exemple suivant s'applique à l'utilisatrice ou l'utilisateur mon-collaborateur :
Plusieurs utilisatrices et utilisateurs peuvent être spécifiés, en respectant la syntaxe JSON.
"Principal": {
"AWS": [
"arn:aws:iam:::user/mon-collaborateur-1",
"arn:aws:iam:::user/mon-collaborateur-2",
"arn:aws:iam:::user/mon-collaborateur-3",
"arn:aws:iam:::user/mon-collaborateur-4",
"arn:aws:iam:::user/mon-collaborateur-5",
"arn:aws:iam:::user/mon-collaborateur-6"
]
Resource identifie les dossiers qui seront concernés par la règle¶
Une règle s'applique à un compartiment ou à un sous-dossier. La section Resource du fichier JSON permet d'identifier la partie de vos données concernée par la règle.
Dans l'exemple suivant, la règle s'applique au compartiment et à tous ses sous-dossiers. L'astérisque signifie que tout ce qui est dans le compartiment est affecté par la règle.
Dans l'exemple suivant, la règle s'applique à tous les documents sous le dossier resultats.
Action identifie les autorisations données ou interdites à Principal¶
Le protocole S3 permet de choisir plusieurs actions possibles sur un compartiment et son contenu. Voici quelques exemples avec les actions les plus souvent utilisées:
s3:ListBuckets3:PutObjects3:GetObjects3:DeleteObject
Pour une référence complète, consulter la page suivante : Bucket Policies
Modifier les permissions d'accès¶
Voici quelques exemples de politique d'accès que vous pouvez appliquer aux compartiments. Chaque compartiment a des règles indépendantes. Il n'est donc pas possible d'écrire une seule politique pour tous les compartiments.
Pour changer les politiques d'accès, il faut modifier un document au format JSON qui décrit la politique des compartiments. Si un document JSON vide est appliqué à un compartiment, la politique existante sera supprimée sans possibilité de récupération. Il est donc suggéré de conserver une version de fichier JSON sur un poste ou encore sur un stockage objet (S3). Advenant que la politique soit supprimée, seul le propriétaire initial (la chercheuse ou le chercheur ULaval) aura accès aux données.
Édition d'une politique d'accès¶
Pour ajouter ou modifier une politique, utiliser une politique existante ou l'un des fichiers d'exemple fournit plus bas. Un seul fichier est nécessaire pour contenir toutes les règles qui seront appliquées au compartiment.
Voici l'exemple d'une règle qui donne un accès en lecture à tout le compartiment projet3 pour le collaborateur mon-collaborateur-1 :
{
"Version": "2012-10-17",
"Id": "acces-lecture-ecriture",
"Statement":
[
{
"Sid": "projet3: Lecture seule sur tout le compartiment",
"Effect": "Allow",
"Principal":
{
"AWS":
[
"arn:aws:iam:::user/mon-collaborateur-1"
]
},
"Action":
[
"s3:ListBucket",
"s3:GetObject"
],
"Resource":
[
"arn:aws:s3:::projet3",
"arn:aws:s3:::projet3/*"
]
}
]
}
Exemple d'une règle qui donne un accès complet à un dossier pour l'étudiant idulÉtudiant123 :
{
"Version": "2012-10-17",
"Id": "acces-complet",
"Statement":
[
{
"Sid": "projet3: Accès complet sur tout le dossier Étudiants/idulÉtudiant123",
"Effect": "Allow",
"Principal":
{
"AWS":
[
"arn:aws:iam:::user/mon-étudiant-123"
]
},
"Action":
[
"s3:*"
],
"Resource":
[
"arn:aws:s3:::projet3/Étudiants/idulÉtudiant123/*"
]
}
]
}
Exemple d'une politique qui combine les deux règles précédentes :
{
"Version": "2012-10-17",
"Id": "politique-acces-combines",
"Statement":
[
{
"Sid": "projet3: Lecture seule sur tout le compartiment",
"Effect": "Allow",
"Principal":
{
"AWS":
[
"arn:aws:iam:::user/mon-collaborateur-1"
]
},
"Action":
[
"s3:ListBucket",
"s3:GetObject"
],
"Resource":
[
"arn:aws:s3:::projet3",
"arn:aws:s3:::projet3/*"
]
},
{
"Sid": "projet3: Accès complet sur tout le dossier Étudiants/idulÉtudiant123",
"Effect": "Allow",
"Principal":
{
"AWS":
[
"arn:aws:iam:::user/mon-étudiant-123"
]
},
"Action":
[
"s3:*"
],
"Resource":
[
"arn:aws:s3:::projet3/Étudiants/idulÉtudiant123/*"
]
}
]
}
Appliquer une politique à un compartiment¶
Pour appliquer une politique à un compartiment, sauvegarder votre politique dans un fichier JSON (ex. : politique.json) et d'utiliser la commande suivante :