Agent Docker (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 Docker racm-icf-server-agent. 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 Historique 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	RAC/M se connecte en entrée vers ConnId sur l’hôte et le port configurés pour le serveur ICF. 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 ne peut pas accepter de connexions entrantes depuis RAC/M. Utilisez Direct lorsque RAC/M peut joindre l’hôte agent 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. Utilisez Suivant et Précédent pour naviguer entre les étapes, ou cliquez sur un nœud complété.

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 : Historique, Direct ou Agent.

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ù RAC/M joindra ConnId sur l’hôte agent. La note Pourquoi c’est nécessaire explique que ces valeurs sont réutilisées pour générer racm-icf-agent.env et les commandes de déploiement (y compris la publication du port). Ouvrez ce port dans le pare-feu de l’hôte (et tout équilibreur de charge ou groupe de sécurité) 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é.

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 l’agent Docker.
2. Choisissez votre moteur de conteneur à l’aide du sélecteur Environnement d’exécution (Docker ou Podman) ; les commandes des étapes 2 et 3 sont régénérées pour le moteur choisi.
3. Sur un hôte Linux, exécutez les trois étapes affichées 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.

Après avoir quitté la page

La console avertit que le secret bearer complet dans racm-icf-agent.env 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à racm-icf-agent.env sur l’hôte, passez aux étapes 2 et 3. 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émarrez vos conteneurs agent sur l’hôte avec le nouveau fichier .env et les nouvelles commandes ; l’ancien secret cesse immédiatement de fonctionner.

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. Sur l’hôte Linux ou le cluster où ConnId doit s’exécuter, installez Docker (ou un environnement d’exécution de conteneurs compatible).

2. Exécutez les trois étapes de la console dans l’ordre (créer racm-icf-agent.env, connexion au registre, docker run), ou transposez-les en Docker Compose, Kubernetes ou votre modèle de déploiement habituel en conservant les mêmes variables d’environnement, 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. 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 Kubernetes).

Connexion RAC/M

Le conteneur ne démarre pas sans ces variables :

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.

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.