Agent SaaS

Ce guide décrit comment les clients RAC/M Identity en tant que service (SaaS) déploient le serveur de connecteurs ICF (ConnId) sur leur propre infrastructure à l’aide de l’image de conteneur racm-icf-server-agent. La console génère les étapes de déploiement pour Docker, Podman ou Kubernetes (un exemple de chart Helm). L’agent synchronise les artefacts de connecteurs depuis RAC/M, s’enregistre auprès de RAC/M, puis ouvre un tunnel sortant sécurisé ou écoute pour que RAC/M joigne ConnId directement—selon le mode de connexion configuré pour le serveur ICF.

SaaS uniquement

La fonctionnalité agent serveur ICF s’applique uniquement à RAC/M Identity en tant que service (SaaS). Elle n’est pas prise en charge pour les déploiements RAC/M Identity sur site ou en cloud privé.

Cette page couvre les deux types de connexion agent SaaS (Agent et Direct). Pour les serveurs Désuet et Interne ainsi qu’un aperçu de l’assistant de configuration, voir Serveurs ICF.

Modes de connexion

Disponible depuis3.21.0 +

L’enregistrement renvoie un connectionMode valant TUNNEL ou DIRECT. L’image agent (0.6.5 ou ultérieure) doit être déployée avec une version de RAC/M qui émet ce champ. Dans la console, cela correspond aux Types de connexion Agent et Direct.

Mode	Comment RAC/M joint ConnId	Réseau sur l’hôte agent
Tunnel (TUNNEL) — Agent	L’agent ouvre un tunnel WebSocket sortant vers RAC/M ; RAC/M se connecte via ce tunnel.	Aucune publication entrante de ConnId n’est requise. Autorisez le HTTPS sortant (et le WebSocket du tunnel) vers RAC/M.
Direct (DIRECT) — Direct	Le serveur ICF écoute sur l’hôte et le port configurés ; RAC/M s’y connecte. L’agent ne démarre pas le client de tunnel.	Publiez ConnId (port conteneur 8759, TLS) avec Docker -p portHôte:8759 (ou l’équivalent Compose/Kubernetes). Ouvrez le pare-feu / les groupes de sécurité pour que RAC/M atteigne ce port hôte.

Utilisez Agent lorsque l’hôte agent n’accepte aucune connexion entrante depuis RAC/M. Utilisez Direct lorsque l’hôte n’ouvre pas de connexion sortante mais que RAC/M peut le joindre sur le port configuré (par exemple, réseau partagé ou redirection de port contrôlée).

Règles de pare-feu et réseau

Un agent serveur ICF ne nécessite qu’un accès réseau sortant vers RAC/M. Sur l’hôte agent, ouvrez une règle sortante vers votre point d’accès RAC/M sur son port HTTPS (443 par défaut, ou le port sur lequel RAC/M est exposé). L’agent initie toujours la connexion vers RAC/M ; aucune règle entrante vers l’hôte agent n’est donc requise.

L’exception est Direct : RAC/M se connecte au serveur de connecteurs sur l’hôte et le port que vous avez configurés (par défaut 8759), vous devez donc aussi autoriser cette connexion entrante de RAC/M vers l’hôte agent. Agent ne nécessite que la règle sortante.

Créer le serveur agent dans RAC/M

L’écran du serveur ICF est un court assistant guidé. La barre de progression affiche Configuration (sous-étapes Général et, le cas échéant, Connexion), puis Déploiement, puis Vérification. Pendant Configuration, utilisez Suivant et Précédent (ou cliquez sur un nœud complété). À l’étape Vérification, Éditer rouvre Configuration depuis la première sous-étape.

1. Connectez-vous à la console de gestion RAC/M Identity avec un compte habilité à gérer les serveurs ICF.
2. Ouvrez CONFIGURATION → Serveurs ICF.

3. Cliquez sur + pour créer un nouveau serveur ICF.
4. À la sous-étape Général de Configuration, saisissez un Nom pour ce serveur (par exemple, l’environnement ou l’application desservie) et choisissez un Type de connexion. Agent est présélectionné pour un nouveau serveur ; les cartes sont ordonnées Agent, Direct, Désuet.

