Aller au contenu

Configurer S3

Raccordez SmartAGT à un bucket S3 privé. S3 est requis en conteneurs et peut être retenu sur VM, selon le mode de stockage.

Raccordez SmartAGT à un bucket S3 privé. En cluster, S3 est requis : tous les nœuds Backend partagent le même bucket, d'où chacun relit les documents déposés par les autres. Voir le mode de stockage.

Prérequis

  • Un service compatible S3 qui respecte les exigences ci-dessous, sur site ou chez un fournisseur cloud.
  • Un bucket privé, créé par l'administrateur du stockage : SmartAGT ne crée jamais le bucket.
  • Une clé d'accès S3 limitée à ce bucket, avec les quatre droits ci-dessous.
Exigence Attendu
API S3 avec signature V4 et ListObjectsV2
Accès HTTPS depuis chaque hôte Backend, certificat reconnu par ces hôtes
Adressage Par chemin, https://hôte/bucket/clé, le défaut des services sur site.
Sur AWS, hors PrivateLink, SmartAGT emploie l'hôte virtuel, https://bucket.hôte/clé
Bucket Dédié à cette installation, partagé par tous ses nœuds, sans autre usage
Droits s3:ListBucket sur le bucket. s3:GetObject, s3:PutObject et s3:DeleteObject sur ses objets
Object Lock Non pris en charge
Versionnage Admis, avec une règle de cycle de vie qui expire les versions non courantes
Politique d'accès de la clé

