Implementar el cliente de Relay como contenedor

Implemente el cliente de UiPath Relay como una imagen de contenedor utilizando Podman, Docker o Kubernetes para establecer túneles de salida seguros en entornos en contenedores.

Ejecuta el cliente de Relay como imagen de contenedor para establecer túneles salientes seguros a Test Cloud desde entornos en contenedores. Antes de comenzar, configura un grupo de Relay y ten lista la string de configuración del Cliente desde la IU de Relay.

Requisitos previos

• Runtime de contenedor: Podman, Docker o un clúster de Kubernetes.
• Imagen de contenedor de cliente de Relay: registry.uipath.com/relay-client:<tag>. Sustituye <tag> por una versión de Relay de la página de descargas del Customer Portal de UiPath . La versión mínima compatible es 26.4.1, o 26.4.3 para conexiones basadas en TCP como SAP BAPI.
• Un archivo de configuración codificado en base64 generado a partir de la IU de Relay.
• Aceptación del acuerdo de licencia: establece LICENSE_AGREEMENT=accept como variable de entorno o anexa --accept-license-agreement al comando de inicio.
• (Opcional) Un certificado de CA personalizado si tu organización utiliza PKI de empresa.

Para conocer los requisitos de hardware y los requisitos previos de red específicos de la versión, consulta Implementación del cliente de Relay.

Importante:

Para las conexiones basadas en TCP compatibles, como SAP BAPI, implementas el cliente de Relay junto con un segundo contenedor, el ejecutor local. Si lo necesitas, omite el paso 3 y sigue SAP BAPI y otras conexiones basadas en TCP . Esa sección cubre Docker y Podman.

Paso 1: obtener la configuración

1. Abra el panel de IU de Relay.
2. Cree o copie su configuración de Relay.
3. Crea un directorio en el host para el archivo de configuración. Cualquier directorio funciona; esta página utiliza /opt/uipath/relay/config como ejemplo. En Windows, utiliza una ruta de Windows como C:\uipath\relay\config.
4. Guarda la cadena de configuración codificada en base64 desde la IU allí como relay.config.b64enc. Los comandos de implementación montan este directorio en el contenedor como /relay-config; reemplaza la ruta de ejemplo por la tuya.

Paso 2: configura las variables de entorno

Pasa estas variables como marcadores -e con Podman o Docker, o como entradas env: en el manifiesto de Kubernetes, en el paso 3.

Certificado de CA personalizado

Si tu organización utiliza una CA corporativa o autofirmada, establece las siguientes variables juntas antes de iniciar el contenedor:

Variable	Propósito	Obligatorio
RELAY_CUSTOM_CA_PATH	Ruta al certificado de CA personalizado	Sí, si se utiliza una CA personalizada
RELAY_CA_BUNDLE_PATH	Ruta donde se escribe el paquete de CA fusionado	Sí, si se utiliza una CA personalizada

El cliente de Relay fusiona la CA personalizada con el paquete de certificados del sistema antes de establecer cualquier conexión TLS.

Proxy

Para enrutar el tráfico saliente a través de un proxy:

Variable	Propósito	Obligatorio
HTTP_PROXY y HTTPS_PROXY	URL del proxy	No
NO_PROXY	Nombres de host, dominios o direcciones IP separados por comas que omiten el proxy	No

Paso 3: Implementar

Reemplace <RELAY_ID> por el ID real de la IU de Relay. Para una alta disponibilidad con Docker o Podman, ejecuta dos contenedores en nodos independientes con nombres distintos, por ejemplo, relay1-<RELAY_ID> en el host1 y relay2-<RELAY_ID> en el host2. En Kubernetes, utiliza dos réplicas con antiafinidad de pod, como en el manifiesto a continuación. Un inicio correcto registra All prerequisite checks passed.

Los siguientes comandos de Podman y Docker se ejecutan en primer plano con -it --rm, para que puedas ver el primer inicio y el contenedor se elimina cuando lo detienes. Para una implementación de larga duración, reemplaza -it --rm por -d.

Podman

Inicio rápido:

podman run -it --name relay1-<RELAY_ID> --hostname relay1-<RELAY_ID> --rm \
  --read-only --read-only-tmpfs \
  -v /opt/uipath/relay/config:/relay-config:ro,z \
  registry.uipath.com/relay-client:<tag> \
  start --config-file /relay-config/relay.config.b64enc --accept-license-agreement

Con un certificado de CA personalizado:

podman run -it --name relay1-<RELAY_ID> --hostname relay1-<RELAY_ID> --rm \
  --read-only --read-only-tmpfs \
  -v /opt/uipath/relay/config:/relay-config:ro,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/relay.config.b64enc --accept-license-agreement

Docker

Inicio rápido:

docker run -it --name relay1-<RELAY_ID> --hostname relay1-<RELAY_ID> --rm \
  --read-only --tmpfs /tmp \
  -v /opt/uipath/relay/config:/relay-config:ro \
  registry.uipath.com/relay-client:<tag> \
  start --config-file /relay-config/relay.config.b64enc --accept-license-agreement

Con un certificado de CA personalizado:

docker run -it --name relay1-<RELAY_ID> --hostname relay1-<RELAY_ID> --rm \
  --read-only --tmpfs /tmp \
  -v /opt/uipath/relay/config:/relay-config:ro \
  -v /tls/custom-ca.crt:/custom-ca.crt:ro \
  -v /tmp/writable:/writable \
  -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/relay.config.b64enc --accept-license-agreement

Kubernetes

Crear secretos:

# Configuration secret
kubectl create secret generic relay-config \
  --from-file=relay.conf=/opt/uipath/relay/config/relay.config.b64enc

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

Implementar un StatefulSet:

Usa un StatefulSet cuando se aplican restricciones de nombre de host. Los StatefulSets proporcionan nombres de host estables y predecibles (relay-client-<RELAY_ID>-0, relay-client-<RELAY_ID>-1, etc.), que el servicio de Relay utiliza para identificar y validar clientes.

El manifiesto monta el secreto custom-ca y establece las dos variables RELAY_*. Si no utilizas una CA personalizada, elimina esas dos variables, el montaje del volumen custom-ca y el volumen custom-ca. La sonda de preparación utiliza el punto final de estado, que requiere el cliente de Relay 26.4.2 o posterior.

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

Verifica la implementación:

kubectl get statefulset relay-client-<RELAY_ID>

Opciones de comando de inicio

Estos se aplican a cada runtime.

Opción	Descripción	Ejemplo
--config	Cadena de configuración base64 en línea	--config "base64string..."
--config-file	Ruta al archivo de configuración	--config-file /relay-config/relay.config.b64enc
--log-level	Verbosidad del registro: trace, debug, info, warn o error	--log-level debug
--heartbeat-interval	Intervalo de latido en segundos (mínimo: 10)	--heartbeat-interval 10
--reconnect-interval	Intervalo de reconexión en segundos (mínimo: 1800)	--reconnect-interval 1800
--health-addr	Dirección de enlace para el punto final /healthz. El valor predeterminado es 0.0.0.0:9090; utiliza un valor vacío para deshabilitarlo	--health-addr=0.0.0.0:9090
--enable-onprem-executor	Se conecta al contenedor del ejecutor local en el puerto predeterminado 18080. Consulta SAP BAPI y otras conexiones basadas en TCP	--enable-onprem-executor
--onprem-executor-listen-port	Se conecta al contenedor del ejecutor local en este puerto, que debe coincidir con el SERVER_PORT del contenedor. Cualquiera de los marcadores habilita el ejecutor	--onprem-executor-listen-port 18080

SAP BAPI y otras conexiones basadas en TCP

Importante:

Requiere el cliente de Relay 26.4.3 o posterior. Esta sección cubre Docker y Podman.

Para las conexiones basadas en TCP compatibles, como SAP BAPI, ejecutas dos contenedores en el mismo host:

• Contenedor de cliente de Relay: abre la conexión saliente segura a UiPath.
• Contenedor del ejecutor local: se conecta a tu sistema local y gestiona la conexión basada en TCP.

El contenedor del ejecutor comparte la red del cliente de Relay, por lo que el cliente de Relay llega al ejecutor el localhost.

Requisitos previos

• Imagen del contenedor del ejecutor local: registry.uipath.com/relay-onprem-executor:<tag>. Utilice el mismo <tag> que su imagen de cliente de Relay. La versión mínima compatible es 26.4.3.
• Las bibliotecas de SAP JCo 3 sapjco3.jar, sapidoc3.jar y libsapjco3.so. Descárguelos del Portal de soporte de SAP, que requiere una cuenta de SAP; UiPath no los envía.
  • sapjco3.jar y libsapjco3.so están en el paquete SAP Java Connector 3.1 para Linux en x86_64. La imagen del ejecutor es linux/amd64, por lo que no se carga un paquete para cualquier otra plataforma.
  • sapidoc3.jar está en el paquete independiente SAP Java IDoc Class Library 3.1 .
