Sidecar

Sidecar は DataFlux Func の付属コンポーネントです。

通常、DataFlux Func はコンテナ内で動作するため、ホスト上で直接 Shell コマンドを実行することはできません。一方、Sidecar はホスト上で動作するプログラムであり、DataFlux Func のプロキシとしてホスト上で直接 Shell コマンドを実行します。

ダウンロードコマンド

Bash
bash -c "$(curl -fsSL docs.dataflux-func.com/sidecar-download)"

0. 読む前の注意点

この機能には root 権限が必要です

この文書で扱うすべての shell コマンドは、root ユーザーでは直接実行でき、root 以外のユーザーでは sudo を付けて実行する必要があります

1. システムおよび環境要件

DataFlux Func を実行できるホストであれば、通常 Sidecar も実行できます。

1.1 DataFlux Func のバージョン要件

Sidecar は DataFlux Func 1.3.5 以降と組み合わせて使用する必要があります

2. クイックインストール

通常、Sidecar は DataFlux Func と同じホストにインストールされます。以下の操作は、DataFlux Func がインストール済みのホストで行うことを前提としています。

Sidecar と DataFlux Func が異なるホストで動作する場合は、対応する設定を変更する必要があります

2.1 オフラインインストール

Sidecar をインストールする前に、必要なリソースをダウンロードする必要があります。

インターネットに接続できない環境のホストでは、USB メモリなどの持ち運び可能なデバイスでホストにコピーできます。

ダウンロードしたリソースファイルには自動インストールスクリプトが同梱されており、実行するだけでインストールできます（詳細は後述）

2.1.1 ワンコマンドでのリソースファイルのダウンロード

Linux、macOS などのシステムでは、公式が提供する shell コマンドを使用してインストールパッケージをダウンロードすることを推奨します。

以下のコマンドを実行すると、Sidecar に必要なファイルが自動的にダウンロードされ、ダウンロードスクリプトが現在の環境に応じて x86_64 または aarch64 アーキテクチャのバージョンを自動的に選択します：

Bash
bash -c "$(curl -fsSL docs.dataflux-func.com/sidecar-download)"

特定のアーキテクチャのバージョンをダウンロードする必要がある場合は、以下のコマンドでダウンロードできます：

Intel x86_64 プロセッサ

Bash
bash -c "$(curl -fsSL docs.dataflux-func.com/sidecar-download)" -- --arch=x86_64

ARM aarch64 プロセッサ（ARM64v8 のこと。例：Raspberry Pi など）

Bash
bash -c "$(curl -fsSL docs.dataflux-func.com/sidecar-download)" -- --arch=aarch64

コマンドの実行が完了すると、必要なファイルはすべて、現在のディレクトリに新しく作成される dataflux-func-sidecar ディレクトリに保存されます。

Sidecar をインターネットに接続されていないサーバーにインストールする場合は、まずローカルでダウンロードしてから、ディレクトリ全体を USB メモリなどの持ち運び可能なストレージデバイスや scp ツールなどでターゲットマシンにコピーします
Sidecar をインターネットにアクセスできるサーバーにインストールする場合は、サーバー上で直接ダウンロードしてください

2.1.2 手動でのリソースファイルのダウンロード

shell コマンドの使用が不便なシステムでは、必要なリソースファイルを手動でダウンロードできます。

手動でダウンロードする場合、以下がすべてのファイルリストです：

#	内容	ファイル名	x86_64 アーキテクチャ	aarch64 アーキテクチャ
1	Sidecar バイナリプログラム	`dataflux-func-sidecar.tar.gz`	ダウンロード	ダウンロード
2	Sidecar サービス設定ファイル	`dataflux-func-sidecar.service`	ダウンロード	ダウンロード
3	Sidecar インストールスクリプト	`run-sidecar.sh`	ダウンロード	ダウンロード
4	バージョン情報	`version`	ダウンロード	ダウンロード

すべてのファイルを手動でダウンロードしたら、新しく作成した dataflux-func-sidecar ディレクトリに配置するだけです。

更新がある場合は、すべてのファイルを再ダウンロードしてください。どのファイルが変更され、どのファイルが変更されていないかを自分で推測しないでください

手動でダウンロードする際、ブラウザなどでダウンロードする場合は、キャッシュされた古い内容をダウンロードしないよう注意してください！！

2.1.3 同梱のスクリプトを使用してインストールを実行

ダウンロードした dataflux-func-sidecar ディレクトリで、以下のコマンドを実行すると、自動的に設定され、最終的に Sidecar 全体が起動します：

Sidecar は Mac をサポートしていません。Linux システムにコピーしてからインストールを実行してください

Bash
sudo bash run-sidecar.sh

自動インストールスクリプトを使用すると、数秒で高速にインストールして実行できます。自動設定される内容は次のとおりです：

