Implantação do cliente de Relay como um contêiner

Implante o cliente do UiPath Relay como uma imagem de contêiner usando o Podman, Docker ou Kubernetes para estabelecer túnel de saída seguros em ambientes em contêiner.

Execute o cliente do Relay como uma imagem de contêiner para estabelecer túneis de saída seguros para o Test Cloud a partir de ambientes conteinerizados. Antes de começar, configure um grupo do Relay e tenha a string de configuração do cliente pronta na IU do Relay.

Pré-requisitos

• Runtime de contêiner: Podman, Docker ou um cluster Kubernetes.
• Imagem do contêiner do cliente de Relay: registry.uipath.com/relay-client:<tag>. Substitua <tag> por uma versão de relay da página de downloads do UiPath Customer Portal . A versão mínima compatível é 26.4.1 ou 26.4.3 para conexões baseadas em TCP, como SAP BAPI.
• Um arquivo de configuração codificado em base64 gerado a partir da IU do Relay.
• Aceitação do contrato de licença: defina LICENSE_AGREEMENT=accept como uma variável de ambiente ou anexe --accept-license-agreement ao comando de início.
• (Opcional) Um certificado de CA personalizado se sua organização usar PKI empresarial.

Para requisitos de hardware e pré-requisitos de rede específicos da versão, consulte Implantar o cliente de Relay.

Importante:

Para conexões baseadas em TCP compatíveis, como SAP BAPI, você implanta o cliente de Relay junto com um segundo contêiner, o executor no local. Se você precisar de um, pule a etapa 3 e siga o SAP BAPI e outras conexões baseadas em TCP . Essa seção abrange o Docker e o Podman.

Etapa 1: obter a configuração

1. Abra o painel de interface gráfica do Relay.
2. Crie ou copie sua configuração de relay.
3. Crie um diretório no host para o arquivo de configuração. Qualquer diretório funciona; esta página usa /opt/uipath/relay/config como exemplo. No Windows, use um caminho do Windows, como C:\uipath\relay\config.
4. Salve a string de configuração codificada em base64 da interface gráfica lá como relay.config.b64enc. Os comandos de implantação montam esse diretório no contêiner como /relay-config; substitua o caminho de exemplo pelo seu.

Etapa 2: configurar variáveis de ambiente

Passe essas variáveis como sinalizadores -e com Podman ou Docker, ou como entradas env: no manifesto do Kubernetes, na etapa 3.

Certificado de CA personalizado

Se sua organização usar uma CA corporativa ou autoassinada, defina as seguintes variáveis juntas antes de iniciar o contêiner:

Variável	Finalidade	Required
RELAY_CUSTOM_CA_PATH	Caminho para o certificado de CA personalizado	Sim, se estiver usando CA personalizada
RELAY_CA_BUNDLE_PATH	Caminho em que o pacote de CA mesclado é gravado	Sim, se estiver usando CA personalizada

O cliente de Relay mescla a CA personalizada com o pacote de certificados do sistema antes de estabelecer quaisquer conexões TLS.

Proxy

Para rotear o tráfego de saída por meio de um proxy:

Variável	Finalidade	Required
HTTP_PROXY e HTTPS_PROXY	URLDoProxy	Não
NO_PROXY	Nomes de host, domínios ou endereços IP separados por vírgulas que ignoram o proxy	Não

Etapa 3: implantar

Substitua <RELAY_ID> pelo ID real da interface do usuário do relay. Para alta disponibilidade com o Docker ou o Podman, execute dois contêineres em nós separados com nomes distintos, por exemplo, relay1-<RELAY_ID> no host1 e relay2-<RELAY_ID> no host2. No Kubernetes, use duas réplicas com antivírus de pod, conforme no manifesto abaixo. Um início bem-sucedido registra All prerequisite checks passed.

Os comandos Podman e Docker abaixo são executados em primeiro plano com -it --rm, para que você possa assistir à primeira inicialização e o contêiner ser removido quando você o interromper. Para uma implantação de longa duração, substitua -it --rm por -d.

Podman

Início 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

Com um 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

Início 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

Com um 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

Criar segredos:

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

Implante um StatefulSet:

Use um StatefulSet quando restrições de nome de host forem aplicadas. StatefulSets fornece nomes de host estáveis e previsíveis (relay-client-<RELAY_ID>-0, relay-client-<RELAY_ID>-1 e assim por diante), que o serviço de Relay usa para identificar e validar clientes.

