# Installer la console

> Installer la console avec vos backends de métriques et de traces, ou sans backend comme collecteur OTLP de la passerelle.

Guide - Depuis la version 0.1.0 - Flexway v1.7.1 - https://flexway.io/docs/operations-console-install/

> Guide d'exploitation : configurer, déployer et observer la passerelle. Ce que fait la fonctionnalité côté produit : [guide produit](https://flexway.io/docs/product-overview/) ; l'appeler : [guide développeur](https://flexway.io/docs/developer-overview/).

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](https://flexway.io/docs/operations-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é** :

   ```bash
   # 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 :

   ```yaml title="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 :

   ```yaml title="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é](https://flexway.io/docs/operations-console-accounts/).

### 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.

> [!WARNING]
> Le port d'administration de la passerelle est fermé **par défaut** (`admin.networkPolicy`) : la console y
> entre (même namespace par défaut, `admin.networkPolicy.console.podLabels`) ; un outil qui lit encore
> `/metrics` doit être ajouté à `admin.networkPolicy.from`. Ne pas exposer la console publiquement.

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