5. Poursuivez selon le type de connexion choisi :
   • Agent : la sous-étape Connexion est ignorée (RAC/M gère l’hôte et le port) — après Général, enregistrez directement.
   • Direct : à la sous-étape Connexion, saisissez l’Adresse et le Port (8759 par défaut) où le serveur ICF écoute pour que RAC/M s’y connecte. La note Pourquoi c’est nécessaire explique que ces valeurs sont réutilisées pour générer les étapes de déploiement (publication du port Docker/Podman et port du Service Kubernetes). Ouvrez ce port dans le pare-feu de l’hôte (et tout équilibreur de charge, groupe de sécurité ou Service Kubernetes) pour permettre une connexion entrante depuis RAC/M.

6. Cliquez sur Enregistrer.

Après l’enregistrement, l’assistant s’ouvre à l’étape Déploiement. En mode Direct, le docker run généré inclut -p portHôte:8759 pour publier ConnId sur le port configuré, et l’exemple de chart Kubernetes inclut un Service sur ce port.

Récupérer les étapes de déploiement et le secret bearer

1. Après un enregistrement réussi, l’assistant s’ouvre à l’étape Déploiement avec Déployer le conteneur agent.
2. Choisissez où l’agent s’exécute à l’aide du sélecteur Cible de déploiement (Docker, Podman ou Kubernetes) ; les trois étapes ci-dessous sont régénérées pour la cible choisie.
3. Exécutez les trois étapes affichées dans l’ordre.

Docker et Podman

Sur un hôte Linux, exécutez les trois étapes dans l’ordre.

Étape 1 — Créer le fichier .env sur l’hôte

1. Copiez le contenu affiché sous Contenu de racm-icf-agent.env et enregistrez-le sur l’hôte Linux dans un fichier racm-icf-agent.env, dans le répertoire où vous exécuterez les commandes Docker.
2. Exécutez la commande Restreindre l’accès au fichier (chmod 600 racm-icf-agent.env) sur l’hôte immédiatement après la création du fichier.

Le fichier contient RACM_HOST, au besoin RACM_PORT et RACM_SCHEME, et RACM_AGENT_ICF_SERVER_BEARER_TOKEN. Considérez-le comme hautement confidentiel : le secret bearer authentifie votre agent auprès de RAC/M (synchro des artefacts, enregistrement, tunnel le cas échéant et registre d’images intégré). Conservez-le dans un coffre-fort de secrets ou une procédure sécurisée, pas dans un courriel ou une messagerie instantanée.

Étape 2 — Connexion au registre

Exécutez la commande de l’Étape 2 — Connexion au registre sur l’hôte. Elle authentifie Docker auprès du registre de conteneurs intégré de RAC/M à l’aide du jeton bearer du fichier racm-icf-agent.env. La commande lit le jeton dans ce fichier et le transmet à Docker via l’entrée standard, pour éviter de l’exposer dans l’historique du shell ou la ligne de commande. Utilisez le nom d’utilisateur bearer ; le mot de passe est le secret bearer.

RAC/M sert l’image racm-icf-server-agent depuis ce registre. La référence d’image à l’étape 3 utilise le nom d’hôte RAC/M (et le port, lorsqu’il n’est pas le port HTTPS ou HTTP par défaut).

Étape 3 — Démarrer le conteneur agent

Exécutez la commande de l’Étape 3 — Démarrer le conteneur agent. Elle démarre l’agent avec --env-file ./racm-icf-agent.env et récupère l’image depuis le registre RAC/M (--pull always). Pour Direct, la commande publie aussi ConnId avec -p portHôte:8759 (port conteneur 8759, TLS) ; pour Agent, ce mapping de port est omis.

Kubernetes

Sélectionnez Kubernetes dans le sélecteur Cible de déploiement. La console affiche alors un exemple de chart Helm prérempli avec les paramètres de ce serveur. Traitez-le comme un point de départ à adapter à votre cluster (ou à une plateforme compatible telle qu’OpenShift), et non comme un chart supporté.