O manifesto monta o segredo custom-ca e define as duas variáveis RELAY_*. Se você não usar uma CA personalizada, remova essas duas variáveis, a montagem de volume custom-ca e o volume custom-ca. A investigação de prontidão usa o ponto de extremidade de integridade, que requer o cliente de Relay 26.4.2 ou 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

Verifique a implantação:

kubectl get statefulset relay-client-<RELAY_ID>

Opções do comando Iniciar

Isso se aplica a qualquer runtime.

Opção	Description	Exemplo
--config	String de configuração base64 embutida	--config "base64string..."
--config-file	Caminho para o arquivo de configuração	--config-file /relay-config/relay.config.b64enc
--log-level	Verbo baixo do registro em log: trace, debug, info, warn ou error	--log-level debug
--heartbeat-interval	Intervalo de pulsação em segundos (mínimo: 10)	--heartbeat-interval 10
--reconnect-interval	Intervalo de reconexão em segundos (mínimo: 1800)	--reconnect-interval 1800
--health-addr	Endereço de vinculação para o ponto de extremidade /healthz . O padrão é 0.0.0.0:9090; use um valor vazio para desabilitá-lo	--health-addr=0.0.0.0:9090
--enable-onprem-executor	Conecta-se ao contêiner Executor local na porta padrão 18080. Consulte SAP BAPI e outras conexões baseadas em TCP	--enable-onprem-executor
--onprem-executor-listen-port	Conecta-se ao contêiner do executor local nesta porta, que deve corresponder ao SERVER_PORT do contêiner. Qualquer sinalizador habilita o executor	--onprem-executor-listen-port 18080

SAP BAPI e outras conexões baseadas em TCP

Importante:

Requer cliente de Relay 26.4.3 ou posterior. Esta seção abrange o Docker e o Podman.

Para conexões baseadas em TCP compatíveis, como SAP BAPI, você executa dois contêineres no mesmo host:

• Contêiner de cliente de Relay: abre a conexão de saída segura para a UiPath.
• Contêiner de execução local: conecta-se ao seu sistema local e lida com a conexão baseada em TCP.

O contêiner do executor compartilha a rede do cliente de Relay, de modo que o cliente de Relay alcança o executor localhost em.

Pré-requisitos

• Imagem do contêiner do executor no local: registry.uipath.com/relay-onprem-executor:<tag>. Use o mesmo <tag> que a imagem do seu cliente de Relay. A versão mínima com suporte é 26.4.3.
• As bibliotecas SAP JCo 3 sapjco3.jar, sapidoc3.jar e libsapjco3.so. Baixe-os no Portal de Suporte da SAP, que requer uma conta SAP; A UiPath não os envia.
  • sapjco3.jar e libsapjco3.so estão no pacote SAP Java Connector 3.1 para Linux em x86_64. A imagem do executor é linux/amd64, portanto, um pacote para qualquer outra plataforma não é carregado.
  • sapidoc3.jar no pacote SAP Java IDoc Class Library 3.1 separado.
• O host de Relay pode resolver e alcançar o nome do host e a porta do sistema SAP.

Preparar as bibliotecas JCo

As bibliotecas podem estar em qualquer diretório no host. Esta página usa /opt/uipath/relay/executor-deps como exemplo; o que importa é que o comando de implantação monte seu diretório em /opt/uipath/onprem-runtime/dep-libs dentro do contêiner do executor. Os comandos usam sudo porque /opt requer raiz no Linux; omita-o para um diretório seu.

1. Crie o diretório:

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

2. Copie os três arquivos para ele. Coloque-os diretamente no diretório, não em subdiretórios:

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

3. Confirme se a biblioteca nativa é criada para x86-64:

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

   Se a saída dizer ARM aarch64 ou outra arquitetura, baixe o pacote Linux no x86_64 em vez disso. No Windows, onde file não está disponível, verifique o pacote do qual você extraiu: o correto é chamado sapjco3-linuxx86_64-<version>.

Implantar ambos os contêineres

Execute os comandos nesta ordem: o cliente de Relay primeiro, depois o executor. O executor entra na rede do cliente de Relay, portanto, o cliente de Relay deve estar em execução quando o executor for iniciado.

