Paramètres¶

La fiche client porte les vingt-deux variables qui distinguent une instance Tradeval d'une autre. Cette page les documente, elle ne les redéfinit pas : la référence reste scripts/install.env.example.

Obtenir sa fiche¶

cp scripts/install.env.example scripts/install.env

Le fichier obtenu, scripts/install.env, ne se commite jamais : il est exclu par .gitignore. Il ne se source pas non plus. Trois des scripts du guide (preflight.sh, render-config.sh, validate-install.sh) le lisent par scripts/lib-env.sh, un lecteur strict qui n'accepte que des affectations simples CLE=valeur : une fiche qui contiendrait une substitution de commande ou un appel de fonction est refusée avant d'être utilisée. Le quatrième script du guide, check-docs.sh, ne lit pas la fiche : il n'a ni option --env ni besoin d'elle.

Aucun secret ne figure dans la fiche. Le seul secret que les scripts consomment, CF_API_TOKEN, vient de l'environnement de l'opérateur, pas d'une ligne de la fiche.

Domaine et TLS¶

Variable	Exemple	Où la valeur atterrit	Effet si elle est fausse
`TV_DOMAIN`	`exemple.tld`	substituée par `render-config.sh` dans la quasi-totalité des manifests concernés, y compris sa forme échappée `domaine\.tld` dans les règles de réécriture de `core/coredns/` et de `core/lan-dns/`	`render-config.sh` refuse toute valeur qui n'a pas la forme d'un domaine ; une valeur acceptée mais fausse produit des hosts et un certificat pour le mauvais domaine
`TV_ACME_EMAIL`	`ops@exemple.tld`	substituée par `render-config.sh` dans le ClusterIssuer Let's Encrypt, sous `certs/` ; à écrire à la main comme destinataire des alertes dans `observability/prometheus-values.yaml`	une valeur vide bloque `preflight.sh` ; une adresse fausse mais bien formée n'est pas détectée par les scripts du guide, et les avis d'expiration du certificat partent à la mauvaise adresse
`TV_CF_ZONE_ID`	voir `scripts/install.env.example`	consommée par `preflight.sh`, qui interroge l'API Cloudflare pour vérifier que la zone est accessible avec `CF_API_TOKEN`	`preflight.sh` affiche `KO` avec le code HTTP retourné par Cloudflare ; le challenge DNS-01 ne peut pas fonctionner
`TV_CF_TUNNEL_NAME`	`exemple-prod`	nom donné par l'opérateur au tunnel Cloudflare, créé à l'étape 13 du Pas-à-pas, pas une valeur substituée dans un manifest	`core/cloudflare/cloudflared-config.yaml` porte encore l'UUID du tunnel d'origine, qu'aucune substitution ne touche : tant que cet UUID n'est pas remplacé à la main après `cloudflared tunnel create`, les pods cloudflared visent le tunnel du fournisseur et l'exposition publique ne monte pas

Cluster¶

Variable	Exemple	Où la valeur atterrit	Effet si elle est fausse
`TV_NODE_COUNT`	`6`	aucune substitution : la valeur n'atterrit dans aucun manifest, elle sert de nombre attendu au contrôle 1 de `validate-install.sh`, qui compte les noeuds `Ready` du cluster	`preflight.sh` échoue avant l'installation si la variable est absente, vide, ou n'est pas un entier positif, et `validate-install.sh` refuse la fiche sur le même critère ; une valeur bien formée mais fausse fait échouer le contrôle 1 sur un cluster sain, ou le laisse passer alors qu'un noeud manque

Le dimensionnement de référence est de six noeuds, trois control-plane et trois workers (Prérequis). C'est une valeur d'exemple, pas une contrainte du guide : un client qui déploie quatre ou huit noeuds écrit son nombre ici, et la recette de conformité passe au vert sur son cluster.

Réseau¶

Le rôle de six de ces huit variables et l'adressage à réserver avant de commencer : 02-prerequis.md. Cette table ajoute ce que 02-prerequis.md ne dit pas : où la valeur atterrit une fois la fiche remplie, et ce que produit une valeur fausse. TV_LAN_DNS_IP et TV_VPN_IP, absentes de 02-prerequis.md, sont documentées ici en entier.