Le jeton bearer n’est pas écrit dans le chart. Vous le conservez dans un fichier local que Helm lit à l’installation avec --set-file, ce qui permet de versionner les fichiers du chart sans y inclure le secret.

Étape 1 — Créer le fichier du jeton bearer

1. Copiez le contenu affiché sous Contenu de racm-icf-agent-bearer-token et enregistrez-le dans le répertoire où vous exécuterez la commande Helm. Le fichier ne contient que le jeton bearer.
2. Exécutez la commande Restreindre l’accès au fichier (chmod 600 racm-icf-agent-bearer-token) immédiatement après la création du fichier.

Ne versionnez pas ce fichier dans le dépôt où vous conservez le chart. La même règle d’affichage unique que pour le fichier .env s’applique : le secret complet peut ne plus rester visible après actualisation ou navigation.

Si le secret est déjà masqué, la page ne peut pas régénérer racm-icf-agent-bearer-token. Si vous avez déjà installé le chart, passez à l’étape 3 ; le secret déjà présent dans le cluster demeure valide. Si vous ne l’avez pas copié, utilisez Révoquer et régénérer le jeton pour afficher un nouveau fichier.

Étape 2 — Créer l’exemple de chart

Créez le répertoire racm-icf-server-agent à côté du fichier du jeton. Dans ce répertoire, enregistrez chaque fichier affiché par la console au chemin indiqué :

Fichier	Rôle
Chart.yaml	Métadonnées du chart.
values.yaml	Référence d’image (la même que pour Docker/Podman), hôte, schéma et port RAC/M, nom du secret de tirage d’image, et (en mode Direct) le port du Service. Le jeton bearer en est volontairement absent afin de pouvoir versionner ce fichier.
templates/secret.yaml	Place le jeton bearer dans un Secret Kubernetes monté en fichier dans le pod. Le conteneur le lit via RACM_AGENT_ICF_SERVER_BEARER_TOKEN_FILE ; le jeton n’est jamais passé en variable d’environnement en clair.
templates/registry-secret.yaml	Construit le secret de tirage d’image à partir de ce même jeton (nom d’utilisateur du registre bearer), afin qu’aucune commande distincte n’ait à transporter le secret comme argument de processus.
templates/deployment.yaml	Un seul réplica, le secret monté en lecture seule, un contexte de sécurité non root, et des sondes de démarrage, de vivacité et de disponibilité alignées sur la vérification de santé de l’image.
templates/service.yaml	Mode Direct seulement : expose le port ConnId pour que RAC/M se connecte en entrée. L’exemple utilise ClusterIP ; changez le type de Service (ou ajoutez une route) lorsque RAC/M joint l’agent depuis l’extérieur du cluster.

En mode Agent, aucun Service n’est généré : l’agent établit une connexion sortante.

La sonde de démarrage prévoit un premier démarrage long (le port ConnId ne s’ouvre qu’après la première synchro des artefacts). Augmentez connId.startupFailureThreshold dans values.yaml si le bundle est volumineux ou si le lien vers RAC/M est lent.

Étape 3 — Installer le chart

Exécutez la commande de l’Étape 3 — Installer le chart depuis le répertoire qui contient à la fois le fichier du jeton et le répertoire du chart :

helm upgrade --install racm-icf-agent ./racm-icf-server-agent --set-file bearerToken.value=./racm-icf-agent-bearer-token

La commande lit le jeton bearer dans le fichier créé à l’étape 1, puis installe ou met à jour la version déployée. Réexécutez-la après une régénération du jeton.

Après avoir quitté la page

La console avertit que le secret bearer complet (racm-icf-agent.env ou racm-icf-agent-bearer-token) peut ne plus rester visible après actualisation ou navigation. Copiez et sécurisez le contenu du fichier avant de quitter. Si le secret est masqué mais que vous avez déjà le fichier sur l’hôte (ou le chart déjà installé), passez aux étapes suivantes. Si vous ne l’avez pas copié, utilisez Révoquer et régénérer le jeton pour afficher un nouveau fichier.

