跳轉到

Sidecar

Sidecar 是 DataFlux Func 的一個附帶元件。

由於通常 DataFlux Func 執行在容器內，無法直接在宿主機上執行 Shell 命令。而 Sidecar 的是一個運行於宿主機上的程式，作為 DataFlux Func 的代理直接在宿主機上執行 Shell 命令。

下載命令

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

0. 閱讀前提示

本文所有涉及到的 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 之前，需要下載所需資源。

對於無公網環境的主機，可以透過 U 盤等移動裝置複製至主機上。

下載的資原始檔附帶了自動安裝指令碼，執行即可進行安裝（詳情見下文）

2.1.1 一鍵命令下載資原始檔

對於 Linux、macOS 等系統，推薦使用官方提供的 shell 命令下載安裝包。

執行以下命令，即可自動下載 Sidecar 的所需檔案，下載指令碼會自動根據當前環境選擇下載 x86_64 或 aarch64 架構版本：

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

如需要下載指定架構的版本，可以使用以下命令下載：

  • Intel x86_64 處理器
Bash
1
/bin/bash -c "$(curl -fsSL docs.dataflux-func.com/sidecar-download)" -- --arch=x86_64
  • ARM aarch64 處理器（即 ARM64v8，如：樹莓派等）
Bash
1
/bin/bash -c "$(curl -fsSL docs.dataflux-func.com/sidecar-download)" -- --arch=aarch64

命令執行完成後，所有所需檔案都儲存在當前目錄下新建立的 dataflux-func-sidecar 目錄下。

  • 對於需要將 Sidecar 安裝到無公網的伺服器時，可以先在本機下載，之後將整個目錄透過 U 盤等移動儲存裝置，或 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
1
sudo /bin/bash run-sidecar.sh

使用自動安裝指令碼可以實現幾秒內快速安裝執行，自動配置的內容如下：

  • 建立 /usr/local/bin/dataflux-func-sidecar 可執行檔案
  • 建立 /etc/dataflux-func-sidecar 配置檔案
  • 建立 dffs 使用者用於執行 Sidecar 程式
  • 建立 /etc/systemd/system/dataflux-func-sidecar Systemd 配置檔案，並設定為開機啟動

安裝完畢後，會展示如下安裝資訊：

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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
1
curl http://127.0.0.1:8099

如返回如下資訊，則表示 Sidecar 正常執行：

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

2.3. 安裝選項

自動安裝指令碼支援一些安裝選項，用於適應不同的安裝需求

安裝時，只需要在自動安裝命令後新增 --{引數}[ 引數配置（如有）]，即可指定安裝選項

如，指定監聽地址：

Bash
1
sudo /bin/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 引數），那麼建立聯結器時也需要做相應的修改。

add-datasource.png

3.2. 編寫程式碼

以下為示例程式碼：

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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 內容為：
    # {'stderr': '', 'stdout': 'my_host\n'}

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
1
2
3
4
5
6
7
8
9
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
1
2
3
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. 安全性保障

由於 Sidecar 的使用模式本質上就是向所在主機發送任意可執行程式碼，具有危險性。

因此 Sidecar 在實現和部署上具有以下限制條件：

  1. Sidecar 服務 dffs 使用者執行（即 DataFlux Func Sidecar 首字母縮寫）
  2. Sidecar 必須配置了 SecretKey 才能正常呼叫執行 Shell 命令
  3. SidecarHelper.shell(...) 內部實現了 HmacSha1 簽名，以防止篡改、重放攻擊

由於 Sidecar 服務以 dffs 用於執行，無法執行需要 root 許可權的命令或操作其他使用者的檔案。如有需要，可以將 dffs 使用者加入使用者組、或修改檔案相關許可權。