forked from DSIT/documentation-dsit
Ajouter docs/Services/pole-scientifique/Onyxia/docs/Guide-insee-version-secret-stockage
This commit is contained in:
parent
5118675b4d
commit
91f00b911a
|
|
@ -0,0 +1,345 @@
|
|||
# Contrôle de version
|
||||
|
||||
## Pourquoi utiliser le contrôle de version ?
|
||||
|
||||
Le Datalab est une plateforme mutualisée : les ressources utilisées par les services sont partagées entre les différents utilisateurs. A ce titre, les services du Datalab fonctionnent sur le modèle des conteneurs éphémères : dans un usage standard, l'utilisateur lance un service, réalise des traitements de données, sauvegarde le code qui a permis de réaliser ces traitements, et supprime l'instance du service. Cette sauvegarde du code est grandement facilitée par l'usage du contrôle de version.
|
||||
|
||||
Cette considération de performance ne doit cependant pas être vue comme une contrainte : le contrôle de version est une bonne pratique essentielle de développement. Les bénéfices sont nombreux, aussi bien à titre individuel :
|
||||
|
||||
* le projet local est synchronisé avec un serveur distant, rendant la perte de code quasi impossible ;
|
||||
* l'historique complet des choix et modifications effectuées sur le projet est conservé ;
|
||||
* l'utilisateur peut parcourir cet historique pour rechercher les modifications qui ont pu créer des erreurs, et décider à tout moment de revenir à une version précédente du projet, ou bien de certains fichiers.
|
||||
|
||||
que dans le cadre de projets collaboratifs :
|
||||
|
||||
* le travail simultané sur un même projet est possible, sans risque de perte ;
|
||||
* l'utilisateur peut partager ses modifications tout en bénéficiant de celles des autres ;
|
||||
* il devient possible de contribuer à des projets open-source, pour lesquels l'usage de Git est très largement standard.
|
||||
|
||||
::: {.callout-warning}
|
||||
Ce tutoriel vise à présenter comment le contrôle de version peut être facilement implémenté grâce aux outils présents sur le Datalab. Il ne présente pas le fonctionnement de Git et présuppose donc une certaine familiarité avec l'outil. De nombreuses ressources en ligne peuvent servir d'introduction ; l'utilisateur de R pourra par exemple consulter [ce guide](https://linogaliana.gitlab.io/collaboratif/git.html) et l'utilisateur de Python ce [chapitre de cours](https://linogaliana-teaching.netlify.app/course/git/). Une formation complète à Git sera bientôt proposée dans l'[espace formation ](https://www.sspcloud.fr/documentation)du Datalab.
|
||||
:::
|
||||
|
||||
## Intégration de GitHub avec le Datalab
|
||||
|
||||
### Pourquoi GitHub ?
|
||||
|
||||
Bien qu'une utilisation hors-ligne de Git soit possible, tout l'intérêt du contrôle de version réside dans la synchronisation de la copie locale d'un projet (_clone_) avec un dépôt distant (_remote_). Différents services de forge logicielle permettent cette synchronisation des projets Git, dont les plus connus sont [GitHub ](https://github.com)et [GitLab](https://about.gitlab.com). Dans la mesure où le premier dispose aujourd'hui de beaucoup plus de visibilité — par exemple, les dépôts de l'Insee, [InseeFr ](https://github.com/InseeFrL)et [InseeFrLab](https://github.com/InseeFrLab), sont sur GitHub — le Datalab propose une intégration facilitée avec GitHub, que nous présentons à travers ce tutoriel.
|
||||
|
||||
::: {.callout-warning}
|
||||
La suite du tutoriel nécessite de disposer d'un [compte GitHub](https://github.com/join).
|
||||
:::
|
||||
|
||||
::: {.callout-note}
|
||||
Si l'utilisation du Datalab avec la plateforme GitHub est facilitée, elle n'est en aucun cas obligatoire : il reste tout à fait possible d'utiliser la forge logicielle de son choix pour la synchronisation des projets. Une [forge basée sur GitLab ](https://git.lab.sspcloud.fr)est notamment mise à disposition des utilisateurs du Datalab.
|
||||
:::
|
||||
|
||||
### Créer un jeton d'accès (_token_)
|
||||
|
||||
La synchronisation avec un dépôt distant nécessite une authentification auprès de GitHub. Celle-ci s'effectue à l'aide d'un jeton d'accès personnel, qui doit être généré à partir du compte GitHub de l'utilisateur. Le service de génération est accessible à [cette adresse](https://github.com/settings/tokens). La [documentation GitHub ](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)(en Anglais) propose des illustrations pour guider le processus.
|
||||
|
||||
Pour générer un jeton, il est nécessaire de choisir un nom de jeton, un délai d'expiration et des droits d'accès (_scope_). Il est recommandé de choisir un délai court (30 jours) et un accès restreint (_repo_ seulement) afin de limiter les risques de sécurité en cas de diffusion malveillante du jeton.
|
||||
|
||||
|
||||
|
||||
Une fois le jeton généré, ce dernier apparaît à l'écran. Un jeton ne peut être visualisé qu'une seule fois ; en cas de perte, il faudra en générer un nouveau.
|
||||
|
||||
### Ajouter le jeton d'accès au Datalab
|
||||
|
||||
Il est recommandé d'ajouter ses jetons d'accès à un gestionnaire de mots de passe. Le jeton peut également être ajouté à la configuration "Services externes" du compte utilisateur sur le Datalab, ce qui permet au jeton d'être directement accessible au sein des services proposés sur la plateforme.
|
||||
|
||||
|
||||
|
||||
::: {.callout-warning}
|
||||
Attention à bien utiliser dans les "Informations du compte" l'adresse mail associée à votre compte GitHub, c'est elle qui permet de lier effectivement les _commits_ que vous effectuerez à votre compte GitHub.
|
||||
:::
|
||||
|
||||
## Utiliser Git avec les services du Datalab
|
||||
|
||||
Git est préconfiguré pour fonctionner nativement avec les différents services pertinents du Datalab. A l'ouverture d'un service, il est possible de configurer certains éléments. Si l'on a ajouté un jeton d'accès GitHub à son compte sur le Datalab, ce dernier est pré-configuré. Il est par ailleurs possible d'indiquer l'URL **complète** d'un _Repository_ Git (ex : [https://github.com/InseeFrLab/onyxia](https://github.com/InseeFrLab/onyxia)), qui sera alors cloné à l'initialisation dans l'espace de travail de l'instance.
|
||||
|
||||
|
||||
|
||||
### Via le terminal
|
||||
|
||||
Le jeton d'accès GitHub est disponible dans le terminal des différents services via la variable d'environnement `$GIT_PERSONAL_ACCESS_TOKEN`. Afin d'éviter de devoir s'authentifier à chaque opération impliquant le dépôt distant (_clone_, _push_ & _pull_), il est recommandé de cloner celui-ci en incluant le jeton d'accès dans le lien HTTPS, à l'aide de la commande suivante :
|
||||
|
||||
`git clone https://${GIT_PERSONAL_ACCESS_TOKEN}@github.com/<owner>/<repo>.git`
|
||||
|
||||
où \<owner> et \<repo> sont à remplacer respectivement par le nom d'utilisateur et le nom du dépôt GitHub.
|
||||
|
||||
### Via des interfaces graphiques intégrées
|
||||
|
||||
Les principaux services de production de code disponibles sur le Datalab disposent d'une interface graphique pour faciliter l'utilisation de Git :
|
||||
|
||||
* RStudio : RStudio propose une interface graphique pour Git native et assez complète. La [documentation utilitR](https://www.book.utilitr.org/03_fiches_thematiques/fiche_git_utilisation) présente son fonctionnement en détail ;
|
||||
* Jupyter : le plugin [jupyterlab-git ](https://github.com/jupyterlab/jupyterlab-git)permet un interfaçage (assez sommaire) de Jupyter avec Git ;
|
||||
* VSCode : VSCode propose nativement une interface graphique très bien intégrée avec Git et GitHub. Une [documentation détaillée ](https://code.visualstudio.com/docs/editor/versioncontrol)(en Anglais) présente les possibilités de l'outil.
|
||||
|
||||
::: {.callout-warning}
|
||||
Les interfaces graphiques facilitent la prise en main de Git, mais ne remplacent jamais complètement l'usage de l'outil via un terminal du fait d'une intégration nécessairement imparfaite. Il est donc utile de se familiariser avec l'usage de Git via le terminal le plus tôt possible.
|
||||
:::
|
||||
|
||||
|
||||
# Stockage de données
|
||||
|
||||
## Principes
|
||||
|
||||
La solution de stockage de fichiers associée au Datalab est [MinIO](https://min.io), un système de stockage d'objets basé sur le cloud, compatible avec l'API S3 d'Amazon. Concrètement, cela a plusieurs avantages :
|
||||
|
||||
* les fichiers stockés sont accessibles facilement et à n'importe quel endroit : un fichier est accessible directement via une simple URL, qui peut être partagée ;
|
||||
* il est possible d'accéder aux fichiers stockés directement dans les services de _data science_ (R, Python...) proposés sur le Datalab, sans avoir besoin de copier les fichiers localement au préalable, ce qui améliore fortement la reproductibilité des analyses.
|
||||
|
||||
|
||||
|
||||
## Gérer ses données
|
||||
|
||||
### Importer des données
|
||||
|
||||
La page [Mes fichiers](https://datalab.sspcloud.fr/mes-fichiers/) du Datalab prend la forme d'un explorateur de fichiers présentant les différents _buckets_ (dépôts) auxquels l’utilisateur a accès.
|
||||
|
||||
Chaque utilisateur dispose par défaut d'un _bucket_ personnel pour stocker ses fichiers. Au sein de ce _bucket_, deux options sont possibles :
|
||||
|
||||
* "**créer un répertoire**" : crée un répertoire dans le _bucket_/répertoire courant, de manière hiérarchique, comme dans un système de fichiers traditionnel ;
|
||||
* "_**uploader**_** un fichier**" : _upload_ un ou plusieurs fichiers dans le répertoire courant.
|
||||
|
||||
::: {.callout-note}
|
||||
L'interface graphique du stockage de données sur le Datalab est encore en cours de construction. Elle peut à ce titre présenter des problèmes de réactivité. Pour des opérations fréquentes sur le stockage de fichiers, il peut être préférable d'interagir avec MinIO via le terminal.
|
||||
:::
|
||||
|
||||
### Partager des données
|
||||
|
||||
En cliquant sur un fichier dans son _bucket_ personnel, on accède à sa page de caractéristiques. Sur celle-ci, il est notamment possible de **changer le statut de diffusion du fichier**. Changer le statut du fichier de "privé" à "public" permet d'obtenir un **lien de diffusion**, qui peut alors être transmis pour téléchargement du fichier. Le statut "public" ne donne aux autres utilisateurs que des droits en lecture, la modification ou la suppression de fichiers personnels par d'autres utilisateurs est impossible.
|
||||
|
||||
Pour simplifier la mise à disposition en lecture de plusieurs fichiers — dans le cadre d'une formation par exemple — il est possible de créer un **dossier "diffusion"** dans son _bucket_ personnel. Par défaut, tous les fichiers présents dans ce dossier ont un statut de diffusion public.
|
||||
|
||||
::: {.callout-note}
|
||||
Dans le cadre de projets collaboratifs, il peut être intéressant pour les différents participants d'avoir accès à un espace de stockage commun. Il est possible pour cet usage de créer des _buckets_ partagés sur MinIO. N'hésitez pas à nous contacter via les canaux précisés sur la page "[Première utilisation](discover.qmd)" si vous souhaitez porter des projets _open-data_ sur le Datalab.
|
||||
:::
|
||||
|
||||
::: {.callout-warning}
|
||||
Conformément aux [conditions d'utilisation](https://www.sspcloud.fr/tos\_fr.md), seuls des données de type _open data_ ou ne présentant aucune sensibilité peuvent être stockées sur le Datalab. Le fait qu'un fichier ait un statut de diffusion "privé" ne suffit pas à garantir une parfaite confidentialité.
|
||||
:::
|
||||
|
||||
## Utiliser des données stockées sur MinIO
|
||||
|
||||
Les identifiants d'accès nécessaires pour accéder à des données sur MinIO sont pré-configurés dans les différents services du Datalab, accessibles sous la forme de [variables d'environnement](secrets.qmd). Ainsi, l'import et l'export de fichiers à partir des services est grandement facilité.
|
||||
|
||||
### Configuration
|
||||
|
||||
::: {.panel-tabset}
|
||||
|
||||
#### R
|
||||
|
||||
En R, l'interaction avec un système de fichiers compatible S3 est rendu possible par la librairie `aws.s3`.
|
||||
|
||||
```r
|
||||
library(aws.s3)
|
||||
```
|
||||
|
||||
#### Python
|
||||
|
||||
En Python, l'interaction avec un système de fichiers compatible S3 est rendu possible par deux librairies :
|
||||
|
||||
* [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html), une librairie créée et maintenue par Amazon ;
|
||||
* [S3Fs](https://s3fs.readthedocs.io/en/latest/), une librairie qui permet d'interagir avec les fichiers stockés à l'instar d'un _filesystem_ classique.
|
||||
|
||||
Pour cette raison et parce que S3Fs est utilisée par défaut par la librairie [pandas](https://pandas.pydata.org) pour gérer les connections S3, nous allons présenter la gestion du stockage sur MinIO via Python à travers cette librairie.
|
||||
|
||||
```python
|
||||
import os
|
||||
import s3fs
|
||||
|
||||
# Create filesystem object
|
||||
S3_ENDPOINT_URL = "https://" + os.environ["AWS_S3_ENDPOINT"]
|
||||
fs = s3fs.S3FileSystem(client_kwargs={'endpoint_url': S3_ENDPOINT_URL})
|
||||
```
|
||||
|
||||
#### mc
|
||||
|
||||
MinIO propose un client en ligne de commande (`ùc`) qui permet d’interagir avec le système de stockage à la manière d'un _filesystem_ UNIX classique. Ce client est installé par défaut et accessible via un terminal dans les différents services du Datalab.
|
||||
|
||||
Le client MinIO propose les commandes UNIX de base, telles que ls, cat, cp, etc. La liste complète est disponible dans la [documentation du client](https://docs.min.io/docs/minio-client-complete-guide.html).
|
||||
|
||||
:::
|
||||
|
||||
### Lister les fichiers d'un *bucket*
|
||||
|
||||
::: {.panel-tabset}
|
||||
|
||||
#### R
|
||||
|
||||
```r
|
||||
aws.s3::get_bucket("donnees-insee", region = "")
|
||||
```
|
||||
|
||||
#### Python
|
||||
|
||||
```python
|
||||
fs.ls("donnees-insee")
|
||||
```
|
||||
|
||||
#### mc
|
||||
|
||||
Le stockage du Datalab est accessible via l'alias `s3`. Par exemple, pour lister les fichiers du bucket `donnees-insee` :
|
||||
|
||||
```bash
|
||||
mc ls s3/donnees-insee
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### Importer des données
|
||||
|
||||
::: {.panel-tabset}
|
||||
|
||||
#### R
|
||||
|
||||
```r
|
||||
BUCKET <- "donnees-insee"
|
||||
FILE_KEY_S3 <- "diffusion/BPE/2019/BPE_ENS.csv"
|
||||
|
||||
df <-
|
||||
aws.s3::s3read_using(
|
||||
FUN = readr::read_delim,
|
||||
# Mettre les options de FUN ici
|
||||
delim = ";",
|
||||
object = FILE_KEY_S3,
|
||||
bucket = BUCKET,
|
||||
opts = list("region" = "")
|
||||
)
|
||||
```
|
||||
|
||||
#### Python
|
||||
|
||||
Le package S3Fs permet d'interagir avec les fichiers stockés sur MinIO comme s'il s'agissait de fichiers locaux. La syntaxe est donc très familière pour les utilisateurs de Python. Par exemple, pour importer/exporter des données tabulaires via `pandas` :
|
||||
|
||||
```python
|
||||
import pandas as pd
|
||||
|
||||
BUCKET = "donnees-insee"
|
||||
FILE_KEY_S3 = "diffusion/BPE/2019/BPE_ENS.csv"
|
||||
FILE_PATH_S3 = BUCKET + "/" + FILE_KEY_S3
|
||||
|
||||
with fs.open(FILE_PATH_S3, mode="rb") as file_in:
|
||||
df_bpe = pd.read_csv(file_in, sep=";")
|
||||
```
|
||||
|
||||
#### mc
|
||||
|
||||
Pour copier les données d'un bucket sur MinIO vers le service local :
|
||||
|
||||
```bash
|
||||
mc cp s3/donnees-insee/diffusion/BPE/2019/BPE_ENS.csv ./BPE_ENS.csv
|
||||
```
|
||||
|
||||
::: {.callout-warning}
|
||||
**Copier les fichiers dans le service local n'est généralement pas une bonne pratique** : cela limite la reproductibilité des analyses, et devient rapidement impossible avec des volumes importants de données. Il est donc préférable de prendre l'habitude d'importer les données comme des fichiers directement dans `R`/`Python`.
|
||||
:::
|
||||
|
||||
:::
|
||||
|
||||
### Exporter des données vers MinIO
|
||||
|
||||
::: {.panel-tabset}
|
||||
|
||||
#### R
|
||||
|
||||
```r
|
||||
BUCKET_OUT = "<mon_bucket>"
|
||||
FILE_KEY_OUT_S3 = "mon_dossier/BPE_ENS.csv"
|
||||
|
||||
aws.s3::s3write_using(
|
||||
df,
|
||||
FUN = readr::write_csv,
|
||||
object = FILE_KEY_OUT_S3,
|
||||
bucket = BUCKET_OUT,
|
||||
opts = list("region" = "")
|
||||
)
|
||||
```
|
||||
|
||||
#### Python
|
||||
|
||||
```python
|
||||
BUCKET_OUT = "<mon_bucket>"
|
||||
FILE_KEY_OUT_S3 = "mon_dossier/BPE_ENS.csv"
|
||||
FILE_PATH_OUT_S3 = BUCKET_OUT + "/" + FILE_KEY_OUT_S3
|
||||
|
||||
with fs.open(FILE_PATH_OUT_S3, 'w') as file_out:
|
||||
df_bpe.to_csv(file_out)
|
||||
```
|
||||
|
||||
#### mc
|
||||
|
||||
Pour copier les données du service local vers un bucket sur MinIO:
|
||||
|
||||
```bash
|
||||
mc cp chemin/local/vers/mon/fichier.csv s3/<mon_bucket>/chemin/distant/vers/mon/fichier.csv
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### Renouveler des jetons d'accès (*tokens*) périmés
|
||||
|
||||
L'accès au stockage MinIO est possible via un _token_ (jeton d'accès) personnel, valide 24h, et automatiquement régénéré à échéances régulières sur le SSP Cloud. Lorsqu'un token a expiré, les services créés avant la date d'expiration (avec le précédent token) ne peuvent plus accéder au stockage ; le service concerné apparaît alors marqué en rouge dans la page [Mes Services](https://datalab.sspcloud.fr/my-services). Dans ce cas, deux possibilités :
|
||||
- ouvrir un nouveau service sur le Datalab, qui aura par défaut un nouveau token à jour
|
||||
- remplacer manuellement les jetons périmés par des nouveaux. Des scripts indiquant la manière de faire pour les différentes utilisations de MinIO (`R`/`Python`/`mc`) sont disponibles [ici](https://datalab.sspcloud.fr/account/storage). Il suffit de choisir le script pertinent et de l'exécuter dans son environnement de travail courant.
|
||||
|
||||
# Gestion des secrets
|
||||
|
||||
### Les variables d'environnement;
|
||||
|
||||
Il arrive que certaines informations doivent être mise à disposition d'un grand nombre d'applications, ou ne doivent pas figurer en clair dans votre code (jetons d'accès, mots de passe, etc.). L'utilisation de **variables d'environnement** permet de pouvoir accéder à ces informations depuis n'importe quel service.
|
||||
|
||||
Au lancement d'un service, plusieurs variables d'environnement sont déjà injectées automatiquement — par exemple, les tokens d'accès à ``
|
||||
|
||||
|
||||
|
||||
### Création et gestion de secrets
|
||||
|
||||
Sur la plateforme, les variables d'environnement sont des secrets écrits dans [Vault](https://www.vaultproject.io) (le coffre fort du Datalab) et sont chiffrées. Cela vous permet d'y stocker des jetons, des identifiants et des mots de passe. La page [Mes secrets](https://datalab.sspcloud.fr/my-secrets/) prends la forme d'un explorateur de fichiers où vous pouvez trier et hiérarchiser vos variables dans des dossiers.
|
||||
|
||||
#### Pour commencer :
|
||||
|
||||
* Créez un nouveau dossier `+ Nouveau dossier`
|
||||
* Puis dans ce dossier, créez un nouveau secret `+ Nouveau secret`
|
||||
* Ouvrez votre secret
|
||||
|
||||
|
||||
|
||||
Chaque secret peut contenir plusieurs variables, composés de paires de clés-valeurs.
|
||||
|
||||
* `+ Ajouter une variable`
|
||||
|
||||
|
||||
|
||||
::: {.callout-note}
|
||||
Les clés (nom de la variable) commencent toujours par`$`et contiennent uniquement des lettres, des chiffres et le caractère de soulignement (`_`). Par convention, les clefs s'écrivent en MAJUSCULE.
|
||||
:::
|
||||
|
||||
Remplissez le champ du nom de la clef puis sa valeur.
|
||||
|
||||
### Convertir des secrets en variables d'environnement
|
||||
|
||||
Une fois votre secret édité, avec ses différentes variables, vous êtes prêt à l'utiliser dans votre service.
|
||||
|
||||
* Copiez le chemin du secret en cliquant sur le bouton `Utiliser dans un service`
|
||||
* Puis au moment de la configuration de votre service, allez dans l'onglet `Vault`et collez le chemin du secret dans le champ dédié
|
||||
|
||||
|
||||
|
||||
* Créez et ouvrez votre service
|
||||
|
||||
Pour vérifier que vos variables d'environnement ont bien été crées, vous pouvez lancer les commandes suivantes dans le terminal du service :
|
||||
|
||||
```bash
|
||||
# Lister toutes les variables d'environnement disponibles
|
||||
env
|
||||
|
||||
# Afficher la valeur d'une variable d'environnement
|
||||
echo $MA_VARIABLE
|
||||
|
||||
# Trouver toutes les variables d'environnement qui contiennent un pattern donné
|
||||
env | grep -i "<PATTERN>"
|
||||
```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user