Après régénération du jeton, redéployez avec le nouveau secret pour que l’agent le prenne en compte ; l’ancien secret cesse immédiatement de fonctionner. Sur un hôte Docker/Podman, redémarrez les conteneurs agent avec le nouveau fichier .env et les nouvelles commandes. Pour Kubernetes, enregistrez le nouveau fichier du jeton et réexécutez la commande d’installation Helm.

Une fois que l’agent s’est connecté au moins une fois, la page affiche aussi Dernière connexion au système (ou Jamais jusqu’au premier contact réussi). Utilisez cet horodatage avec Test à l’étape Vérification pour confirmer que l’agent est joignable.

Démarrer l’agent dans votre environnement

1. Préparez l’endroit où ConnId doit s’exécuter : un hôte Linux avec Docker ou Podman, ou un cluster Kubernetes avec Helm.

2. Exécutez les trois étapes de la console pour la Cible de déploiement choisie. Vous pouvez toujours transposer les commandes Docker ou Podman en Docker Compose ou dans votre modèle habituel, en conservant les mêmes variables d’environnement (ou RACM_AGENT_ICF_SERVER_BEARER_TOKEN_FILE pour un fichier de jeton monté), la même authentification au registre et (en mode direct) le port ConnId publié.

3. Laissez le conteneur joindre RAC/M en HTTPS pour la synchro et l’enregistrement. Au démarrage, l’image attend que l’URL HTTP des fichiers agent réponde (sauf si vous désactivez cette attente), exécute la synchro des artefacts, puis l’enregistrement. En mode tunnel, elle démarre ensuite le client de tunnel ; en mode direct, elle omet le tunnel et exécute ConnId pour que RAC/M se connecte en entrée.

4. En mode direct, vérifiez que le pare-feu de l’hôte (et tout équilibreur de charge ou Service Kubernetes) permet à RAC/M d’atteindre le port ConnId publié. En mode tunnel, vérifiez uniquement la connectivité sortante vers RAC/M.

5. Surveillez au besoin les journaux du conteneur pour confirmer la synchro, l’enregistrement et (mode tunnel) le démarrage du tunnel. Les journaux d’enregistrement indiquent le mode de connexion actif.

Variables d’environnement de l’image agent

Le fichier racm-icf-agent.env fourni par RAC/M contient les paramètres requis pour Docker et Podman. L’exemple de chart Kubernetes définit les mêmes valeurs de connexion RAC/M dans values.yaml et fournit le jeton bearer par un fichier monté. Les tableaux ci-dessous listent toutes les variables d’environnement reconnues par l’image racm-icf-server-agent si vous devez en ajouter ou en modifier (par exemple, sous Docker Compose ou dans un chart que vous adaptez).

Connexion RAC/M

Le conteneur ne démarre pas si RACM_HOST est absent, ou si aucune des deux entrées de jeton bearer ci-dessous ne se résout en une valeur non vide :

Variable	Description
RACM_HOST	Nom d’hôte RAC/M, ou IPv6 entre crochets. Ne pas inclure le schéma ni le port.
RACM_AGENT_ICF_SERVER_BEARER_TOKEN	Secret bearer pour l’accès aux fichiers agent, l’authentification au registre et l’enregistrement ; à protéger. Utilisé par les commandes Docker et Podman générées. Requis sauf si RACM_AGENT_ICF_SERVER_BEARER_TOKEN_FILE est défini. Prend le dessus lorsque les deux entrées sont définies (un avertissement est journalisé et le fichier n’est pas lu).
RACM_AGENT_ICF_SERVER_BEARER_TOKEN_FILE	Chemin vers un fichier contenant uniquement le jeton (forme Kubernetes : monter un Secret en lecture seule — l’exemple de chart définit cette variable vers le chemin du Secret monté, au lieu de placer le jeton dans RACM_AGENT_ICF_SERVER_BEARER_TOKEN). Les espaces environnants et le saut de ligne final sont retirés ; le jeton doit tenir sur une seule ligne sans caractères de contrôle (un saut de ligne intégré injecterait un en-tête HTTP supplémentaire). La variable ci-dessus a préséance lorsque les deux entrées sont définies. Un fichier absent, illisible ou vide fait échouer le démarrage en nommant le chemin, sans divulguer le contenu. Requis sauf si RACM_AGENT_ICF_SERVER_BEARER_TOKEN est défini.