Format standard des politiques S3. Sur un service qui attribue les droits par clé et par bucket, accordez la lecture et l'écriture sur le bucket.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": ["arn:aws:s3:::smartagt-documents"]
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": ["arn:aws:s3:::smartagt-documents/*"]
    }
  ]
}

Procédure

1. Préparer la confiance

Avec une autorité privée, installez sa chaîne de confiance sur chaque hôte Backend avant l’initialisation. En conteneurs, ajoutez-la au magasin de confiance de l’image utilisée.

sudo install -m 644 s3-ca.crt /usr/local/share/ca-certificates/smartagt-s3.crt
sudo update-ca-certificates

Dans PowerShell administrateur :

Import-Certificate -FilePath '.\s3-ca.crt' -CertStoreLocation Cert:\LocalMachine\Root

2. Raccorder le bucket

Les clés d'accès S3 sont des secrets : elles ne figurent jamais dans le YAML. Comme le mot de passe PostgreSQL et la KEK, elles passent par l'environnement.

  1. Dans le YAML Backend livré, renseignez le bloc suivant avec les paramètres du bucket, sans les clés :

    smartagt:
      mediastore:
        backend: s3
        s3:
          endpoint_url: "https://storage.example.org"
          bucket: "smartagt-documents"
          region: "eu-west-1"
    

    endpoint_url est l'adresse du service, sans le bucket. Sur AWS : https://s3.<région>.amazonaws.com. region vaut us-east-1 si le service n'en déclare pas.

  2. À l'initialisation, ajoutez les clés à la session avant de lancer init :

    read -rsp "Clé d'accès S3 : " SMARTAGT_MEDIASTORE_S3_ACCESS__KEY; echo
    read -rsp 'Secret S3 : ' SMARTAGT_MEDIASTORE_S3_SECRET__KEY; echo
    export SMARTAGT_MEDIASTORE_S3_ACCESS__KEY SMARTAGT_MEDIASTORE_S3_SECRET__KEY
    

    Ajoutez aussi SMARTAGT_MEDIASTORE_S3_ACCESS__KEY,SMARTAGT_MEDIASTORE_S3_SECRET__KEY à la liste --preserve-env de la commande init.

    $env:SMARTAGT_MEDIASTORE_S3_ACCESS__KEY = [Net.NetworkCredential]::new('', (Read-Host "Clé d'accès S3" -AsSecureString)).Password
    $env:SMARTAGT_MEDIASTORE_S3_SECRET__KEY = [Net.NetworkCredential]::new('', (Read-Host 'Secret S3' -AsSecureString)).Password
    
  3. À la création des services, ajoutez les mêmes clés à leur environnement :

    Dans /etc/smartagt/backend.env, à la suite du mot de passe et de la KEK :

    SMARTAGT_MEDIASTORE_S3_ACCESS__KEY=<clé d'accès S3>
    SMARTAGT_MEDIASTORE_S3_SECRET__KEY=<secret S3>
    

    Avant la boucle de création, lisez les clés :

    $s3Key = [Net.NetworkCredential]::new('', (Read-Host "Clé d'accès S3" -AsSecureString)).Password
    $s3Secret = [Net.NetworkCredential]::new('', (Read-Host 'Secret S3' -AsSecureString)).Password
    

    Puis ajoutez-les à la valeur Environment de chaque service :

    Set-ItemProperty "HKLM:\SYSTEM\CurrentControlSet\Services\$($service.Name)" -Name Environment -Type MultiString -Value "SMARTAGT_CORE_DATABASE_PASSWORD=$password", "SMARTAGT_KEK=$kek", "SMARTAGT_MEDIASTORE_S3_ACCESS__KEY=$s3Key", "SMARTAGT_MEDIASTORE_S3_SECRET__KEY=$s3Secret"
    

    Avant la boucle de création, lisez les clés :

    $s3Key = [Net.NetworkCredential]::new('', (Read-Host "Clé d'accès S3" -AsSecureString)).Password
    $s3Secret = [Net.NetworkCredential]::new('', (Read-Host 'Secret S3' -AsSecureString)).Password
    

    Puis ajoutez-les à l'environnement de chaque service :

    nssm set $service.Name AppEnvironmentExtra "SMARTAGT_CORE_DATABASE_PASSWORD=$password" "SMARTAGT_KEK=$kek" "SMARTAGT_MEDIASTORE_S3_ACCESS__KEY=$s3Key" "SMARTAGT_MEDIASTORE_S3_SECRET__KEY=$s3Secret"
    

En conteneurs, injectez les deux variables depuis le gestionnaire de secrets de votre infrastructure.

Résultat attendu : init journalise Stockage S3 vérifié et les services démarrent.

Le raccordement se déclare à l'installation du Backend, à l'identique sur tous les nœuds : Installer le Backend.

  1. Dans le YAML commun des nœuds Backend, renseignez le bloc suivant, sans les clés d'accès :

    smartagt:
      mediastore:
        backend: s3
        s3:
          endpoint_url: "https://storage.example.org"
          bucket: "smartagt-documents"
          region: "eu-west-1"
    

    endpoint_url est l'adresse du service, sans le bucket. Sur AWS : https://s3.<région>.amazonaws.com. region vaut us-east-1 si le service n'en déclare pas.

  2. Donnez les clés par l'environnement, dans la session d'init puis dans celui des services de chaque nœud : SMARTAGT_MEDIASTORE_S3_ACCESS__KEY pour la clé d'accès, SMARTAGT_MEDIASTORE_S3_SECRET__KEY pour le secret.

Résultat attendu : sur chaque nœud, les services démarrent sans erreur de raccordement S3.

Remarque

init et l'API contrôlent le bucket et les quatre droits à chaque démarrage : ils déposent, relisent et suppriment un objet témoin smartagt-probe/…. Les workers vérifient l'accès au bucket.

Cas particuliers

Refus au démarrage

init ou l'API s'arrêtent avec un message qui nomme la cause.

Message Action
Bucket S3 « … » introuvable Créer le bucket, ou corriger son nom
Accès refusé au bucket S3 « … » Vérifier la clé, puis le droit s3:ListBucket
… refusé, droit s3:… manquant Accorder le droit nommé
Bucket S3 « … » refusé (HTTP 301, 307 ou 400) Corriger region ou endpoint_url
Un bucket sous Object Lock … n'est pas pris en charge Employer un bucket sans Object Lock
Stockage S3 injoignable à l'adresse … Vérifier le réseau, le proxy et la confiance du certificat. La nature suit l'adresse : tls_rejected, dns_unresolved, connection_refused, timeout
Proxy et pare-feu

Si le service n'est joignable que par un proxy, déclarez HTTPS_PROXY, et NO_PROXY si besoin, dans la session d'init et dans l'environnement des services. Sous Windows, le proxy WinHTTP de la machine convient aussi. Un proxy saisi ensuite dans la console l'emporte.

Sur AWS, SmartAGT joint l'hôte du bucket, <bucket>.s3.<région>.amazonaws.com : une exception de proxy ou une règle de pare-feu s'écrit *.s3.<région>.amazonaws.com.

Bucket versionné

Les objets supprimés et les témoins de démarrage restent en versions non courantes. Une règle de cycle de vie qui les expire évite que le bucket grossisse sans fin.

Réinitialisation

init --reset, services arrêtés sur tous les nœuds, supprime du bucket les objets de SmartAGT. Tout autre objet est conservé et signalé dans le journal : Purge S3 terminée (supprimés=…, conservés=…).

Panne du stockage en service

Les utilisateurs lisent « Le stockage des fichiers est injoignable », « ne répond pas dans les délais » ou « a refusé l'opération ». La cause est dans le journal de l'API : S3 <opération> en échec (…) ou S3 <opération> refusé (HTTP …). SmartAGT reprend seul au retour du service, sans redémarrage. Un document n'est jamais retiré de la base tant que son absence n'est pas prouvée par le service.