• El host de Relay puede resolver y alcanzar el nombre de host y el puerto del sistema SAP.

Preparar las bibliotecas de JCo

Las bibliotecas pueden residir en cualquier directorio del host. Esta página utiliza /opt/uipath/relay/executor-deps como ejemplo; lo que importa es que el comando de implementación monte tu directorio en /opt/uipath/onprem-runtime/dep-libs dentro del contenedor del ejecutor. Los comandos utilizan sudo porque /opt requiere root en Linux; omítelo para un directorio de tu propiedad.

1. Crea el directorio:

   sudo mkdir -p /opt/uipath/relay/executor-deps
   

2. Copia los tres archivos en él. Colócalos directamente en el directorio, no en subdirectorios:

   sudo cp sapjco3.jar sapidoc3.jar libsapjco3.so /opt/uipath/relay/executor-deps/
   

3. Confirma que la biblioteca nativa está creada para x86-64:

   file /opt/uipath/relay/executor-deps/libsapjco3.so
   # Expect: ELF 64-bit LSB shared object, x86-64
   

   Si la salida dice ARM aarch64 u otra arquitectura, descarga el paquete Linux en x86_64 en su lugar. En Windows, donde file no está disponible, comprueba el paquete del que extrajiste: el correcto se llama sapjco3-linuxx86_64-<version>.

Implementar ambos contenedores

Ejecuta los comandos en este orden: primero el cliente de Relay y luego el ejecutor. El ejecutor se une a la red del cliente de Relay, por lo que el cliente de Relay debe estar ejecutándose cuando se inicia el ejecutor.

ADVERTENCIA:

Si reinicias o vuelves a crear el cliente de Relay, el ejecutor pierde su red y no se recupera por sí solo. Reinicia el ejecutor después, como se describe en Reiniciar y actualizar.

Antes de ejecutar los comandos:

• Sustituye /opt/uipath/relay/config y /opt/uipath/relay/executor-deps por los directorios de host que elegiste en el paso 1 y organiza las bibliotecas de JCo. Mantén las rutas del lado del contenedor como se muestra.
• Si ya inició un cliente de Relay desde el paso 3, deténgalo y elimínelo. Los argumentos de un contenedor en ejecución no se pueden cambiar.
• Si utilizas una CA personalizada o un proxy, añade las variables del Paso 2, y para una CA personalizada los dos montajes de volumen del Paso 3, al comando de cliente de Relay. El cliente de Relay es el contenedor que se conecta a UiPath.
• No publiques el puerto del ejecutor con -p. Solo el cliente de Relay necesita llegar a él.

Habilita el ejecutor en el cliente de Relay con cualquiera de los marcadores:

Marca	Efecto
--enable-onprem-executor	Se conecta al ejecutor en el puerto predeterminado 18080
--onprem-executor-listen-port <port>	Se conecta al ejecutor en <port>. Debe coincidir con el contenedor del ejecutor SERVER_PORT

Los otros indicadores de ejecutor, --onprem-executor-java-home y --onprem-executor-dep-dir, no tienen efecto en un contenedor: la imagen del ejecutor incluye su propio tiempo de ejecución de Java y lee sus bibliotecas desde /opt/uipath/onprem-runtime/dep-libs.

Podman

# 1. Relay client. It owns the network namespace that the executor joins.
podman run -d --name relay1-<RELAY_ID> --hostname relay1-<RELAY_ID> \
  --read-only --read-only-tmpfs \
  -v /opt/uipath/relay/config:/relay-config:ro,z \
  registry.uipath.com/relay-client:<tag> \
  start --config-file /relay-config/relay.config.b64enc \
  --accept-license-agreement \
  --onprem-executor-listen-port 18080

# 2. On-prem executor. SERVER_ADDRESS=127.0.0.1 restricts it to loopback,
#    which is where the Relay client reaches it. Without it, the executor
#    image listens on all interfaces of the shared namespace.
podman run -d --name relay-executor-<RELAY_ID> \
  --network container:relay1-<RELAY_ID> \
  -e SERVER_ADDRESS=127.0.0.1 \
  -e SERVER_PORT=18080 \
  -v /opt/uipath/relay/executor-deps:/opt/uipath/onprem-runtime/dep-libs:ro,z \
  registry.uipath.com/relay-onprem-executor:<tag>