Facultatif :

Variable	Défaut	Description
RACM_SCHEME	https	Schéma HTTP de RAC/M (http ou https). Sert à construire les URL HTTP(S) des agents RAC/M.
RACM_PORT	(défaut du schéma)	Port HTTP(S) de RAC/M. S’il est absent ou vide : 443 lorsque RACM_SCHEME vaut https (valeur par défaut) et 80 lorsque http. S’il est défini, chiffres décimaux uniquement (1–65535).

Disponibilité HTTP avant la synchro des fichiers agent (facultatif)

Avant la synchro des artefacts, l’image interroge l’URL HTTP des fichiers agent de RAC/M (attente bornée). Ajustez ce comportement avec :

Variable	Défaut	Description
RACM_SERVER_WAIT_SECS	120	Durée maximale d’attente de disponibilité HTTP ; 0 désactive l’attente.
RACM_SERVER_PROGRESS_SECS	15	Ligne de progression toutes les N secondes pendant l’attente ; 0 désactive.
RACM_SERVER_READY_COUNT	3	Après la première réussite du test, nombre de passes successives (1 s d’intervalle) avant la synchro ; 1 pour le comportement « première réussite ».
RACM_SERVER_SETTLE_SECS	0	Pause supplémentaire (secondes) après la disponibilité et avant la synchro.
RACM_SERVER_PROBE_DEBUG	(non défini)	Si 1, true ou yes (insensible à la casse), les échecs de test utilisent curl -S pour afficher le détail des erreurs curl sur stderr.

Synchronisation périodique et redémarrage de ConnId (facultatif)

Variable	Défaut	Description
RACM_ICF_SYNC_INTERVAL_SECS	300	Secondes entre deux tentatives de synchro incrémentielle.
RACM_ICF_ICF_SIGTERM_WAIT_SECS	60	Après SIGTERM vers ConnId, secondes d’attente avant SIGKILL.

Client de tunnel (facultatif, mode tunnel uniquement)

Ces variables s’appliquent uniquement lorsque l’enregistrement renvoie connectionMode: TUNNEL. En mode direct, l’agent ne démarre pas le client de tunnel ; elles n’ont alors aucun effet.

Variable	Défaut	Description
TUNNEL_CONTROL_URL	(depuis l’enregistrement)	Remplacement seulement. URL WebSocket de contrôle complète (le chemin doit être /agent/icf-server/tunnel). Remplace l’URL d’enregistrement lorsqu’elle est définie. À omettre en déploiement normal ; RAC/M n’émet pas cette variable dans les étapes de déploiement.
TUNNEL_EXTRA_ARGS	(non défini)	Arguments supplémentaires ajoutés à la commande du client de tunnel.
TUNNEL_SERVER_CONNECT_WAIT_SECS	120	Attente du port TCP du serveur de tunnel (déduit de l’URL de contrôle) avant le démarrage du client ; 0 désactive.
TUNNEL_WAIT_PROGRESS_SECS	15	Intervalle des lignes de progression pendant l’attente ; 0 désactive.
TUNNEL_LOG_LEVEL	INFO	Niveau de journalisation du client de tunnel ; le détail est écrit dans tunnel.log sous ${ICF_AGENT_ROOT}/logs/ (par défaut /opt/icf-agent/logs/).

Chemins d’installation (facultatif)

Variable	Défaut (image)	Description
ICF_AGENT_ROOT	/opt/icf-agent	Racine d’installation de l’agent.
ICF_ROOT	/opt/icf-agent/icf-server	Répertoire du bundle ConnId.

Utiliser des connecteurs avec ce serveur

Configurez vos connecteurs ICF pour utiliser cette instance de serveur ICF comme tout autre serveur : CONFIGURATION → Connecteurs ICF, ouvrez le connecteur et sélectionnez ce serveur sous Serveur ICF. Voir Connecteurs pour le flux général.