AVISO:

Se você reiniciar ou recriar o cliente de Relay, o executor perderá sua rede e não se recuperará por conta própria. Reinicie o Executor posteriormente, conforme descrito em Reinicialização e atualização.

Antes de executar os comandos:

• Substitua /opt/uipath/relay/config e /opt/uipath/relay/executor-deps pelos diretórios de host que você escolheu na Etapa 1 e Preparar as bibliotecas JCo. Mantenha os caminhos do lado do contêiner conforme mostrado.
• Se você já iniciou um cliente de Relay na Etapa 3, pare e remova-o. Os argumentos de um contêiner em execução não podem ser alterados.
• Se você usar uma CA personalizada ou um proxy, adicione as variáveis da etapa 2 e, para uma CA personalizada, as duas montagens de volume da etapa 3 ao comando do cliente de Relay. O cliente de Relay é o contêiner que se conecta à UiPath.
• Não publique a porta do executor com -p. Apenas o cliente de Relay precisa alcançá-lo.

Habilite o executor no cliente de Relay com qualquer sinalizador:

Bandeira	Efeito
--enable-onprem-executor	Conecta-se ao Executor na porta padrão 18080
--onprem-executor-listen-port <port>	Conecta-se ao executor em <port>. Deve corresponder a SERVER_PORTdo contêiner do executor

Os outros sinalizadores de executor, --onprem-executor-java-home e --onprem-executor-dep-dir, não têm efeito em um contêiner: a imagem do executor inclui seu próprio runtime Java e lê suas bibliotecas a partir de /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>

Ou crie um pod do Podman e execute ambos os contêineres nele com --pod. O contêiner infraestrutura do pod possui o namespace da rede, então qualquer um dos contêineres pode reiniciar por conta própria.

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>

Verificar

Leia os logs com os comandos para seu runtime:

Runtime	Logs do cliente de Relay	Logs do executor
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. Nos logs do cliente de Relay, confirme a linha de pré-requisito On-prem executor checks: OK.
2. Nos mesmos logs, localize o endpoint do executor, chamado relay1-<RELAY_ID>-system-onprem-executor-<id>, e confirme se ele chega a health check success.
3. Nos logs do executor,Started OnPremRuntimeApplication confirme.
4. Execute uma chamada de teste do conector que usa esse ponto de extremidade para confirmar se o caminho completo funciona.

Observação:

Enquanto o contêiner do executor ainda estiver iniciando, a etapa 2 pode mostrar um health check failed: dial tcp [::1]:18080: connect: connection refused primeiro. Isso é esperado e eliminado na próxima verificação, cerca de 10 segundos depois, sem reiniciar o cliente de Relay.

Para problemas, consulte Solução de problemas nesta página primeiro, em seguida, Problemas do executor no local.

Reinicialização e atualização

Você pode reiniciar ou atualizar o executor por conta própria. Se você reiniciar ou recriar o cliente do Relay, reinicie ou recrie o executor posteriormente: o executor é executado dentro da rede do cliente do Relay, e reiniciar ou recriar o cliente do Relay substitui essa rede, portanto, o contêiner do executor existente não pode se recuperar por conta própria. Use a mesma <tag> para ambas as imagens ao atualizar. Para o Podman, substitua docker por podman.

Tarefa	O que fazer
Reinicie o executor	docker restart relay-executor-<RELAY_ID>. O cliente de Relay continua em execução
Atualizar o executor	docker rm -f relay-executor-<RELAY_ID>, em seguida, execute o comando do executor novamente com o novo <tag>
Reiniciar o cliente do Relay	docker restart relay1-<RELAY_ID>, então docker restart relay-executor-<RELAY_ID>
Atualizar o cliente de Relay	Remova os dois contêineres e, em seguida, execute os dois comandos novamente com o novo <tag>, cliente de Relay primeiro. Um cliente de Relay recriado é um novo contêiner. Portanto, o executor também deve ser recriado

Operações

Configuration details

O arquivo de configuração deve conter a string JSON codificada em base64 gerada pela interface gráfica do Relay. Na inicialização, o cliente de Relay lê a configuração, decodifica-a, valida-a e conecta-se ao ponto de extremidade do serviço de Relay especificado.