Variable	Exemple	Où la valeur atterrit	Effet si elle est fausse
`TV_CP_ENDPOINT`	`10.0.0.100`	configuration machine Talos, générée par `talosctl` ; hors de la portée de `render-config.sh`	`talosctl` ne joint pas le control-plane, le bootstrap du cluster échoue
`TV_VIP`	`10.0.0.200`	substituée par `render-config.sh`, après `TV_VIP_RANGE` ; épinglée sur le Service Traefik par `spec.loadBalancerIP`, et configure aussi kube-vip côté Talos	`preflight.sh` échoue avant l'installation si la valeur sort de `TV_VIP_RANGE` ; sinon, `validate-install.sh` compare l'`EXTERNAL-IP` du service Traefik à cette variable après coup et échoue si elles diffèrent
`TV_VIP_RANGE`	`10.0.0.200-10.0.0.209`	configuration kube-vip côté Talos ; substituée par `render-config.sh` dans `core/kube-vip/kubevip-range.yaml`, avant `TV_VIP`, la plage devant se remplacer en premier sous peine d'être coupée en deux moitiés. Cette ConfigMap n'est lue par aucun composant que ce dépôt installe : la plage est à réserver et à documenter, elle n'est pas distribuée (étape 5 du Pas-à-pas)	aucun effet direct, puisque rien ne lit cette plage ; `preflight.sh` s'en sert en revanche pour refuser une `TV_VIP`, `TV_LAN_DNS_IP` ou `TV_VPN_IP` qui en sort
`TV_TRAEFIK_CLUSTERIP`	`10.111.0.21`	substituée par `render-config.sh` dans `core/cloudflare/cloudflared-config.yaml` et `core/traefik/traefik.yaml`	`validate-install.sh` interroge CoreDNS pour un host public et échoue si la résolution ne pointe pas vers cette ClusterIP
`TV_LAN_DNS_IP`	`10.0.0.201`	adresse du DNS à horizon partagé (`core/lan-dns/`), épinglée sur son Service par l'annotation `kube-vip.io/loadbalancerIPs` et annoncée par kube-vip ; substituée par `render-config.sh` ; doit tomber dans `TV_VIP_RANGE`, comme `TV_VIP` ; le DHCP du client doit la pousser aux postes du LAN	`preflight.sh` échoue si l'adresse sort de `TV_VIP_RANGE` ; sinon kube-vip annonce l'adresse écrite dans le manifeste, quelle qu'elle soit, et les postes du LAN interrogent une autre adresse que celle qui répond
`TV_VPN_IP`	`10.0.0.202`	adresse du concentrateur WireGuard in-cluster, épinglée par `spec.loadBalancerIP` dans `core/vpn/wireguard-incluster.yaml` ; substituée par `render-config.sh` ; doit tomber dans `TV_VIP_RANGE`, comme `TV_VIP`. Ce manifeste n'est pas appliqué par la procédure, voir l'étape 13 du Pas-à-pas	`preflight.sh` échoue si l'adresse sort de `TV_VIP_RANGE` ; sans effet ensuite, le manifeste qui la porte n'étant pas appliqué
`TV_POD_SUBNET`	`10.244.0.0/16`	configuration machine Talos, générée par `talosctl`, et substituée par `render-config.sh` dans `core/vpn/peer-officer.template.conf`, où le tunnel annonce la plage aux agents	conflit d'adressage possible avec le réseau existant du client, qu'aucun contrôle du guide ne détecte ; et si la valeur de la fiche diffère de celle réellement posée dans Talos, le tunnel monte, les agents se connectent et ne joignent rien derrière, sans erreur
`TV_SVC_SUBNET`	`10.96.0.0/12`	configuration machine Talos, générée par `talosctl`, et substituée par `render-config.sh` dans `core/vpn/peer-officer.template.conf`, comme la plage des pods	même effet que pour `TV_POD_SUBNET` : collision d'adressage non détectée, ou routage VPN muet si la fiche et Talos divergent

L'exemple de TV_TRAEFIK_CLUSTERIP est le seul de cette table qui ne recopie pas la valeur de scripts/install.env.example. Ce n'est pas un écart : la fiche d'exemple porte la ClusterIP réelle de l'instance de référence, et aucune page de ce guide ne recopie une valeur d'instance. Les deux tombent dans 10.96.0.0/12, et ni l'une ni l'autre n'est à reprendre telle quelle : c'est la ClusterIP réservée sur le cluster du client qui va dans la fiche.

