Relay クライアントをコンテナとしてデプロイする

Podman、Docker、または Kubernetes を使用して UiPath Relay クライアントをコンテナー イメージとしてデプロイし、コンテナー化された環境にセキュリティで保護された送信トンネルを確立します。

Relay クライアントをコンテナー イメージとして実行し、コンテナー化された環境から Test Cloud へのセキュリティで保護された送信トンネルを確立します。開始する前に、Relay グループを設定し、Relay UI からクライアント設定文字列を準備しておきます。

前提条件

• コンテナー ランタイム: Podman、Docker、または Kubernetes クラスター。
• Relay クライアント コンテナー イメージ: registry.uipath.com/relay-client:<tag>。<tag> を UiPath Customer Portal のダウンロード ページにある Relay バージョンに置き換えます。サポートされる最小バージョンは 26.4.1で、SAP BAPI などの TCP ベースの接続の場合は 26.4.3 です。
• Relay UI から生成された Base64 エンコード構成ファイル。
• ライセンス契約への同意: LICENSE_AGREEMENT=accept を環境変数として設定するか、start コマンドに --accept-license-agreement を追加します。
• (オプション)カスタム CA 証明書 (組織でエンタープライズ PKI を使用している場合)。

ハードウェア要件とバージョン固有のネットワークの前提条件については、 リレークライアントをデプロイするを参照してください。

重要:

サポートされる TCP ベースの接続 (SAP BAPI など) の場合は、Relay クライアントを 2 つ目のコンテナーであるオンプレミス Executor と一緒にデプロイします。必要な場合は、手順 3 をスキップして、 代わりに SAP BAPI およびその他の TCP ベースの接続 を実行します。このセクションでは、DockerとPodmanについて説明します。

手順 1: 構成を取得する

1. Relay UI ダッシュボードを開きます。
2. リレー構成を作成またはコピーします。
3. ホスト上に構成ファイル用のディレクトリを作成します。どのディレクトリでも機能します。このページでは、例として /opt/uipath/relay/config を使用します。Windows では、 C:\uipath\relay\configなどの Windows パスを使用します。
4. そこに UI から Base64 でエンコードされた構成文字列を として保存します relay.config.b64enc。デプロイ コマンドは、このディレクトリを としてコンテナーにマウントします /relay-config。例のパスを自分のパスに置き換えます。

手順 2: 環境変数を設定する

これらの変数は、手順 3 で Podman または Docker で -e フラグとして渡すか、Kubernetes マニフェストの env: エントリとして渡します。

カスタム CA 証明書

組織で企業 CA または自己署名 CA を使用している場合は、コンテナーを起動する前に次の変数を一緒に設定します。

変数	目的	Required
RELAY_CUSTOM_CA_PATH	カスタム CA 証明書へのパス	はい (カスタム CA を使用する場合)
RELAY_CA_BUNDLE_PATH	マージされた CA バンドルが書き込まれるパス	はい (カスタム CA を使用する場合)

Relay クライアントは、TLS 接続を確立する前に、カスタム CA をシステム証明書バンドルにマージします。

プロキシ

送信トラフィックをプロキシ経由でルーティングするには:

