Déploiement du client de relais en tant que conteneur

Exécutez le client de relais sous forme d'image de conteneur pour établir des tunnels sortants sécurisés vers Test Cloud à partir d'environnements conteneurisés. Avant de commencer, configurez un groupe de relais et préparez la chaîne de configuration client à partir de l’interface utilisateur du relais.

Prérequis

• Runtime du conteneur: Podman, Docker ou un cluster Kubernetes.
• Image de conteneur du client de relais: registry.uipath.com/relay-client:<tag>. Remplacez <tag> par une version Relay à partir de la page de téléchargements du UiPath Customer Portal . La version minimale prise en charge est 26.4.1.
• Un fichier de configuration encodé en base64 généré à partir de l'interface utilisateur du relais.
• Acceptation du contrat de licence: définissez LICENSE_AGREEMENT=accept comme variable d'environnement ou ajoutez --accept-license-agreement à la commande de démarrage.
• (Facultatif) Un certificat CA personnalisé si votre organisation utilise un PKI d'entreprise.

Pour connaître la configuration matérielle requise et les prérequis réseau spécifiques à la version, consultez la section Déployer le client de relais.

Étape 1: Obtenir la configuration

1. Ouvrez le tableau de bord de l'interface utilisateur du relais.
2. Créez ou copiez votre configuration de relais.
3. Enregistrez la chaîne de configuration encodée en Base64 fournie par l'interface utilisateur.

Étape 2: configurer les variables d'environnement

Certificat CA personnalisé

Si votre organisation utilise une autorité de certification d'entreprise ou auto-signée, définissez les variables suivantes avant de lancer le conteneur:

Variable	Objectif	Requis
RELAY_CUSTOM_CA_PATH	Chemin d'accès au certificat CA personnalisé	Non (No)
RELAY_CA_BUNDLE_PATH	Chemin où le bundle d’autorité de certification fusionné est écrit	Oui, si vous utilisez une autorité de certification personnalisée

Le client de relais fusionne l'autorité de certification personnalisée avec le bundle de certificats système avant d'établir des connexions TLS. Les deux variables doivent être définies ensemble.

Proxy

Pour acheminer le trafic sortant via un proxy:

Variable	Objectif	Requis
HTTP_PROXY et HTTPS_PROXY	URL du proxy	Non (No)
NO_PROXY	Noms d'hôte, domaines ou adresses IP séparés par des virgules qui contournent le proxy	Non (No)

Étape 3: Déployer

Podman

Pour la haute disponibilité, exécutez deux conteneurs sur des nœuds distincts avec des noms distincts. Remplacez <RELAY_ID> par l'ID réel de l'interface utilisateur du relais, par exemple. Exécutez relay1-<RELAY_ID> sur l'hôte1 et relay2-<RELAY_ID> sur l'hôte2.

Démarrage rapide:

# Create a config file with the base64-encoded content from the Relay UI
echo "YOUR_BASE64_CONFIG_HERE" > /tmp/relay_config

# Run the container
podman run -it --name relay1-<RELAY_ID> --hostname relay1-<RELAY_ID> --rm \
  --read-only --read-only-tmpfs \
  -v /tmp/relay_config:/relay.config.b64enc:z \
  -e LICENSE_AGREEMENT=accept \
  registry.uipath.com/relay-client:<tag> \
  start --config-file /relay.config.b64enc --accept-license-agreement

Avec un certificat CA personnalisé:

podman run -it --name relay1-<RELAY_ID> --hostname relay1-<RELAY_ID> --rm \
  --read-only --read-only-tmpfs \
  -v /tmp/relay_config:/relay.config.b64enc:z \
  -v /tls/custom-ca.crt:/custom-ca.crt:z \
  -v /tmp/writable:/writable:z \
  -e RELAY_CUSTOM_CA_PATH=/custom-ca.crt \
  -e RELAY_CA_BUNDLE_PATH=/writable/merged-ca.crt \
  registry.uipath.com/relay-client:<tag> \
  start --config-file /relay.config.b64enc --accept-license-agreement