Como alternativa, crea un pod de Podman y ejecuta ambos contenedores en él con --pod. El contenedor de infraestructura del pod es propietario del espacio de nombres de la red, por lo que cualquiera de los contenedores puede reiniciarse por sí solo.

Docker

# 1. Relay client. It owns the network namespace that the executor joins.
docker run -d --name relay1-<RELAY_ID> --hostname relay1-<RELAY_ID> \
  --read-only --tmpfs /tmp \
  -v /opt/uipath/relay/config:/relay-config:ro \
  registry.uipath.com/relay-client:<tag> \
  start --config-file /relay-config/relay.config.b64enc \
  --accept-license-agreement \
  --onprem-executor-listen-port 18080

# 2. On-prem executor. SERVER_ADDRESS=127.0.0.1 restricts it to loopback,
#    which is where the Relay client reaches it. Without it, the executor
#    image listens on all interfaces of the shared namespace.
docker run -d --name relay-executor-<RELAY_ID> \
  --network container:relay1-<RELAY_ID> \
  -e SERVER_ADDRESS=127.0.0.1 \
  -e SERVER_PORT=18080 \
  -v /opt/uipath/relay/executor-deps:/opt/uipath/onprem-runtime/dep-libs:ro \
  registry.uipath.com/relay-onprem-executor:<tag>

Comprobar

Lee los registros con los comandos para tu runtime:

Tiempo de ejecución	Registros de cliente de Relay	Registros del ejecutor
Podman	podman logs relay1-<RELAY_ID>	podman logs relay-executor-<RELAY_ID>
Docker	docker logs relay1-<RELAY_ID>	docker logs relay-executor-<RELAY_ID>

1. En los registros del cliente de Relay, confirme la línea de requisitos previos On-prem executor checks: OK.
2. En los mismos registros, busca el punto final del ejecutor, llamado relay1-<RELAY_ID>-system-onprem-executor-<id>, y confirma que llega a health check success.
3. En los registros del ejecutor, confirma Started OnPremRuntimeApplication.
4. Ejecuta una llamada de prueba desde el conector que utiliza este punto final, para confirmar que la ruta completa funciona.

Nota:

Mientras el contenedor del ejecutor aún se está iniciando, el paso 2 puede mostrar un health check failed: dial tcp [::1]:18080: connect: connection refused primero. Eso es lo esperado y se borra en la siguiente comprobación, unos 10 segundos más tarde, sin reiniciar el cliente de Relay.

Para problemas, consulta primero Resolución de problemas en esta página y luego Problemas con el ejecutor local.

Reiniciar y actualizar

Puedes reiniciar o actualizar el ejecutor por sí solo. Si reinicias o vuelves a crear el cliente de Relay, reinicia o vuelve a crear también el ejecutor después: el ejecutor se ejecuta dentro de la red del cliente de Relay, y reiniciar o volver a crear el cliente de Relay reemplaza esa red, por lo que el contenedor del ejecutor existente no puede recuperarse por sí solo. Utiliza el mismo <tag> para ambas imágenes al actualizar. Para Podman, reemplaza docker por podman.

Tarea	Qué hacer
Reiniciar el ejecutor	docker restart relay-executor-<RELAY_ID>. El cliente de Relay sigue ejecutándose
Actualizar el ejecutor	docker rm -f relay-executor-<RELAY_ID>y, a continuación, vuelve a ejecutar el comando ejecutor con el nuevo <tag>
Reiniciar el cliente de Relay	docker restart relay1-<RELAY_ID>, entonces docker restart relay-executor-<RELAY_ID>
Actualizar el cliente de Relay	Elimine ambos contenedores y, a continuación, vuelva a ejecutar ambos comandos con el nuevo <tag> cliente de Relay primero. Un cliente de Relay recreado es un nuevo contenedor, por lo que el ejecutor también debe volver a crearse

Operaciones

Detalles de configuración

El archivo de configuración debe contener la cadena JSON codificada en base64 generada por la IU de Relay. Al iniciarse, el cliente de Relay lee la configuración, la decodifica, la valida y se conecta al punto final de servicio de Relay especificado.

• Primera ejecución: la configuración se almacena cifrada en el directorio de datos.
• Ejecuciones posteriores: la configuración cifrada se descifra y se utiliza automáticamente.
• Cambios en el archivo de configuración: requiere un reinicio del contenedor para que surta efecto.

