Installation

La plateforme Avatar est empaquetée sous forme de chart Helm : elle peut donc être déployée dans un cluster Kubernetes que vous exploitez déjà. Tous les composants de l'architecture — l'API, le client web, l'ordonnanceur et les workers Dask, le stockage objet et le fournisseur d'identité Authentik — sont installés par ce seul chart.

Suivez les étapes ci-dessous pour déployer la plateforme Avatar dans votre cluster.

Ce que le chart fait, et ce qu'il ne fait pas

Le chart ne crée volontairement aucune infrastructure de cluster. Il attend qu'un contrôleur d'ingress, une StorageClass, un serveur PostgreSQL et des identifiants de pull existent déjà, et il crée tout ce qui s'exécute par-dessus — y compris les bases de données Avatar et Authentik. Les prérequis ci-dessous détaillent ce partage.

Prérequis du cluster

Parcourez les prérequis communs aux deux chemins auto-hébergés, puis vérifiez que tous les éléments de cette liste existent avant l'installation.

• Cluster Kubernetes
  • Un contrôleur ingress-nginx, avec un LoadBalancer (ou un NodePort, ou MetalLB) devant lui
  • Une StorageClass par défaut — le stockage objet s'exécute sous forme de StatefulSets avec des PersistentVolumeClaims
  • Un CNI qui applique les NetworkPolicy (Calico, Cilium, …), si vous souhaitez l'isolation réseau
  • kubectl et helm (v3) configurés sur le cluster
• Réseau et configuration TLS
  • Un nom de domaine pointant vers le load balancer. Toutes les URL publiques que le chart transmet à l'API, au client web et à Authentik sont dérivées de ce seul nom.
  • Un Secret kubernetes.io/tls contenant le certificat de ce domaine, dans le namespace de la release. Le chart ne le crée jamais.
  • Si ce certificat a été émis par une autorité de certification privée ou interne, le certificat de cette autorité — il doit être transmis à l'API via api.caBundle, sans quoi les connexions échouent
  • Un serveur SMTP joignable depuis le cluster, pour les réinitialisations de mot de passe et les invitations
  • Octopize vous a fourni vos identifiants quay.io
• Base de données
  • Un serveur PostgreSQL joignable depuis le cluster
  • Un compte administrateur sur ce serveur. La base Avatar et celle d'Authentik sont créées pour vous à partir de ce compte.
• Réseau
  • Les flux listés dans les Prérequis communs sont ouverts. L'artefact du chart Helm est lui aussi récupéré depuis quay.io.

Ce que le chart crée pour vous

• La base de données Avatar, son rôle, ses tables et la première organisation.
• Le rôle d'Authentik, sa base de données et ses extensions. Positionnez authentikDatabase.createDatabase: false si un DBA les a déjà créés.
• Le stockage objet, lorsque seaweedfs.enabled vaut true.
• Les objets Ingress et toutes les URL publiques transmises à l'API, au client web et à Authentik.

Côté base de données, vous fournissez un serveur et un compte administrateur, et rien d'autre.

Si vous utilisez un contrôleur d'ingress autre qu'ingress-nginx, positionnez ingress.enabled: false et créez vos propres objets Ingress. Les URL restent identiques.

Images de conteneurs

Les images et leur taille sont listées dans les Prérequis.

Les images avatar-service-api et avatar-web sont privées, de même que avatar-connector si vous activez le connecteur de bases de données. Octopize vous fournit les identifiants quay.io à la signature du contrat ; le chart les attend sous la forme d'un config.json Docker encodé en base64 dans imageCredentials.dockerConfigJson, dont il crée le Secret docker-local-pull-secret :

base64 -w0 < ~/.docker/config.json

Préparer un fichier de valeurs

Le chart embarque un fichier de valeurs d'exemple complet et fonctionnel. Récupérez le chart et copiez-le :

helm pull oci://quay.io/octopize/helm/services-api/avatar --version <version> --untar
cp avatar/example-values.yaml my-values.yaml