Options de la commande de démarrage:

Option	Description	Exemple
--config	Chaîne de configuration base64 intégrée	--config "base64string..."
--config-file	Chemin d’accès au fichier de configuration	--config-file /relay.config.b64enc
--log-level	Détail de la journalisation: trace, debug, info, warn, ou error	--log-level debug
--heartbeat-interval	Intervalle des pulsations en secondes (3e minimum: 10)	--heartbeat-interval 10
--reconnect-interval	Intervalle de reconnexion en secondes (minimum: 1 800)	--reconnect-interval 1800
--health-addr	Adresse de liaison pour le point de terminaison /healthz . La valeur par défaut est 0.0.0.0:9090; Si vous indiquez une valeur vide pour la désactiver,	--health-addr=0.0.0.0:9090

Kubernetes

Créer des clés secrètes:

# Configuration secret
kubectl create secret generic relay-config \
  --from-file=relay.conf=/tmp/relay_config

# Custom CA certificate secret (optional)
kubectl create secret generic custom-ca \
  --from-file=custom-ca.crt=./custom-ca.crt

# Headless service for the StatefulSet
kubectl create service clusterip relay-client-<RELAY_ID> --clusterip="None"

Déployez un ensemble d'états:

Utilisez un Ensemble d'états lorsque des restrictions de nom d'hôte sont appliquées. Les ensembles d'états fournissent des noms d'hôtes stables et prévisibles (relay-client-0, relay-client-1, etc.), que le service de relais utilise pour identifier et valider les clients.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: relay-client-<RELAY_ID>
spec:
  serviceName: relay-client-<RELAY_ID>
  replicas: 2
  selector:
    matchLabels:
      app: relay-client-<RELAY_ID>
  template:
    metadata:
      labels:
        app: relay-client-<RELAY_ID>
    spec:
      affinity:
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
          - labelSelector:
              matchExpressions:
              - key: app
                operator: In
                values:
                - relay-client-<RELAY_ID>
            topologyKey: "kubernetes.io/hostname"
      containers:
      - name: relay
        image: registry.uipath.com/relay-client:<tag>
        args:
        - start
        - --config-file=/config/relay.conf
        - --accept-license-agreement
        - --log-level=info
        - --heartbeat-interval=30
        env:
        - name: RELAY_CUSTOM_CA_PATH
          value: "/tls/custom-ca.crt"
        - name: RELAY_CA_BUNDLE_PATH
          value: "/writable/merged-ca.crt"
        imagePullPolicy: IfNotPresent
        securityContext:
          allowPrivilegeEscalation: false
          capabilities:
            drop:
            - ALL
          privileged: false
          readOnlyRootFilesystem: true
          runAsGroup: 1001
          runAsNonRoot: true
          runAsUser: 1001
        readinessProbe:
          httpGet:
            path: /healthz
            port: 9090
          initialDelaySeconds: 5
          timeoutSeconds: 1
          periodSeconds: 3
          successThreshold: 1
          failureThreshold: 2
        resources:
          requests:
            cpu: 50m
            memory: 100Mi
        volumeMounts:
        - name: relay-config
          mountPath: /config/relay.conf
          subPath: relay.conf
          readOnly: true
        - mountPath: /writable
          name: writable
        - name: custom-ca
          mountPath: /tls/custom-ca.crt
          subPath: custom-ca.crt
          readOnly: true
      volumes:
      - name: relay-config
        secret:
          secretName: relay-config
      - name: writable
        emptyDir: {}
      - name: custom-ca
        secret:
          secretName: custom-ca
      restartPolicy: Always
      terminationGracePeriodSeconds: 30

Vérifiez le déploiement:

kubectl get statefulset relay-client-<RELAY_ID>

Opérations

Configuration details

Le fichier de configuration doit contenir la chaîne JSON encodée en base64 générée par l'interface utilisateur du relais. Au démarrage, le client de relais lit la configuration, la décode, la valide et se connecte au point de terminaison du service de relais spécifié.