/usr/local/bin/dataflux-func-sidecar 実行可能ファイルを作成
/etc/dataflux-func-sidecar 設定ファイルを作成
Sidecar プログラムを実行するための dffs ユーザーを作成
/etc/systemd/system/dataflux-func-sidecar Systemd 設定ファイルを作成し、システム起動時に自動起動するよう設定

インストールが完了すると、以下のインストール情報が表示されます：

Text Only
Bind:
    127.0.0.1:8099,172.17.0.1:8099
Secret Key:
    xxxxxxxxxxxxxxxx
To shutdown:
    sudo systemctl start dataflux-func-sidecar
To start:
    sudo systemctl stop dataflux-func-sidecar

Now open 127.0.0.1:8099,172.17.0.1:8099 and have fun!

出力内容の意味は次のとおりです：

項目	説明	対応する設定ファイル項目
Bind	リッスンアドレス。複数指定可、カンマ区切り	`BIND`
Secret Key	秘密鍵。リクエストの検証に使用	`SECRET_KEY`

なお、デフォルトのインストールでは、Bind には 2 つのアドレスがあります：

127.0.0.1:8099：ローカルネットワーク
172.17.0.1:8099：docker0、DataFlux Func との通信用

2.2. インストールの検証

Sidecar のデフォルトインストールが完了したら、以下のコマンドでインストールを検証できます：

Bash
curl http://127.0.0.1:8099

以下の情報が返された場合は、Sidecar が正常に動作していることを示します：

Text Only
Welcome to DataFlux Func Sidecar
* Version: 0.0.1
* Release Date: 2021-10-17 00:00:00

2.3. インストールオプション

自動インストールスクリプトは、さまざまなインストール要件に対応するためのインストールオプションをサポートしています。

インストール時は、自動インストールコマンドの後に --{パラメータ}[ パラメータ設定（ある場合）] を追加するだけで、インストールオプションを指定できます。

例：リッスンアドレスを指定する場合：

Bash
sudo bash run-sidecar.sh --bind 0.0.0.0.8099

2.3.1 利用可能なインストールオプション

具体的なパラメータの詳細は後述します。

`--bind`：リッスンアドレスの指定

Sidecar はデフォルトで 127.0.0.1:8099,172.17.0.1:8099 をリッスンします。ポートが使用中の場合は、別のリッスンアドレスを選択できます。

`--secret-key`：秘密鍵の指定

DataFlux Func Sidecar はデフォルトインストール時にランダムな秘密鍵を自動生成します。このパラメータを使用して秘密鍵を手動で指定できます。

3. DataFlux Func で Sidecar を呼び出す

DataFlux Func には DataFlux Func Sidecar のコネクターが用意されており、Sidecar の操作に使用できます。

3.1. Sidecar コネクターを作成

「コネクター / コネクターを追加 / DataFlux Func Sidecar（HTTP）」に移動し、Secret Key を正しく入力して作成するだけです。

Sidecar のインストール時に別のリッスンアドレスを指定した場合（Bind パラメータを変更した場合）、コネクターを作成する際にもそれに応じた変更が必要です。

3.2. コードの作成

以下はサンプルコードです：

Python
import json

@DFF.API('Test Sidecar')
def test_sidecar():
    sidecar = DFF.CONN('sidecar')
    res = sidecar.shell('hostname', wait=True, callback_url='http://172.17.0.1:8088/api/v1/sync/sidecar-callback')
    # res の内容は：
    # (200, {'data': {'stderr': '', 'stdout': 'my_host\n'}, 'message': '', 'ok': True})
    return res

@DFF.API('Test Sidecar callback')
def test_sidecar_callback(**kwargs):
    # kwargs の内容は：
    # {'stdout': 'my_host\n', 'stderr': ''}
    print(kwargs['stdout'])
    print(kwargs['stderr'])

3.3. 関数の設定

上記のサンプルコードでは：

「Test Sidecar」は主要な実行関数であり、「関数 API」または「定期実行タスク」として実行するように設定できます。

「Test Sidecar callback」は、実行後のコールバックを受信する関数であり、「関数 API」として設定する必要があります。

サンプルコードでは、callback_url パラメータの関数 API アドレスの ID 部分が sidecar-callback です。コールバック関数に「関数 API」を設定する場合も同じ ID を指定して、URL アドレスが一致するようにしてください

Sidecar と DataFlux Func が同じホストにインストールされている場合、双方は docker0 を介して相互にアクセスできます。つまり、IP アドレスは 172.17.0.1 です

「Sidecar コネクター操作オブジェクト」の詳細は後述します。

4. Sidecar コネクター操作オブジェクト API

Sidecar コネクター操作オブジェクトを使用すると、ユーザーは Sidecar を呼び出して Shell コマンドを実行できます。

DFF.CONN(...) のパラメータは次のとおりです：

パラメータ	型	必須 / デフォルト値	説明
`data_source_id`	str	必須	コネクター ID

`SidecarHelper.shell(...)`

Sidecar を呼び出して Shell コマンドを実行する場合のパラメータは次のとおりです：