Chaque PLACEHOLDER_ de ce fichier doit être remplacé, et chacun est accompagné de la commande qui le génère.

L'archive contient aussi un script qui fabrique les identifiants pour vous. Lancez-le, et donnez le fichier qu'il écrit à Helm après votre propre fichier de valeurs :

cd avatar && bash scripts/generate-secrets.sh

Utilisez bash, et non ./. Helm empaquette chaque fichier avec le mode 0644, donc la copie dans l'archive n'est pas exécutable. Helm obéit au dernier fichier --values, donc avatar-secrets.yaml remplace ces clés dans my-values.yaml. Gardez ces clés hors de my-values.yaml, donnez le fichier généré à chaque mise à jour, et conservez-le. Voir Générer les secrets.

Le script ne fabrique pas les valeurs qui appartiennent à votre propre infrastructure. Vous les renseignez vous-même. Au minimum, renseignez :

Valeur	De quoi il s'agit
ingress.host	Le domaine sur lequel la plateforme est servie
ingress.tls.secretName	Un Secret kubernetes.io/tls existant pour ce domaine
imageCredentials.dockerConfigJson	base64 d'un config.json Docker avec les identifiants quay.io/octopize
api.image.tag	Le tag de l'image de l'API
web.image.tag	Le tag de l'image du client web
database.host / database.port	Votre serveur PostgreSQL
database.adminUsername / database.adminPassword	Identifiants administrateur, utilisés une fois pour créer les bases
api.config.organizationName	Le nom de votre organisation
smtp.host et les autres valeurs SMTP	Votre serveur SMTP

Voir Configuration pour la référence complète des valeurs.

Pour un namespace appliquant le Pod Security Standard restricted, appliquez la surcouche example-values-restricted.yaml par-dessus votre propre fichier avec un second --values — voir Pod Security Standard restricted.

Deux valeurs doivent correspondre à autre chose

• dask.scheduler.image.tag et dask.worker.image.tag doivent être égaux à api.image.tag.
• storage.sseKek est générée une seule fois et n'est jamais modifiée. Lors de la migration d'un SeaweedFS existant, récupérez la valeur depuis l'ancien filer — voir Chiffrement SeaweedFS. Écrivez-la dans avatar-secrets.yaml si vous avez utilisé le script, car Helm obéit à ce fichier en dernier.

Vous renseignez les quatre valeurs sso une seule fois. L'API s'authentifie avec clientId et clientSecret, et le blueprint Authentik intégré enregistre le même fournisseur OAuth. apiToken et webhookSecret révoquent les clés d'API d'un utilisateur que vous désactivez ou supprimez dans Authentik. Helm ne peut pas écrire dans les valeurs d'un sous-chart, donc les entrées AVATAR_AUTHENTIK_BLUEPRINT_* sous authentik.global.env référencent les objets dans lesquels le chart écrit ces quatre valeurs. Laissez ces entrées telles qu'example-values.yaml les pose. Voir SSO.

Un certificat issu d'une autorité privée nécessite api.caBundle

Si le certificat de votre domaine a été émis par une autorité interne ou est auto-signé, toutes les connexions échouent avec CERTIFICATE_VERIFY_FAILED tant que vous n'avez pas renseigné api.caBundle.

Installer

helm install avatar oci://quay.io/octopize/helm/services-api/avatar \
  --version <version> \
  --namespace avatar --create-namespace \
  --values my-values.yaml

Une valeur obligatoire manquante fait échouer le rendu avec un message la nommant : une installation qui se déclare réussie a donc au moins reçu une configuration complète. Le chart affiche ensuite la table de routage du déploiement.

Suivre le démarrage

kubectl -n avatar get pods -w

Les pods Authentik restent en Init:0/1 jusqu'à ce que leur base de données réponde. C'est l'init container wait-for-db qui fait son travail, et non un blocage — consultez les journaux du Job d'amorçage pour voir où il en est :

kubectl -n avatar get jobs
kubectl -n avatar logs job/avatar-authentik-db-init-<version-du-chart>