• Première exécution: la configuration est stockée chiffrée dans le répertoire de données.
• Exécutions suivantes: la configuration chiffrée est automatiquement déchiffrée et utilisée.
• Modifications du fichier de configuration: nécessitent un redémarrage du conteneur pour prendre effet.

Intervalle des pulsations

La pulsation maintient les connexions TCP inactives actives. Réduisez l'intervalle si votre pare-feu, votre proxy ou la traduction d'adresses réseau abandonne les connexions inactives avant 30 secondes:

--heartbeat-interval=30    # Default
--heartbeat-interval=10    # For aggressive firewall or NAT environments

Intervalle de reconnexion

La reconnexion proactive rétablit la connexion selon un calendrier fixe. Utilisez cette option dans les environnements où un proxy ou un équilibreur de charge a un délai d'expiration de connexion inactive:

--reconnect-interval=0     # Disabled (default)
--reconnect-interval=1800  # Reconnect every 30 minutes (minimum)

Point de terminaison de santé

Remarque :

L'option --health-addr est disponible avec le client de relais 26.4.2 et les versions ultérieures.

L'image de conteneur active un point de terminaison HTTP /healthz par défaut sur 0.0.0.0:9090. Utilisez --health-addr=<address> pour modifier l'adresse de liaison ou --health-addr= pour désactiver le point de terminaison. La sonde de disponibilité Kubernetes du manifeste utilise ce point de terminaison.

Accéder aux journaux

# Podman
podman logs -f relay1

# Kubernetes (current run)
kubectl logs -f relay-client-0

# Kubernetes (previous run, if the container restarted)
kubectl logs relay-client-0 --previous

La rétention du journal de conteneur est contrôlée par votre runtime de conteneur ou par votre stratégie de journalisation de cluster Kubernetes, et non par le client de relais.

Sécurité

Appliquez les paramètres de sécurité suivants dans votre manifeste de conteneur:

• readOnlyRootFilesystem: true — empêche la modification du système de fichiers du conteneur.
• runAsNonRoot: true — exécute le processus en tant qu'utilisateur non-administrateur.
• allowPrivilegeEscalation: false — empêche l'escalade des privilèges.
• capabilities.drop: [ALL] — supprime toutes les fonctionnalités Linux.
• privileged: false — désactive le mode privilégié.

Stockez la configuration du Relay dans les clés secrètes Kubernetes et utilisez le contrôle d’accès basé sur les rôles pour restreindre l’accès aux secrets. N'intégrez pas la configuration base64 dans l'image du conteneur et ne la transmettez pas en tant que variable d'environnement simple.

Résolution des problèmes

Symptôme	Origine	Résolution
license agreement not accepted au démarrage	Indicateur de licence ou variable non défini	Ajoutez --accept-license-agreement à la commande de démarrage, ou définissez LICENSE_AGREEMENT=accept
Fichier de configuration introuvable	Chemin de montage de volume ou clé secrète incorrecte	Exécutez kubectl describe secret relay-config et kubectl describe pod <pod-name> pour vérifier les montages
Impossible de se connecter au service de relais	Problème de réseau ou de pare-feu	Vérifiez les journaux de pod avec kubectl logs <pod-name> et vérifiez les destinations sortantes requises dans le déploiement du client de relais
Échec de la fusion de l’autorité de certification personnalisée	Variables d'environnement CA non définies les deux	Définir RELAY_CUSTOM_CA_PATH et RELAY_CA_BUNDLE_PATH ensemble
Nom d'hôte non reconnu par le service de Relay	Le nom du pod est aléatoire (pod autonome, non Ensembles d'états)	Utiliser un Ensemble d'états au lieu d'un Pod autonome
erreurs de certificat x509	Certificat CA non valide ou inaccessible	Vérifiez le format du certificat avec openssl x509 -in custom-ca.crt -text -noout et vérifiez les autorisations du fichier