Utiliser un bucket S3 pour le stockage

Ce tutoriel vous guidera à travers les étapes pour créer et utiliser un bucket 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éé (voir Créer votre premier workspace)
Avoir au moins un DeploymentTarget créé (voir Déployer votre première application)
Avoir accès au dépôt GitOps de votre workspace

Vue d'ensemble

Les buckets S3 sont des espaces de stockage compatibles avec le protocole S3 d'Amazon Web Services. Ils permettent 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.

Étapes pour créer un bucket S3

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

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

2. Créer un fichier de définition 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.

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 :

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

Options de configuration importantes

acl : Contrôle 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
versioned : Active ou désactive le versioning des objets. Une fois activé, le versioning ne peut pas être désactivé.
forceDestroy : Si la suppression de cette ressource supprimera le bucket associé et toutes les données qu'il contient. Attention : ce champ est dangereux, à utiliser avec prudence.

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

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.

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

6. 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 :

{
  "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

Accédez à Vault via l'interface Atlas
Naviguez vers le chemin correspondant à votre DeploymentTarget
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 :

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

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

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;
  }
}

Bonnes pratiques

Utilisez toujours l'ACL private sauf si vous avez une raison spécifique de rendre le bucket public.
Activez le versioning si vous avez besoin de conserver l'historique des modifications des fichiers.
N'activez jamais forceDestroy en production, car cela pourrait entraîner une perte de données.
Utilisez des noms de bucket uniques et significatifs.
Organisez vos fichiers dans le bucket en utilisant des préfixes (similaires à des dossiers).
Mettez en place une lifecycle policy pour gérer la durée de vie des objets si nécessaire.

Que faire ensuite ?

Maintenant que vous avez configuré un bucket S3, vous pouvez :

Configurer une base de données pour stocker les métadonnées de vos fichiers
Mettre en place une CDN pour distribuer vos fichiers statiques
Configurer des lifecycle policies pour gérer automatiquement la durée de vie des objets