• Primeira execução: a configuração é armazenada criptografada no diretório de dados.
• Execuções subsequentes: a configuração criptografada é automaticamente descriptografada e usada.
• Alterações no arquivo de configuração: exigem uma reinicialização do contêiner para entrar em vigor.

Intervalo de pulsação

A pulsação mantém as conexões TCP ociosas ativas. Reduza o intervalo se seu firewall, proxy ou tradução de endereço de rede (NAT) eliminar conexões inativas antes de 30 segundos:

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

Intervalo de reconexão

A reconexão proativa restaura a conexão em um cronograma fixo. Use isso em ambientes em que um proxy ou balanceador de carga tem um tempo limite de conexão ociosa:

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

Ponto de extremidade de integridade

Observação:

A --health-addr está disponível com o cliente de Relay 26.4.2 e posterior.

A imagem do contêiner habilita um ponto de extremidade /healthz HTTP por padrão em 0.0.0.0:9090. Use --health-addr=<address> para alterar o endereço de vínculo ou --health-addr= para desabilitar o ponto de extremidade. A investigação de prontidão do Kubernetes no manifesto de exemplo usa esse ponto de extremidade.

Como acessar os logs

# 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

A retenção de log do contêiner é controlada por seu runtime de contêiner ou política de registro em log do cluster Kubernetes, não pelo cliente de Relay.

Segurança

Aplique as seguintes configurações de segurança no manifesto do seu contêiner:

• readOnlyRootFilesystem: true: impede a modificação do sistema de arquivos do contêiner.
• runAsNonRoot: trueexecuta o processo como um usuário não raiz.
• allowPrivilegeEscalation: false: impede o escalonamento de privilégios.
• capabilities.drop: [ALL]: encerra todos os recursos do Linux.
• privileged: false: desabilita o modo privilegiado.

Armazene a configuração de relay em segredos do Kubernetes e use o controle de acesso baseado em funções (RBAC) para restringir o acesso ao segredo. Não incorpore a configuração base64 na imagem do contêiner nem a passe como uma variável de ambiente simples.

Solução de problemas

Problema	Causa	Resolution
license agreement not accepted Na inicialização	Sinalizador de licença ou variável não definido	Adicione --accept-license-agreement ao comando Iniciar ou defina LICENSE_AGREEMENT=accept
Arquivo de configuração não encontrado	Caminho ou segredo de montagem de volume incorreto	Execute kubectl describe secret relay-config e kubectl describe pod <pod-name> para verificar montagens
Não é possível conectar ao serviço de relay	Problema de rede ou firewall	Verifique os logs do pod com kubectl logs <pod-name> e os destinos de saída necessários em Implantação do cliente de Relay
Falha na mesclagem da CA personalizada	Variáveis de ambiente de CA não definidas	Definir RELAY_CUSTOM_CA_PATH e RELAY_CA_BUNDLE_PATH juntos
Nome do host não reconhecido pelo serviço de relay	O nome do pod é aleatório (Pod independente, não StatefulSet)	Use um StatefulSet em vez de um pod independente
erros de certificado x509	Certificado de CA inválido ou inacessível	Verifique o formato do certificado com openssl x509 -in custom-ca.crt -text -noout e verifique as permissões do arquivo
O ponto de extremidade do executor nunca atinge health check success	O contêiner do executor não compartilha o namespace da rede do cliente de Relay ou --onprem-executor-listen-port não corresponde ao SERVER_PORTdo executor	Inicie o executor com --network container:relay1-<RELAY_ID> e defina ambas as portas com o mesmo valor
Depois de reiniciar um contêiner, o outro perde todo o acesso à rede e não se recupera	--network container:Com, a rede do contêiner que está se associando é perdida quando o contêiner proprietário é reiniciado. Um pod Podman não é afetado, porque seu contêiner de infraestrutura tem o namespace	Inicie o cliente de Relay primeiro para que ele possua o namespace. Após qualquer reinicialização do cliente de Relay, reinicie o contêiner do executor também
O Executor não pode encontrar as bibliotecas JCo	Os arquivos estão em um subdiretório do volume montado ou o volume está montado no caminho errado	Instale um diretório que contenha os arquivos diretamente, sem subdiretórios, em /opt/uipath/onprem-runtime/dep-libs

Para problemas de executor que não são específicos de contêineres, como uma biblioteca nativa JCo criada para a arquitetura errada, consulte Problemas de executor local.