変数	目的	Required
HTTP_PROXY ] と [ HTTPS_PROXY	プロキシ URL	いいえ
NO_PROXY	プロキシをバイパスするコンマ区切りのホスト名、ドメイン、または IP アドレス	いいえ

手順 3: デプロイする

<RELAY_ID>を Relay UI の実際の ID に置き換えます。Docker または Podman で高可用性を確保するには、2 つのコンテナーを別々の名前の別々のノードで実行します (例: host1 の relay1-<RELAY_ID> と host2 の relay2-<RELAY_ID> )。Kubernetes では、以下のマニフェストのように、ポッドの非親和性を持つレプリカを 2 つ使用します。開始が正常に完了すると、ログ All prerequisite checks passedが記録されます。

以下の Podman コマンドと Docker コマンドは、 を使用してフォアグラウンドで実行 -it --rmため、最初の起動と、停止したときにコンテナーが削除されるのを確認できます。長期実行のデプロイの場合は、 -it --rm を -dに置き換えます。

Podman

クイック スタート:

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

カスタム CA 証明書を使用する場合

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

クイック スタート:

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

カスタム CA 証明書を使用する場合

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

シークレットを作成します。

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

StatefulSetをデプロイします。

ホスト名の制限が適用されている場合は、StatefulSetを使用します。StatefulSetは、安定した予測可能なホスト名(relay-client-<RELAY_ID>-0、 relay-client-<RELAY_ID>-1など)を提供し、Relayサービスはこれを使用してクライアントを識別および検証します。

マニフェストは、 custom-ca シークレットをマウントし、2 つの RELAY_* 変数を設定します。カスタム CA を使用しない場合は、これら 2 つの変数 ( custom-ca ボリューム マウントと custom-ca ボリューム) を削除します。Readiness Probe は正常性エンドポイントを使用します。これには Relay クライアント 26.4.2 以降が必要です。

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

デプロイを確認します。

kubectl get statefulset relay-client-<RELAY_ID>

コマンドの開始オプション

これらはすべてのランタイムに適用されます。

オプション	説明	例
--config	インライン Base64 構成文字列	--config "base64string..."
--config-file	構成ファイルへのパスです	--config-file /relay-config/relay.config.b64enc
--log-level	ログの詳細度: trace、 debug、 info、 warn、または error	--log-level debug
--heartbeat-interval	ハートビート間隔 (秒) (最小: 10)	--heartbeat-interval 10
--reconnect-interval	再接続間隔(秒)(最小:1800)	--reconnect-interval 1800
--health-addr	/healthzエンドポイントのバインド アドレスです。既定値は 0.0.0.0:9090です。無効化するには空の値を使用します	--health-addr=0.0.0.0:9090
--enable-onprem-executor	オンプレミスの Executor コンテナーに既定のポート 18080で接続します。「SAP BAPI およびその他の TCP ベースの接続」をご覧ください	--enable-onprem-executor
--onprem-executor-listen-port	このポートでオンプレミスの Executor コンテナーに接続します。このポートは、コンテナーの SERVER_PORTと一致する必要があります。どちらのフラグを設定すると、Executor が有効になります	--onprem-executor-listen-port 18080

SAP BAPI およびその他の TCP ベースの接続

重要:

Relay クライアント 26.4.3 以降が必要です。このセクションでは、Docker と Podman について説明します。

サポートされる TCP ベースの接続 (SAP BAPI など) の場合は、同じホスト上で 2 つのコンテナーを実行します。

• Relay クライアント コンテナー: UiPath へのセキュリティで保護されたアウトバウンド接続を開きます。
• オンプレミスの Executor コンテナー: オンプレミス システムに接続し、TCP ベースの接続を処理します。

Executor コンテナーは Relay クライアントのネットワークを共有しているため、Relay クライアントは で Executor に localhostします。

前提条件

• オンプレミスの Executor コンテナー イメージ: registry.uipath.com/relay-onprem-executor:<tag>。Relay クライアント イメージと同じ <tag> を使用します。サポートされる最小バージョンは 26.4.3です。
• SAP JCo 3 ライブラリ sapjco3.jar、 sapidoc3.jar、 libsapjco3.soです。SAP サポート ポータルからダウンロードします。このポータルには SAP アカウントが必要です。UiPath では出荷されません。
  • sapjco3.jar と libsapjco3.so は、SAP Java Connector 3.1 パッケージ for Linux on x86_64 に含まれています。Executor イメージは linux/amd64であるため、他のプラットフォーム用のパッケージは読み込まれません。
  • sapidoc3.jar は、個別の SAP Java IDoc クラス ライブラリ 3.1 パッケージに含まれています。
• Relay ホストは、SAP システムのホスト名とポートを解決して到達できます。

JCoライブラリのステージング

ライブラリは、ホスト上の任意のディレクトリに存在できます。このページでは、例として /opt/uipath/relay/executor-deps を使用します。重要なのは、デプロイ コマンドがディレクトリを Executor コンテナー内の /opt/uipath/onprem-runtime/dep-libs にマウントすることです。Linux では root を必要とするため、コマンド/opt sudoを使用します。所有するディレクトリの場合は省略します。

1. ディレクトリを作成します。

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

2. そこに 3 つのファイルをコピーします。サブディレクトリではなく、ディレクトリに直接配置します。

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

3. ネイティブ ライブラリが x86-64 用に構築されていることを確認します。

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

   出力に ARM aarch64 または別のアーキテクチャと表示されている場合は、代わりに Linux on x86_64 パッケージをダウンロードします。file が利用できない Windows では、抽出元のパッケージを確認します。正しいパッケージの名前は sapjco3-linuxx86_64-<version>です。

両方のコンテナーをデプロイします

コマンドを最初に Relay クライアント、次に Executor の順に実行します。Executor は Relay クライアントのネットワークに参加するため、Executor の起動時に Relay クライアントが実行されている必要があります。

警告:

Relay クライアントを再起動または再作成すると、Executor はネットワークを失い、自律的に回復しません。「 再起動とアップグレード」の説明に従って、後で Executor を再起動します。

コマンドを実行する前に、以下を行います。

• /opt/uipath/relay/configと /opt/uipath/relay/executor-deps を、手順 1 で選択したホストディレクトリに置き換え、JCo ライブラリをステージングします。図のように、コンテナー側のパスをそのまま使用します。
• 手順 3 で Relay クライアントを既に起動している場合は、停止して削除します。実行中のコンテナーの引数は変更できません。
• カスタム CA またはプロキシを使用する場合は、手順 2 の変数を追加し、カスタム CA の場合は手順 3 の 2 つのボリューム マウントを Relay クライアント コマンドに追加します。Relay クライアントは、UiPath に接続するコンテナーです。
• を使用して Executor ポートをパブリッシュしないでください -p。Relay クライアントのみがそこに到達する必要があります。

Relay クライアントで Executor を有効化し、以下のいずれかのフラグを設定します。

フラグ	効果
--enable-onprem-executor	Executor に既定のポートで接続します 18080
--onprem-executor-listen-port <port>	<port>で Executor に接続します。Executor コンテナーの SERVER_PORT と一致する必要があります

他の Executor フラグである --onprem-executor-java-home および --onprem-executor-dep-dirは、コンテナー内では無効です。Executor イメージには独自の Java ランタイムが含まれており、そのライブラリは から読み取 /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>

または、Podman ポッドを作成し、その中で両方のコンテナーを --podで実行します。ポッドのインフラ コンテナーはネットワーク名前空間を所有しているため、どちらのコンテナーも自動的に再起動できます。

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>

検証

ランタイムのコマンドを含むログを読み取ります。

実行時	Relay クライアント ログ	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. Relay クライアント ログで、前提条件の行 On-prem executor checks: OKを確認します。
2. 同じログで、 relay1-<RELAY_ID>-system-onprem-executor-<id>という名前の Executor エンドポイントを見つけ、 に到達していることを確認します health check success。
3. Executor のログで、 Started OnPremRuntimeApplicationを確認します。
4. このエンドポイントを使用するコネクタからテスト呼び出しを実行して、フル パスが機能することを確認します。

注:

Executor コンテナーがまだ起動している間に、手順 2 で最初に 1 つの health check failed: dial tcp [::1]:18080: connect: connection refused が表示される場合があります。これは予期されており、Relay クライアントを再起動することなく、約 10 秒後の次のチェックでクリアされます。

問題については、まずこのページの 「トラブルシューティング 」を参照し、次に「 オンプレミス Executor の問題」を参照してください。

再起動とアップグレード

Executor は、自身で再起動またはアップグレードできます。Relay クライアントを再起動または再作成する場合は、後で Executor も再起動または再作成します: Executor は Relay クライアントのネットワーク内で実行され、Relay クライアントを再起動または再作成するとそのネットワークが置き換えられるため、既存の Executor コンテナーは単独で回復できません。アップグレードする際は、両方のイメージに同じ <tag> を使用します。Podman の場合、 docker を podmanに置き換えます。

タスク	何をすべきか
Executor を再起動します	docker restart relay-executor-<RELAY_ID>.Relay クライアントは実行を続けます
Executor をアップグレードする	docker rm -f relay-executor-<RELAY_ID>を使用してから、新しいコマンドを使用して executor コマンドを再度実行します。 <tag>
Relay クライアントを再起動します	docker restart relay1-<RELAY_ID>、その後 docker restart relay-executor-<RELAY_ID>
Relay クライアントをアップグレードする	両方のコンテナーを削除してから、新しい <tag>で両方のコマンドをもう一度実行します。 Relay クライアントを最初に実行します。再作成された Relay クライアントは新しいコンテナーであるため、Executor も再作成する必要があります

操作

設定の詳細

構成ファイルには、Relay UI によって生成された Base64 でエンコードされた JSON 文字列が含まれている必要があります。起動時に、リレークライアントは構成を読み取り、デコードし、検証し、指定されたリレーサービスエンドポイントに接続します。

• 最初の実行: 構成は暗号化されてデータ ディレクトリに保存されます。
• 後続の実行: 暗号化された設定は自動的に復号され、使用されます。
• 構成ファイルの変更: 有効にするには、コンテナーの再起動が必要です。

ハートビート間隔

ハートビートは、アイドル状態の TCP 接続を維持します。ファイアウォール、プロキシ、またはネットワーク アドレス変換 (NAT) がアイドル状態の接続を 30 秒前に切断する場合は、間隔を短くします。

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

再接続の間隔

プロアクティブ再接続は、固定スケジュールで接続を再確立します。プロキシまたはロード バランサーにアイドル接続タイムアウトがある環境で使用します。

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

正常性エンドポイント

注:

--health-addr オプションは、Relay クライアント (26.4.2) 以降で使用できます。

コンテナー イメージでは、0.0.0.0:9090で既定で HTTP /healthz エンドポイントが有効になります。--health-addr=<address> を使用してバインド アドレスを変更するか、--health-addr= を使用してエンドポイントを無効にします。マニフェストの例の Kubernetes Readiness Probe は、このエンドポイントを使用します。

ログにアクセスする

# 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

コンテナログの保持は、Relayクライアントではなく、コンテナランタイムまたはKubernetesクラスタロギングポリシーによって制御されます。

セキュリティ

コンテナー マニフェストに次のセキュリティ設定を適用します。

• readOnlyRootFilesystem: true: コンテナー ファイルシステムを変更できません。
• runAsNonRoot: true: プロセスを非 root ユーザーとして実行します。
• allowPrivilegeEscalation: false: 権限の昇格を防止します。
• capabilities.drop: [ALL]: Linux のすべての機能を削除します。
• privileged: false: 特権モードを無効化します。

リレーの構成は Kubernetes シークレットに保存し、ロールベースのアクセス制御 (RBAC) を使用してシークレット アクセスを制限します。Base64 の構成をコンテナー イメージに埋め込んだり、プレーンな環境変数として渡したりしないでください。

トラブルシューティング

症状	原因	解決方法
license agreement not accepted 起動時	ライセンス フラグまたは変数が設定されていない	start コマンドに --accept-license-agreement を追加するか、 LICENSE_AGREEMENT=accept
設定ファイルが見つからない	ボリュームのマウント パスまたはシークレットが正しくない	kubectl describe secret relay-config と kubectl describe pod <pod-name> を実行してマウントを確認します
中継サービスに接続できない	ネットワークまたはファイアウォールの問題	kubectl logs <pod-name> でポッド ログをチェックし、リレー クライアントのデプロイで必要な送信先を確認します
カスタム CA のマージに失敗	CA 環境変数が両方とも設定されていない	RELAY_CUSTOM_CA_PATHとRELAY_CA_BUNDLE_PATHの両方を同時に設定する
ホスト名がリレー サービスで認識されない	Pod 名がランダムである (スタンドアロン Pod、StatefulSet ではない)	スタンドアロンのPodの代わりにStatefulSetを使用する
x509 証明書エラー	無効またはアクセスできない CA 証明書	証明書の形式を openssl x509 -in custom-ca.crt -text -noout で検証し、ファイルのアクセス許可を確認します
Executor エンドポイントが到達しない health check success	Executor コンテナーが Relay クライアントのネットワーク名前空間を共有していないか、 --onprem-executor-listen-port Executor のネットワーク名前空間と一致しません SERVER_PORT	Executor を で起動し、両方のポートを同じ値に設定--network container:relay1-<RELAY_ID>
一方のコンテナーを再起動すると、もう一方のコンテナーはすべてのネットワーク アクセスを失い、回復しません	--network container:では、所有するコンテナーが再起動したときに、結合しているコンテナーのネットワークが破棄されます。Podman ポッドは影響を受けません。そのインフラ コンテナーが 名前空間を所有しているからです	最初に Relay クライアントを起動して、名前空間を所有します。Relay クライアントを再起動した後は、Executor コンテナーも再起動します
Executor が JCo ライブラリーを見つけられない	ファイルがマウントされたボリュームのサブディレクトリにあるか、ボリュームが間違ったパスにマウントされています	ファイルをサブディレクトリなしで直接保持するディレクトリを にマウントします。 /opt/uipath/onprem-runtime/dep-libs

コンテナーに固有ではないエグゼキューターの問題 (間違ったアーキテクチャ用にビルドされた JCo ネイティブ・ライブラリーなど) については、 オンプレミス・エグゼキューターの問題を参照してください。