パラメータ	型	必須 / デフォルト値	説明
`cmd`	str	必須	実行する Shell コマンド例：`"ls -l"`
`wait`	bool	`True`	実行完了を待つかどうか `False` に設定した場合、この関数はすぐに戻り、端末出力は返されません
`workdir`	str	`None`	Shell コマンドを実行する作業ディレクトリ例：`"/home/dev"`
`envs`	dict	`None`	環境変数。キーと値はどちらも文字列です例：`{"MY_NAME": "Tom"}`
`callback_url`	str	`None`	コールバックアドレス。コマンド実行後、`stdout` と `stderr` を POST 方式で指定された URL に送信します。通常は `wait=False` パラメータと一緒に使用し、非同期コールバックを実現します。
`timeout`	int	`3`	リクエストのタイムアウト時間注意：このパラメータは Shell コマンドのタイムアウト時間ではなく、Func が Sidecar へリクエストする際のタイムアウト時間ですつまり、Func の Sidecar へのリクエストはタイムアウトする可能性がありますが、実行中の Shell コマンドはそのために停止することはありません。

実行後コールバック

SidecarHelper.shell(...) を呼び出して callback_url パラメータを指定すると、Sidecar は Shell コマンドの実行完了後に標準出力 stdout と標準エラー stderr を POST 方式でこのアドレスに送信します。

具体的な構造は次のとおりです：

Text Only
POST {callback_url}
Content-Type: application/json

{
  "kwargs": {
    "stdout": "<標準出力テキスト>",
    "stderr": "<標準エラーテキスト>"
  }
}

この構造は DataFlux Func の「関数 API」標準 POST 方式 と一致しており、そのまま「関数 API」を使用して実行後のコールバックを受信できます

5. 日常メンテナンス

デフォルトでは、実行可能プログラムのインストール場所は /usr/local/bin/dataflux-func-sidecar です。

5.1 システムのアップグレード

インストール手順を繰り返し実行するだけです。自動インストールスクリプトが実行可能プログラムを自動的に置き換え、サービスを再起動します。

同時に、以前の設定ファイルの内容は保持されます。

5.2 サービスの起動/停止/再起動

Sidecar サービスは systemd で管理されており、直接 systemctl で操作できます：

Bash
sudo systemctl start dataflux-func-sidecar    # 起動
sudo systemctl stop dataflux-func-sidecar     # 停止
sudo systemctl restart dataflux-func-sidecar  # 再起動

5.3 設定の確認

設定ファイルは /etc/dataflux-func-sidecar にあります。

6. アンインストール

次のコマンドを順に実行します：

Bash
sudo systemctl disable --now dataflux-func-sidecar.service   # Sidecar サービスを停止し、自動起動を無効にします
sudo rm -f /etc/systemd/system/dataflux-func-sidecar.service # Sidecar の systemd サービス設定を削除します
sudo systemctl daemon-reload                                 # systemd 設定を再読み込みし、サービスの削除を反映します
sudo rm -f /usr/local/bin/dataflux-func-sidecar              # Sidecar 実行可能ファイルを削除します
sudo rm -f /etc/dataflux-func-sidecar                        # BIND と SECRET_KEY を含む設定ファイルを削除します
sudo userdel dffs                                            # インストール時に作成された Sidecar システムユーザーを削除します

6.1 検証

Bash
systemctl status dataflux-func-sidecar.service                      # サービスが削除されたか確認します。正常にアンインストールされた場合は、サービスが見つからないと表示されます
test ! -e /usr/local/bin/dataflux-func-sidecar && echo "プログラムは削除されました" # 実行可能ファイルが削除されたことを確認します
test ! -e /etc/dataflux-func-sidecar && echo "設定は削除されました"           # 設定ファイルが削除されたことを確認します
getent passwd dffs || echo "ユーザーは削除されました"                             # dffs ユーザーが存在しないことを確認します

/etc/dataflux-func-sidecar には BIND と SECRET_KEY が含まれています。再インストールに備えて設定を保持したい場合は、アンインストール前にこのファイルをバックアップしてください。

dffs ユーザーが他のプログラムでも使用されている場合は、sudo userdel dffs を実行しないでください。

7. セキュリティ上の注意

Sidecar の使用形態は、本質的にホストへ任意の実行可能コードを送信するものであり、危険性があります。

そのため、Sidecar は実装とデプロイにおいて以下の制限事項があります。

Sidecar サービスは dffs ユーザーで実行されます（DataFlux Func Sidecar の頭字語）
Sidecar は SecretKey が設定されて初めて、Shell コマンドを正常に呼び出して実行できます。
SidecarHelper.shell(...) は内部で HmacSha1 署名を実装し、改ざんやリプレイ攻撃を防止しています。

Sidecar サービスは dffs ユーザーで実行されるため、root 権限が必要なコマンドや他のユーザーのファイルを操作することはできません。必要に応じて、dffs ユーザーをユーザーグループに追加したり、ファイルの関連権限を変更したりできます。