Le Job est supprimé après sa fin (authentikDatabase.ttlSecondsAfterFinished) : consultez ses journaux tant qu'il est encore présent.

Créer le premier administrateur Authentik

Obligatoire, et non automatisé

Une installation où personne n'a suivi ce parcours dispose d'un fournisseur d'identité que personne ne peut administrer.

Contrairement à l'installation Docker, le chart ne définit pas les variables AUTHENTIK_BOOTSTRAP_* — Octopize ne détient pas l'identifiant administrateur de votre fournisseur d'identité. Suivez à la place le parcours d'initialisation d'Authentik :

https://<ingress.host>/sso/if/flow/initial-setup/

Définissez-y le mot de passe du compte akadmin. Ce compte administre ensuite les utilisateurs, les groupes et le fournisseur OAuth auquel l'API Avatar s'adresse — voir Gestion des utilisateurs.

Faites-le sans attendre : jusque-là, le parcours est accessible à quiconque peut joindre le déploiement. Il cesse de fonctionner dès que le premier administrateur existe.

Se connecter

Rendez-vous sur https://<ingress.host>/web. Vous êtes redirigé vers Authentik pour vous connecter, puis ramené dans l'interface Avatar.

Étapes suivantes

Une fois la stack en fonctionnement, vérifiez que tout est sain en suivant le guide Vérification et dépannage.

Pour permettre à vos utilisateurs de copier et d'anonymiser des bases de données avec les exécutions sur base de données, activez le connecteur de bases de données. Il est désactivé par défaut.

Essayer sur un cluster local

Pour une évaluation, le même fichier de valeurs s'installe sur un cluster mono-nœud — minikube, kind, k3s — au prix de quelques ajustements. Ils n'ont rien de spécifique à Avatar : ce sont simplement les choses qu'un poste de travail ne fournit pas.

• Activez un contrôleur d'ingress et une StorageClass par défaut. Sur minikube : minikube addons enable ingress default-storageclass storage-provisioner.
• Faites pointer ingress.host vers un nom qui résout vers le cluster — <ip-du-cluster>.nip.io fonctionne sans toucher au DNS.
• Mettez ingress.tls.enabled: false et laissez ingress.tls.secretName vide. Toutes les URL utilisent alors http:// — acceptable pour une évaluation, jamais en production.
• Exécutez un PostgreSQL dans le cluster et faites pointer database.host vers son Service.
• Faites pointer les valeurs SMTP vers un collecteur de mails local. L'envoi de mail doit fonctionner même localement, sans quoi la création d'utilisateur échoue.
• Réduisez seaweedfs.volume.dataDirs[0].size et dask.worker.replicas, et adaptez les arguments -allowedOrigins à votre hôte en http://.
• Neutralisez l'anti-affinité des pods SeaweedFS (seaweedfs.master.affinity, .volume.affinity, .filer.affinity à ""), qu'un cluster mono-nœud ne peut pas satisfaire.

Tout le reste reste identique au fichier de valeurs d'exemple. Le flux de création du premier administrateur reste requis.

Déploiements en environnement isolé

Parcourez d'abord la checklist pour environnement isolé commune aux deux chemins : images recopiées, archive du chart (helm pull … --untar, puis installation depuis le répertoire local), certificat local et serveur SMTP interne.

Pointez ensuite les images vers votre miroir avec global.imageRegistry :

global:
  imageRegistry: registry.internal.example

Elle couvre l'API, le client web et SeaweedFS. Quatre autres images intègrent leur registre dans une chaîne plus large et doivent être pointées vers le miroir à la main : dask.scheduler.image.repository, dask.worker.image.repository, authentik.global.image.repository et authentikDatabase.image.

Désactivez ensuite les deux appels sortants que la plateforme effectuerait sinon :

api:
  config:
    compatibilityMappingUrl: "disabled"
    sentry:
      enabled: false

Pour plus de détails sur la recopie des images Authentik, consultez la documentation Authentik sur les environnements isolés.