core/coredns/coredns-configmap.yaml ne porte aucune adresse IP en dur : son en-tête dit explicitement que CoreDNS continue de résoudre le service Traefik, pas une ClusterIP recopiée. preflight.sh vérifie que TV_VIP, TV_LAN_DNS_IP et TV_VPN_IP tombent toutes les trois dans TV_VIP_RANGE.

Identité¶

Variable	Exemple	Où la valeur atterrit	Effet si elle est fausse
`TV_KC_REALM`	`tradeservices`	hors de la portée de `render-config.sh` : le realm se crée dans Keycloak, et la même valeur se retrouve dans les clés Vault qui portent l'issuer OIDC (page 06)	issuer OIDC incohérent entre Keycloak et les services : tous les tokens rejetés, voir plus bas

Images¶

Variable	Exemple	Où la valeur atterrit	Effet si elle est fausse
`TV_REGISTRY`	`registry.exemple.tld`	substituée par `render-config.sh` : l'hôte est réécrit sur les onze images applicatives ; les images tierces gardent leur registre d'origine	onze pods en `ImagePullBackOff`

Aucune variable ne paramètre le tag des images : les dix images applicatives portent un tag immuable par build, et l'image Keycloak porte prod épinglé par son digest, qu'un autre registre ne reproduit pas. Une variable unique fabriquerait des références qui n'existent dans aucun registre.

Le registre du client doit porter ces onze images sous leurs noms et leurs tags exacts. render-config.sh réécrit l'hôte, il ne pousse rien.

Stockage¶

Variable	Exemple	Où la valeur atterrit	Effet si elle est fausse
`TV_STORAGE_CLASS`	`longhorn`	aucun manifest ne nomme de StorageClass ; `TV_STORAGE_CLASS` est un contrôle de `preflight.sh`	`preflight.sh` distingue deux échecs : aucune StorageClass par défaut sur le cluster, et les PVC resteront `Pending` ; ou une StorageClass par défaut existe mais son nom diffère de `TV_STORAGE_CLASS`

Données externes¶

Chacune de ces six variables porte déjà, dans scripts/install.env.example, un commentaire qui donne son format, l'endroit exact où elle atterrit et le symptôme d'une valeur fausse. Cette table ne les recopie pas : elle renvoie à la fiche.

Variable	Exemple	Où la valeur atterrit	Effet si elle est fausse
`TV_PG_HOST`	`pg.exemple.tld:5432`	Vault, à l'étape 11 du Pas-à-pas, d'où ESO l'injecte dans les pods	voir le commentaire de la variable dans `scripts/install.env.example`
`TV_KAFKA_BOOTSTRAP`	`kafka.exemple.tld:9092`	Vault, à l'étape 11 du pas-à-pas	voir le commentaire de la variable dans `scripts/install.env.example`
`TV_REDIS_HOST`	`redis.exemple.tld:6379`	Vault, à l'étape 11 du pas-à-pas	voir le commentaire de la variable dans `scripts/install.env.example`
`TV_ES_HOST`	`es.exemple.tld:9200`	Vault, à l'étape 11 du pas-à-pas	voir le commentaire de la variable dans `scripts/install.env.example`
`TV_MINIO_ENDPOINT`	`minio.exemple.tld:9000`	Vault, à l'étape 11 du pas-à-pas, et `secrets/vault-backup.yaml` par `render-config.sh`	voir le commentaire de la variable dans `scripts/install.env.example`
`TV_SMTP_HOST`	`smtp.exemple.tld:587`	Vault, à l'étape 11 du pas-à-pas, et `observability/prometheus-values.yaml` par `render-config.sh` (identifiant et expéditeur à éditer à la main)	voir le commentaire de la variable dans `scripts/install.env.example`

preflight.sh vérifie que chacun des six endpoints répond, y compris lancé avec --skip-cluster : ce drapeau ne saute que les deux sections qui exigent un cluster, et ces six endpoints lui sont extérieurs. Le tout premier lancement, avant même que le cluster existe, les exerce donc déjà.

La base de données de Keycloak ne figure pas dans cette table, ni dans la fiche : elle est pourtant obligatoire, et aucun manifeste du dépôt ne la crée. Voir Prérequis.

Ce qui ne se saisit pas¶

Trois valeurs se calculent à partir de TV_DOMAIN et TV_KC_REALM. Elles ne figurent pas dans la fiche, et une fiche qui les porterait quand même serait une occasion d'incohérence plutôt qu'une garantie :

