Créer et utiliser des buckets S3

Ce guide pratique vous montre comment créer et utiliser des buckets S3 pour le stockage de fichiers sur la plateforme Atlas.

Prérequis

• Avoir un compte sur la plateforme Atlas
• Être administrateur de workspace ou avoir les droits nécessaires
• Avoir un workspace déjà créé
• Avoir au moins un DeploymentTarget créé
• Avoir accès au dépôt GitOps de votre workspace

Qu'est-ce qu'un bucket S3 ?

Un bucket S3 est un espace de stockage compatible avec le protocole S3 d'Amazon Web Services. Il permet de stocker des fichiers et des objets de manière durable et évolutive. Sur Atlas, les buckets ont un lifecycle indépendant des applications et doivent être créés au préalable.

Création d'un bucket S3

1. Cloner le dépôt GitOps de votre workspace

1
2

git clone <URL du dépôt de votre workspace>
cd <nom du dépôt>

2. Créer un fichier YAML pour le bucket

Créez un nouveau fichier YAML dans le dossier resources du dépôt. Nommez-le de manière significative, par exemple mon-bucket.yaml.

1
2

mkdir -p resources
touch resources/mon-bucket.yaml

3. Définir la configuration du bucket

Ouvrez le fichier mon-bucket.yaml dans votre éditeur préféré et ajoutez la configuration suivante :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

apiVersion: workspace.fabrique.social.gouv.fr/v1alpha1
kind: Bucket
metadata:
  name: mon-bucket
spec:
  parameters:
    name: "mon-app-bucket-unique-name"
    acl: "private"
    versioned: false
    forceDestroy: false
    tags: {}
    zoneRef:
      name: "dev"
    secretDeliveryTargets:
      - kind: "DeploymentTarget"
        name: "mon-app-dev"

Assurez-vous de remplacer : - mon-bucket par un nom significatif pour votre bucket - mon-app-bucket-unique-name par un nom unique pour votre bucket (ce nom doit être globalement unique) - mon-app-dev par le nom de votre DeploymentTarget - dev par le nom de la zone appropriée

4. Pousser les changements vers le dépôt

1
2
3

git add resources/mon-bucket.yaml
git commit -m "Ajout du bucket pour mon application"
git push

5. Vérifier la création du bucket

Une fois les changements poussés, ArgoCD détectera automatiquement les modifications et créera le bucket. Vous pouvez vérifier l'état de la création dans ArgoCD.

1. Accédez à ArgoCD via l'interface Atlas
2. Recherchez l'application correspondant à votre workspace
3. Vérifiez que le bucket a été créé avec succès

Paramètres de configuration

Paramètres principaux

Options d'ACL

L'ACL (Access Control List) définit les permissions d'accès au bucket. Les valeurs possibles sont :

• private : Accès privé (recommandé pour la plupart des cas)
• public-read : Lecture publique
• public-read-write : Lecture et écriture publiques
• aws-exec-read : Lecture pour AWS
• authenticated-read : Lecture pour les utilisateurs authentifiés
• log-delivery-write : Écriture pour la livraison de logs

Format et accès aux informations de connexion

Les informations de connexion au bucket sont automatiquement livrées au DeploymentTarget spécifié dans secretDeliveryTargets. Le secret est livré dans le format JSON suivant :

1
2
3
4
5

{
  "name": "nom-du-bucket",
  "accessKey": "clé-d-accès",
  "secretKey": "clé-secrète"
}

L'endpoint S3 est toujours s3.gra.io.cloud.ovh.net.

Vous pouvez accéder à ces informations de deux façons :

Via Vault

1. Accédez à Vault via l'interface Atlas
2. Naviguez vers le chemin correspondant à votre DeploymentTarget
3. Vous y trouverez les informations de connexion au bucket

Via les secrets Kubernetes

Les informations de connexion sont également disponibles sous forme de secrets Kubernetes dans le namespace de votre DeploymentTarget. Vous pouvez y accéder dans votre application en montant le secret ou en utilisant les variables d'environnement.

Exemple d'utilisation dans un déploiement Kubernetes :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mon-application
spec:
  # ...
  template:
    # ...
    spec:
      containers:
      - name: mon-application
        image: mon-image:latest
        env:
        - name: S3_ACCESS_KEY
          valueFrom:
            secretKeyRef:
              name: mon-bucket
              key: accessKey
        - name: S3_SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: mon-bucket
              key: secretKey
        - name: S3_BUCKET_NAME
          valueFrom:
            secretKeyRef:
              name: mon-bucket
              key: name
        # L'endpoint est toujours s3.gra.io.cloud.ovh.net
        - name: S3_ENDPOINT
          value: "https://s3.gra.io.cloud.ovh.net"

Utilisation du bucket dans votre application

Exemple d'utilisation avec TypeScript

Voici un exemple simple d'utilisation du bucket S3 avec TypeScript et la bibliothèque AWS SDK :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

import * as AWS from 'aws-sdk';

