跳轉至

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 用户加入用户組、或修改文件相關權限。