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.
-
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_urlest l'adresse du service, sans le bucket. Sur AWS :https://s3.<région>.amazonaws.com.regionvautus-east-1si le service n'en déclare pas. -
À 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__KEYAjoutez aussi
SMARTAGT_MEDIASTORE_S3_ACCESS__KEY,SMARTAGT_MEDIASTORE_S3_SECRET__KEYà la liste--preserve-envde la commandeinit.$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 -
À 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)).PasswordPuis ajoutez-les à la valeur
Environmentde 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)).PasswordPuis 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.
-
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_urlest l'adresse du service, sans le bucket. Sur AWS :https://s3.<région>.amazonaws.com.regionvautus-east-1si le service n'en déclare pas. -
Donnez les clés par l'environnement, dans la session d'
initpuis dans celui des services de chaque nœud :SMARTAGT_MEDIASTORE_S3_ACCESS__KEYpour la clé d'accès,SMARTAGT_MEDIASTORE_S3_SECRET__KEYpour 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.