// Configuration du client S3
const s3 = new AWS.S3({
  accessKeyId: process.env.S3_ACCESS_KEY as string,
  secretAccessKey: process.env.S3_SECRET_KEY as string,
  endpoint: process.env.S3_ENDPOINT as string,
  s3ForcePathStyle: true, // Nécessaire pour les endpoints compatibles S3 non-AWS
  signatureVersion: 'v4'
});

// Exemple : télécharger un fichier
async function uploadFile(fileContent: Buffer | string, fileName: string): Promise<string> {
  const params: AWS.S3.PutObjectRequest = {
    Bucket: process.env.S3_BUCKET_NAME as string,
    Key: fileName,
    Body: fileContent
  };

  try {
    const data: AWS.S3.ManagedUpload.SendData = await s3.upload(params).promise();
    console.log(`Fichier téléchargé avec succès à ${data.Location}`);
    return data.Location;
  } catch (err) {
    console.error('Erreur lors du téléchargement du fichier:', err);
    throw err;
  }
}

// Exemple : télécharger un fichier
async function downloadFile(fileName: string): Promise<AWS.S3.Body> {
  const params: AWS.S3.GetObjectRequest = {
    Bucket: process.env.S3_BUCKET_NAME as string,
    Key: fileName
  };

  try {
    const data: AWS.S3.GetObjectOutput = await s3.getObject(params).promise();
    return data.Body;
  } catch (err) {
    console.error('Erreur lors du téléchargement du fichier:', err);
    throw err;
  }
}

Modification d'un bucket

La modification d'un bucket se fait en modifiant le fichier YAML correspondant dans le dépôt du workspace. Cependant, certains champs sont immuables et ne peuvent pas être modifiés après la création.

Champs immuables

• spec.parameters.name : Le nom du bucket ne peut pas être modifié après la création.
• spec.parameters.versioned : Une fois activé, le versioning ne peut pas être désactivé.

1. Cloner le dépôt GitOps de votre workspace (si ce n'est pas déjà fait)

1
2

git clone <URL du dépôt de votre workspace>
cd <nom du dépôt>

2. Modifier le fichier YAML du bucket

Ouvrez le fichier resources/mon-bucket.yaml dans votre éditeur préféré et modifiez la configuration selon vos besoins.

3. Pousser les changements vers le dépôt

1
2
3

git add resources/mon-bucket.yaml
git commit -m "Modification du bucket pour mon application"
git push

4. Vérifier la mise à jour du bucket

Une fois les changements poussés, ArgoCD détectera automatiquement les modifications et mettra à jour le bucket. Vous pouvez vérifier l'état de la mise à jour dans ArgoCD.

Suppression d'un bucket

La suppression d'un bucket se fait en supprimant le fichier YAML correspondant du dépôt du workspace.

Attention : Si le champ forceDestroy est défini sur true, la suppression de la ressource entraînera également la suppression du bucket et de toutes les données qu'il contient. Assurez-vous de sauvegarder toutes les données importantes avant de supprimer un bucket.

1. Cloner le dépôt GitOps de votre workspace (si ce n'est pas déjà fait)

1
2

git clone <URL du dépôt de votre workspace>
cd <nom du dépôt>

2. Supprimer le fichier YAML du bucket

1
2
3

git rm resources/mon-bucket.yaml
git commit -m "Suppression du bucket pour mon application"
git push

3. Vérifier la suppression du bucket

Une fois les changements poussés, ArgoCD détectera automatiquement les modifications et supprimera le bucket. Vous pouvez vérifier l'état de la suppression dans ArgoCD.

Bonnes pratiques

Sécurité

• Utilisez toujours l'ACL private sauf si vous avez une raison spécifique de rendre le bucket public.
• N'activez jamais forceDestroy en production, car cela pourrait entraîner une perte de données.
• Utilisez des noms de bucket uniques et significatifs.

Organisation des données

• Organisez vos fichiers dans le bucket en utilisant des préfixes (similaires à des dossiers).
• Utilisez des conventions de nommage cohérentes pour vos fichiers.

Versioning

• Activez le versioning si vous avez besoin de conserver l'historique des modifications des fichiers.
• Mettez en place une lifecycle policy pour gérer la durée de vie des objets si nécessaire.

Performance

• Utilisez des noms de fichiers courts et significatifs.
• Évitez d'utiliser des caractères spéciaux dans les noms de fichiers.
• Utilisez des préfixes appropriés pour optimiser les performances.

Résolution des problèmes courants

Le bucket n'est pas créé

• Vérifiez que vous avez bien poussé les changements vers le dépôt
• Vérifiez que le fichier YAML est correctement formaté
• Vérifiez que vous avez les droits nécessaires
• Vérifiez que le nom du bucket est unique

Erreur d'accès au bucket

• Vérifiez que le bucket a été créé avec succès
• Vérifiez que les secrets ont été correctement livrés au DeploymentTarget
• Vérifiez que votre application utilise les bonnes informations de connexion
• Vérifiez que l'ACL est correctement configurée

Problèmes de performance

• Vérifiez que vous utilisez des préfixes appropriés
• Évitez d'utiliser des caractères spéciaux dans les noms de fichiers
• Utilisez des noms de fichiers courts et significatifs