Intervalo de latido

El latido mantiene activas las conexiones TCP inactivas. Reduce el intervalo si tu cortafuegos, proxy o traducción de direcciones de red (NAT) descarta las conexiones inactivas antes de los 30 segundos:

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

Intervalo de reconexión

La reconexión proactiva restablece la conexión en una programación fija. Usa esto en entornos donde un proxy o equilibrador de carga tiene un tiempo de espera de conexión inactiva:

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

Punto final de estado

Nota:

La opción --health-addr está disponible con el cliente de Relay 26.4.2 y versiones posteriores.

La imagen del contenedor habilita un punto final HTTP /healthz de forma predeterminada en 0.0.0.0:9090. Usa --health-addr=<address> para cambiar la dirección de enlace, o --health-addr= para deshabilitar el punto final. La sonda de preparación de Kubernetes en el manifiesto de ejemplo utiliza este punto final.

Acceder a los registros

# Podman
podman logs -f relay1-<RELAY_ID>

# Docker
docker logs -f relay1-<RELAY_ID>

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

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

La retención de registros del contenedor está controlada por su tiempo de ejecución del contenedor o la política de registro del clúster de Kubernetes, no por el cliente de Relay.

Seguridad

Aplica la siguiente configuración de seguridad en tu manifiesto de contenedor:

• readOnlyRootFilesystem: true: evita la modificación del sistema de archivos del contenedor.
• runAsNonRoot: true: ejecuta el proceso como usuario no root.
• allowPrivilegeEscalation: false: evita la escalada de privilegios.
• capabilities.drop: [ALL]: descarta todas las capacidades de Linux.
• privileged: false: deshabilita el modo privilegiado.

Almacena la configuración de Relay en secretos de Kubernetes y utiliza el control de acceso basado en roles (RBAC) para restringir el acceso a los secretos. No incrustes la configuración base64 en la imagen del contenedor ni la pases como una variable de entorno simple.

Solución de problemas

Síntoma	Causa	Resolución
license agreement not accepted al iniciar	Indicador de licencia o variable no establecida	Añade --accept-license-agreement al comando de inicio o establece LICENSE_AGREEMENT=accept
No se ha encontrado el archivo de configuración	Ruta de montaje del volumen o secreto incorrectos	Ejecuta kubectl describe secret relay-config y kubectl describe pod <pod-name> para verificar los montajes
No se puede conectar al servicio de Relay	Problema de red o firewall	Compruebe los registros de pod con kubectl logs <pod-name> y verifique los destinos salientes necesarios en Implementar el cliente de Relay
Error al combinar la CA personalizada	No se han establecido ambas variables de entorno de CA	Establezca RELAY_CUSTOM_CA_PATH y RELAY_CA_BUNDLE_PATH juntos
Nombre de host no reconocido por el servicio de Relay	El nombre del pod es aleatorio (Pod independiente, no StatefulSet)	Usa un StatefulSet en lugar de un Pod independiente
Errores de certificado x509	Certificado de CA no válido o inaccesible	Verifique el formato del certificado con openssl x509 -in custom-ca.crt -text -noout y compruebe los permisos de archivo
El punto final del ejecutor nunca alcanza health check success	El contenedor del ejecutor no comparte el espacio de nombres de red del cliente de Relay, o --onprem-executor-listen-port no coincide con el SERVER_PORTdel ejecutor	Inicia el ejecutor con --network container:relay1-<RELAY_ID> y establece ambos puertos en el mismo valor
Después de reiniciar un contenedor, el otro pierde todo el acceso a la red y no se recupera	Con --network container:, la red del contenedor de unión se destruye cuando se reinicia el contenedor propietario. Un pod de Podman no se ve afectado, porque su contenedor de infraestructura es propietario del espacio de nombres	Inicia primero el cliente de Relay para que sea el propietario del espacio de nombres. Después de reiniciar cualquier cliente de Relay, reinicia también el contenedor del ejecutor
El ejecutor no puede encontrar las bibliotecas JCo	Los archivos están en un subdirectorio del volumen montado o el volumen está montado en la ruta incorrecta	Monte un directorio que contenga los archivos directamente, sin subdirectorios, en /opt/uipath/onprem-runtime/dep-libs

Para problemas del ejecutor que no son específicos de los contenedores, como una biblioteca nativa de JCo creada para la arquitectura incorrecta, consulta Problemas del ejecutor local.