Installer la console

Guide d'exploitation : configurer, déployer et observer la passerelle. Ce que fait la fonctionnalité côté produit : guide produit ; l'appeler : guide développeur.

La console se déploie à part de la passerelle (son binaire, son image, son chart). Un seul mode pour métriques et traces : vos backends, ou la console collecteur OTLP de la passerelle ; jamais un mélange, refusé au rendu. Ce qu'elle montre : Lire avec la console.

Étapes

Essayer localement

Chaque écran a des données en quelques minutes : le trafic de démonstration de la pile passe par l'API de la passerelle, jamais par un magasin.

Installer en cluster

1. Choisir le mode et installer le chart, sans fournisseur d'identité :

   # Avec vos backends : la console lit votre Prometheus, construit des liens vers vos traces,
   # ne reçoit ni ne stocke rien
   helm install console oci://ghcr.io/flexwiz/charts/flexway-console --version <version> \
     --set gateway.url=http://orders-flexway-admin:9090 --set metrics.url=http://victoriametrics:8428 \
     --set traces.url='https://grafana.example/explore?traceId={trace_id}'
   
   # Sans backend : la passerelle pousse métriques et traces vers la console (OTLP, TLS, mTLS par
   # défaut), qui garde l'historique sur un volume persistant par réplique (8 Gio par défaut)
   helm install console oci://ghcr.io/flexwiz/charts/flexway-console --version <version> \
     --set gateway.url=http://orders-flexway-admin:9090 --set persistence.size=8Gi \
     --set otlp.tls.issuerRef.name=flexway-ca --set 'otlp.tls.clientNames={orders-flexway.observability.svc}'

2. Sans backend, faire pousser la passerelle vers la console (valeurs de la passerelle), et régler TLS côté console :

   values.yaml

   # Valeurs de la console : TLS obligatoire, mTLS par défaut (cert-manager, un Issuer de type CA)
   otlp:
     tls:
       issuerRef: { name: flexway-ca }                     # un Certificate est rendu pour la console
       clientNames: [orders-flexway.observability.svc]     # le nom du certificat de la passerelle
     # meshEncrypted: true                  # seulement si un maillage chiffre déjà (Linkerd, Istio strict)
   # Valeurs de la passerelle :
   tracesToConsole:
     enabled: true
     endpoint: https://console-flexway-console-otlp.observability:4317
     tls: { issuerRef: { name: flexway-ca } }   # rend son certificat client orders-flexway.observability.svc

3. Avec vos backends, écrire leurs adresses dans les valeurs ; le lien de trace accepte tout outil adressable par URL :

   values.yaml

   # values.yaml du chart services/console/deploy/helm
   gateway: { url: "http://orders-flexway-admin:9090" }      # la surface d'administration
   metrics: { url: "http://victoriametrics:8428" }           # une API Prometheus
   # Grafana Explore sur Tempo ; tout outil de traces adressable par URL convient :
   # {operation}, {client} (l'agent), {start_us}/{end_us} (microsecondes), {start_ms}/{end_ms} (millisecondes)
   traces:  { url: "https://grafana.example/explore?schemaVersion=1&orgId=1&panes=%7B%22a%22%3A%7B%22datasource%22%3A%22tempo%22%2C%22queries%22%3A%5B%7B%22refId%22%3A%22A%22%2C%22datasource%22%3A%7B%22type%22%3A%22tempo%22%2C%22uid%22%3A%22tempo%22%7D%2C%22queryType%22%3A%22traceql%22%2C%22query%22%3A%22%7Bresource.service.name%3D%5C%22flexway%5C%22%20%26%26%20span.operation_id%3D%5C%22{operation}%5C%22%7D%22%7D%5D%2C%22range%22%3A%7B%22from%22%3A%22{start_ms}%22%2C%22to%22%3A%22{end_ms}%22%7D%7D%7D" }

4. Se connecter avec le premier admin et inviter les autres comptes : Comptes et fournisseur d'identité.

Rétention

Sans backend : 35 jours de détail (retention.detail, réglable), agrégats journaliers

• requêtes, erreurs, tokens, euros - sur 13 mois (retention.daily) pour comparer mois sur mois et année sur année ; volume persistant obligatoire (le rendu est refusé avec persistence.enabled: false), plein à 80 % au plus, le plus ancien sortant d'abord. Au-delà de 35 jours, prévoir 10 Gio au moins ; au-delà encore, votre Prometheus.

Vérifier

1. Un bandeau en haut de Vue d'ensemble, Trafic, Amonts, Catalogue et Consommation dit la source et la rétention ; son panneau « Détails » montre les répliques qui envoient, le dernier envoi reçu et le volume (aux admins).
2. Chaque réplique de la passerelle apparaît sur la carte de la Vue d'ensemble, sous son nom de pod (service.instance.id) ; une réplique qui se tait 45 s passe unknown.
3. Diagnostic -> Erreurs liste les erreurs de chaque réplique, lues par le Service sans tête de la passerelle (orders-flexway-admin-headless).

À savoir

• Avec plusieurs répliques de la console sans backend, celle qui reçoit un envoi le relaie aux autres (file bornée, réessais) : chacune garde une copie complète ; une réplique revenue demande les deux dernières heures à une autre.
• Changer de mode = désinstaller puis réinstaller : le Secret d'état et ses comptes sont gardés.
• Avec traces.url (et metrics.url), le récepteur OTLP de la console reste coupé.
• Ce que la console garde d'une trace : les attributs d'une liste blanche (operation_id, upstream, tenant, politiques, statut, méthode et route du contrat), retirés de tout le reste à la réception - une adresse, un en-tête ou un corps n'y entrent pas. Une requête que l'échantillonnage en tête de la passerelle (observability.sampling.max_per_second) n'a pas retenue n'arrive jamais ; les erreurs restent toutes dans le journal des erreurs.
• Avec votre propre backend, le collecteur doit garder service.instance.id dans l'étiquette instance (Alloy et l'écriture OTLP de Prometheus le font par défaut) : sans elle, une seule « réplique » est vue.

Disponible depuis 0.1.0 ; sans backend, la console collecteur OTLP depuis 1.3.0.