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

Execute o cliente de Relay como uma imagem de contêiner para estabelecer túnel de saída seguros para o Test Cloud a partir de ambientes em contêiner. Antes de começar, configure um Grupo de Relay e tenha a string de configuração do cliente pronta a partir da UI 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.
• 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.

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. Salve a string de configuração codificada em base64 fornecida pela UI.

Etapa 2: configurar variáveis de ambiente

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	Não
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. Ambas as variáveis devem ser definidas juntas.

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

Podman

Para alta disponibilidade, execute dois contêineres em nós separados com nomes distintos. Substitua <RELAY_ID> pelo ID real da interface gráfica do Relay — por exemplo, execute relay1-<RELAY_ID> no host1 e relay2-<RELAY_ID> no host2.

Início rápido:

# 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

Com um certificado de CA personalizado:

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

Opções do comando Iniciar:

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.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

Kubernetes

Criar segredos:

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

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-0, relay-client-1 e assim por diante), que o serviço de Relay usa para identificar e validar clientes.

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>

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

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

# Kubernetes (previous run, if the container restarted)
kubectl logs relay-client-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: true executa o processo como um usuário não raiz.
• allowPrivilegeEscalation: false impede o escalonamento de privilégios.
• capabilities.drop: [ALL] — descarta 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