Valeur dérivée	Formule
issuer OIDC	`https://auth.${TV_DOMAIN}/realms/${TV_KC_REALM}`
`KC_HOSTNAME`	`auth.${TV_DOMAIN}`
hosts d'Ingress	`<service>.${TV_DOMAIN}`

Une valeur dérivée saisie à la main peut diverger de la formule sans qu'aucun contrôle du guide ne le remarque au moment de la saisie : scripts/install.env n'a pas de champ pour elle, donc rien ne la relit. scripts/validate-install.sh ne prend d'ailleurs pas ce risque : il recalcule lui-même l'issuer depuis TV_DOMAIN et TV_KC_REALM plutôt que de lire une valeur saisie.

Ce que le paramétrage ne peut pas faire¶

scripts/render-config.sh se termine par un bloc de huit entrées qui énonce ce qu'aucune substitution de texte ne fait. Six sont des opérations, toutes nécessaires, aucune couverte par la fiche client ; les deux dernières entrées du script sont des constats sur le dépôt, pas des gestes à faire. Les six opérations :

Cloudflare : la zone du domaine et un jeton API scopé (Zone:DNS:Edit et Zone:Zone:Read) pour le challenge DNS-01. Symptôme d'oubli : le certificat wildcard n'est jamais émis, et tant qu'il n'est pas Ready, aucun host de la plateforme n'est joignable.
Vault : les clés qui portent l'issuer OIDC et les URLs d'API des services .NET (AUTH_KEYCLOAK_ISSUER, NEXTAUTH_URL, NEXTAUTH_URL_INTERNAL, l'authority OIDC des cinq services .NET, les *_API_BASE_URL, CONTENT_SERVICE_URL, ALLOWED_ORIGINS). Symptôme d'oubli : KC_HOSTNAME renommé sans que ces clés soient patchées en conséquence, et tous les tokens sont rejetés avec l'erreur IDX10205.
Realm Keycloak : la création du realm ${TV_KC_REALM}, ses Valid Redirect URIs et ses Web Origins. Symptôme d'oubli : connexion refusée ou redirection après connexion qui échoue, alors que le realm attendu n'existe simplement pas encore sous ce nom.
Images frontend : les variables NEXT_PUBLIC_* sont figées au moment du build, pas au démarrage du conteneur. Symptôme d'oubli : les portails continuent d'appeler l'ancien domaine après le déploiement, un redéploiement seul ne suffit pas, il faut reconstruire les images.
Publication des images : le registre ${TV_REGISTRY} doit porter les onze images applicatives sous leurs noms et leurs tags exacts. render-config.sh réécrit l'hôte, il ne pousse rien. Symptôme d'oubli : pods en ImagePullBackOff.
UUID du tunnel Cloudflare : core/cloudflare/cloudflared-config.yaml porte l'UUID du tunnel d'origine, qu'aucune substitution ne touche. Symptôme d'oubli : après cloudflared tunnel create, tant que cet UUID n'est pas remplacé à la main, les pods cloudflared visent le tunnel du fournisseur et l'exposition publique ne monte pas.

Une septième valeur échappe à la fiche sans que le script la nomme : le nom de l'interface réseau de kube-vip. core/kube-vip/kube-vip-ds.yaml fixe vip_interface à ens34, le nom de carte des VM de l'instance de référence. Aucune variable ne le paramètre, aucune substitution ne le touche, et un nom qui ne correspond à rien laisse les pods kube-vip Running sans jamais publier d'adresse. Relevé et correctif à l'étape 5 du Pas-à-pas.

Le realm et les endpoints de données externes ne vivent pas dans les manifests

Ce script ne peut donc pas les changer. Ils se règlent dans Keycloak et dans Vault, détaillé à la page 07-configuration.md.

Appliquer la fiche¶

scripts/render-config.sh --env scripts/install.env            # apercu
scripts/render-config.sh --env scripts/install.env --apply    # applique
git diff --stat

Attendu : 42 fichiers modifiés, une fois les douze familles de valeurs substituées (domaine, VIP, plage, ClusterIP Traefik, registre, DNS de LAN, VPN, adresse ACME, sous-réseau des pods, sous-réseau des services, MinIO, relais SMTP). Le script annonce lui-même leur nombre, Substitutions actives (12), avant de lister les fichiers : c'est cette ligne qui fait foi si le dépôt évolue. Un git diff --stat vide signifie que la fiche porte encore les valeurs d'origine du dépôt, pas celles du client.