本頁說明如何安裝及設定必要元件,在 Looker 中實作 CI/CD 工作流程。
這些操作說明使用三層式系統,包含開發、QA 和實際工作環境。不過,相同原則可套用至兩層或四層系統。
這些操作說明也假設您使用 GitHub 做為 Git 供應商。您可以使用其他 Git 供應商建立 CI/CD 工作流程,但必須具備相關專業知識,才能為供應商修改這些操作說明。
請按照相關章節的指示操作:
必要條件
Linux 環境
這個程序會使用 Gazer 和 Spectacles 這兩項工具,這兩項工具專為類 Unix 作業系統設計。每位 LookML 開發人員都必須在 Linux 環境或 macOS 中存取指令列,才能執行 CI/CD 工作流程。
如果您使用 Windows,可以在 Microsoft 的 Linux 適用的 Windows 子系統 (WSL) 中使用 Gazer 和 Spectacles。WSL 可讓您執行各種不同的 Linux 版本。如果沒有偏好的 Linux 作業系統,建議使用最新版的 Ubuntu Linux,因為支援範圍廣泛。
這些操作說明提供 Linux 系統的範例,如果您使用 macOS 或 WSL,可能需要修改。
每個層級一個 Looker 執行個體
如要啟用這項設定,系統的每個層級都需要一個 Looker 執行個體。舉例來說,如果系統有開發階段、品管階段和正式階段,就需要三個不同的執行個體。執行個體可由 Google 代管或客戶代管。
連線名稱相同
無論代表哪個層級,資料庫連線在每個 Looker 執行個體中都應具有相同名稱。舉例來說,sales
連線在所有執行個體中都應使用該名稱,而非 sales_dev
或 sales_qa
。
連線可以指向相同或不同的資料庫。不過,如果這些執行個體指向同一個資料庫,就應定義不同的暫存結構定義,以免開發或 QA 執行個體中的永久衍生資料表干擾實際工作環境。
舉例來說,如果這三個例項使用相同的資料庫,則設定可能如下:
正式版 | QA | 開發 | |
連線名稱 | sales |
sales |
sales |
資料庫 | sales_db |
sales_db |
sales_db |
暫存結構定義 | prod_sales_scratch |
qa_sales_scratch |
dev_sales_scratch |
或者,如果這三個執行個體都使用專屬資料庫,則設定可能如下:
正式版 | QA | 開發 | |
連線名稱 | sales |
sales |
sales |
資料庫 | sales_db_prod |
sales_db_qa |
sales_db_dev |
暫存結構定義 | sales_scratch |
sales_scratch |
sales_scratch |
Git 存放區
所有三個層級的每個專案都會使用單一 Git 存放區。開發例項會追蹤 main
分支,而 QA 和正式版例項通常會指向 Git 標記 (稍後會詳細說明)。
僅限首次設定的步驟
具備 Looker 管理員權限和 Git 供應商管理員權限的使用者,只需要完成一次本節中的步驟。
Git 憑證
每位開發人員的 Linux 環境都必須連線至您用來管理 LookML 的相同存放區。這可能是託管於 GitHub 等服務的外部存放區。您需要該服務的帳戶,並具備適當的憑證,才能設定存放區。您可以使用該帳戶設定 SSH 金鑰,讓 Linux 環境自動連線至該服務。
如果是 GitHub,請按照「將新的 SSH 金鑰新增至 GitHub 帳戶」一文中的操作說明進行。
建立及設定 Git 伺服器存放區
如要讓 CI/CD 工作流程正常運作,LookML 必須儲存在 Git 存放區中,並連結至 Looker 專案。在專案設定中,「Git Production Branch Name」必須設為 main
,且「Enable Advanced Deploy Mode」必須啟用。
如果尚未執行下列步驟,請按照 GitHub 的操作說明進行:
建立新存放區
- 在 GitHub UI 中,按一下右上角的「+」按鈕,然後選取「New repository」。
- 選取擁有者 (通常是您的機構),然後輸入 REPOSITORY_NAME。
- 選擇將存放區設為公開或私人 (私人存放區需要付費訂閱 GitHub),然後勾選方塊,使用 README 檔初始化存放區。
- 按下「Create repository」(建立存放區) 按鈕。
- 按下標示「<> Code」(程式碼) 的綠色按鈕,然後複製 SSH 網址。看起來會類似這樣:
git@github.com:org_name/REPOSITORY_NAME.git
。 - 在 Looker 中建立新專案。
- 進入開發模式,從左側邊欄選擇專案設定項目,然後設定 Git。
- 貼上存放區網址 (本例為
git@github.com:org_name/REPOSITORY_NAME.git
),然後選取「繼續」。 - 複製部署金鑰,然後返回這個存放區的 GitHub UI。
- 選擇「設定」,然後選擇「動作 - 一般」。
- 在「工作流程權限」下方,確認已勾選「允許 GitHub Actions 建立及核准提取要求」,然後按一下「儲存」。
- 切換至 GitHub 設定的「Deploy keys」頁面。
- 按一下「Add deploy key」按鈕,然後將部署金鑰貼到「Key」欄位。
- 新增標題 (例如
Looker-REPOSITORY_NAME
)、勾選「允許寫入存取權」核取方塊,然後按下「新增金鑰」按鈕。 - 返回 Looker,然後選擇「測試並完成設定」。
- 再次從左側邊欄選擇專案設定。將「Git Production Branch Name」(Git 正式版分支名稱) 變更為
main
。 - 選擇「啟用進階部署模式」,然後選取「儲存專案設定」。
在左側的專案設定圖示下方,您應該會看到 Deployment Manager 的部署圖示。
使用現有存放區
- 前往儲存 LookML 的 GitHub 存放區。
- 選擇「設定」,然後選擇「動作 - 一般」。
- 在「工作流程權限」下方,確認已勾選「允許 GitHub Actions 建立及核准提取要求」,然後按一下「儲存」。
- 前往 GitHub 存放區的「<> Code」部分。
- 按下標示「<> Code」(程式碼) 的綠色按鈕,然後複製 SSH 網址。看起來會類似這樣:
git@github.com:org_name/REPOSITORY_NAME.git
。 - 在 Looker 中建立新專案。
- 進入開發模式,從左側邊欄選擇專案設定項目,然後設定 Git。
- 貼上存放區網址 (本例為
git@github.com:org_name/REPOSITORY_NAME.git
),然後選取「繼續」。 - 複製部署金鑰,然後返回這個存放區的 GitHub UI。
- 依序選擇「設定」和「部署金鑰」。
- 按一下「Add deploy key」按鈕,然後將部署金鑰貼到「Key」欄位。
- 新增標題 (例如
Looker-REPOSITORY_NAME
)、勾選「允許寫入存取權」核取方塊,然後按下「新增金鑰」按鈕。 - 返回 Looker,然後選擇「測試並完成設定」。
- 再次從左側邊欄選擇專案設定。將「Git Production Branch Name」(Git 正式版分支名稱) 變更為
main
。 - 選擇「啟用進階部署模式」,然後選取「儲存專案設定」。
在左側的專案設定圖示下方,您應該會看到 Deployment Manager 的部署圖示。
建立 GitHub 動作
建議您建立多個 GitHub 動作,這樣每次變更 LookML 時,系統就會自動執行各種檢查。如要新增這些動作,您必須能夠在 Linux 環境中變更 Git 存放區。如果尚未提供,請按照「設定 Git」操作說明操作。
如要新增 GitHub 動作,請前往 Linux 環境中的存放區目錄,然後新增 .github/workflows
子目錄。設定完成後,即可從 GitHub UI 的「Actions」頁面手動執行這些動作。
Look-At-Me-Sideways (LAMS)
LAMS 是開放原始碼的 Lint 工具,可檢查 LookML 中的錯誤和不良做法。在 .github/workflows
目錄中新增名為 lams.yml
的檔案,並加入下列內容:
name: LAMS
on:
pull_request:
branches: [ main ]
push:
workflow_dispatch:
jobs:
lams_job:
runs-on: ubuntu-latest
name: LAMS LookML Linter Job
steps:
- name: Checkout your LookML
uses: actions/checkout@v4
with:
ref: ${{ github.event.pull_request.head.sha }}
fetch-depth: 0
- name: Setup Node
uses: actions/setup-node@v1
with:
node-version: '16.x'
- name: Install LAMS
run: npm install -g @looker/look-at-me-sideways@3
- name: Run LAMS
run: lams --reporting=no
每當修訂版本推送至 GitHub,或開啟提取要求以將程式碼與 main
分支版本合併時,LAMS 就會執行。
Release Please
Release Please 是一項開放原始碼工具,可自動為發布內容加上正確的版本號碼。
在 .github/workflows
目錄中新增名為 release-please.yml
的檔案,並加入下列內容:
name: release-please
on:
push:
branches:
- main
workflow_dispatch:
permissions:
contents: write
pull-requests: write
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: google-github-actions/release-please-action@v3
with:
release-type: simple
傳統提交
這項 GitHub 動作會驗證提取要求是否以符合傳統提交標準的標題開啟。
在 .github/workflows
目錄中新增名為 lint_pr_title.yml
的檔案,並加入下列內容:
name: "Lint Pull Request Title"
on:
pull_request_target:
types:
- opened
- edited
- synchronize
jobs:
main:
name: Validate PR title
runs-on: ubuntu-latest
steps:
- uses: amannn/action-semantic-pull-request@v5
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
permissions:
pull-requests:
read statuses: write
將變更推送到 GitHub
最後,請使用下列指令修訂這些 GitHub 動作變更,並將其推送至 GitHub:
git add .github/workflows/
git commit -m "chore: Added github actions"
git push
保護 main
分支
在 GitHub 使用者介面中,您應為 main
分支版本啟用分支版本保護功能,這樣一般開發人員就無法直接將變更推送至該分支版本。他們會在其他分支版本中進行變更,然後開啟提取要求。提取要求可由其他開發人員審查,然後再核准並與 main
合併。
如要設定分支版本保護,請前往存放區的 GitHub UI,依序選擇「Settings」和「Branches」,然後按下「Add branch protection rule」按鈕:
輸入 main
做為「Branch name pattern」(分支版本名稱模式),並勾選下列選項:
- 要求先提出提取要求,再合併
- 要求核准
- 在新提交推送時,取消過時的提取要求核准
最後,按下頁面底部的「建立」按鈕。
建立提取要求時,系統會執行先前在這些操作說明中設定的 GitHub 動作。首次執行後,也可以在這個 UI 中選取這些檢查,這樣一來,提取要求必須通過檢查,才能合併至 main
。
設定提取要求
在 Looker 中,您可以要求使用提取要求,並讓 Looker 代表開發人員開啟提取要求。這項設定僅適用於開發執行個體。QA 和正式版執行個體會使用進階部署模式取得更新。
如要啟用這項功能,請前往每個專案的「Project Configuration」頁面,然後選取「GitHub Integration」標題下方的「Pull Requests Required」。
按下按鈕設定 Webhook 密鑰,複製產生的隨機字串,然後按下「儲存專案設定」按鈕。
返回存放區的 GitHub UI,依序選擇「Settings」和「Webhooks」。按一下右上方的「Add webhook」按鈕:
- 在標示為「Payload URL」的欄位中輸入
https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy
- 在標示為「Secret」的欄位中,貼上您從 Looker 儲存的密鑰
- 在「您想透過哪些事件觸發這個 Webhook?」問題中,選擇「讓我選取個別事件」
確認已選取「Pull Requests」和「Pushes」:
最後,按下頁面底部的「Add webhook」按鈕。
各個 Looker 開發人員的設定步驟
下列所有安裝步驟都應在 Linux 環境中執行。
安裝 Ruby
如要執行 Gazer,必須安裝 Ruby 程式設計語言。Ruby 2.7.7 之後的任何版本都適用於 Gazer,但建議使用 Ruby 3.x.x。如要在 Ubuntu Linux 上安裝 Ruby,請執行下列指令:
sudo apt update
sudo apt install ruby
執行 ruby -v
,確認 Ruby 已正確安裝。這時應該會收到類似以下的回覆:
ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) [x86_64-linux]
這些指令也適用於 Debian Linux、Linux Mint,以及使用 Aptitude 套件管理工具的其他 Linux 版本。您可能需要搜尋適用於其他 Linux 版本的指令,或是 macOS 的安裝指令。詳情請參閱「安裝 Ruby」。
安裝 Gazer
Gazer 是 Google 員工建立的開放原始碼專案,可透過指令列工具瀏覽及管理「空間」、Look 和資訊主頁。
安裝 Ruby 後,即可使用 Ruby 的 Gem 工具安裝 Gazer:
gem install gazer
使用 gzr version
指令確認是否已安裝 Gazer。這時應該會收到類似以下的回覆:
v0.3.12
安裝 Spectacles
Spectacles 是一項開放原始碼工具,可用於測試 LookML (付費版已停用)。如要瞭解如何安裝,請參閱他們的入門指南頁面。
安裝 Git
您可以使用下列指令,在 Ubuntu Linux 上安裝 Git 版本管控軟體:
sudo apt update
sudo apt install git
使用 git --version
指令確認安裝是否成功。這時應該會收到類似以下的回覆:
git version 2.42.0.609.gbb76f46606
這些指令也適用於 Debian Linux、Linux Mint,以及使用 Aptitude 套件管理工具的其他 Linux 版本。您可能需要搜尋適用於其他 Linux 版本的指令。如需 Fedora 和 macOS 的操作說明,請參閱「入門指南 - 安裝 Git」。
設定 Git
您必須設定 Linux 環境中的 Git,才能與儲存 LookML 的 Git 存放區互動。這些操作說明適用於儲存在 GitHub 中的 LookML Git 存放區。
姓名和電子郵件地址
GitHub (以及大多數其他 Git 實作項目) 需要知道您的姓名和電子郵件地址,才能記錄活動。執行下列指令,在 Git 中設定名稱和電子郵件地址:
git config --global user.name "FIRST_NAME LAST_NAME"
git config --global user.email "EMAIL_ADDRESS"
Git 憑證
在初始 CI/CD 設定中建立了 Git 憑證。產生的私密安全殼層金鑰應在 $HOME/.ssh/config
檔案中設定。如要建立檔案,請使用下列指令:
touch $HOME/.ssh/config
chmod 600 $HOME/.ssh/config
在 $HOME/.ssh/config
檔案中插入下列文字:
Host github.com
User git
IdentityFile ~/.ssh/KEY_NAME
ControlMaster auto
ControlPath ~/.ssh/ctrl-%r@%h:%p
ControlPersist yes
請使用您按照「將新的 SSH 金鑰新增至 GitHub 帳戶」一文中的操作說明產生私密金鑰檔案時所用的名稱,取代 KEY_NAME。私密金鑰檔案的名稱與公開金鑰檔案相同,但沒有 .pub
副檔名。舉例來說,如果您使用 id_ed25519.pub
檔案中的公開金鑰,私密金鑰就會命名為 id_ed25519
。
設定本機 Git 存放區
設定 LookML 存放區後,您需要在 Linux 環境中複製該存放區。如要這麼做,請執行下列指令:
git clone GIT_URL
舉例來說,指令可能如下所示:
git clone git@github.com:my_org_name/sales_project.git
這會將 LookML 存放區複製到子目錄,例如 sales_project
。使用 cd SUB_DIRECTORY
指令進入存放區。在本例中,指令為 cd sales_project
。
進入存放區目錄後,即可使用下列指令:
指令 | 目的 |
---|---|
git checkout BRANCH_NAME |
用於切換分支。在大多數情況下,主要分支機構稱為 main ;不過,在舊版系統中,主要分支機構可能稱為 master 。 |
git fetch |
用於從伺服器擷取最新變更。 |
git pull |
用於將變更套用至已簽出的本機檔案。git pull 會隱含執行 git fetch 。 |
git tag |
用於為特定修訂版本建立有意義的標記。 |
git push |
用於將本機變更推送至伺服器。 |
設定 Gazer
如要使用 Gazer,您需要開發、QA 和正式環境例項的 API 憑證。如需建立 API 憑證的操作說明,請參閱「管理設定 - 使用者」頁面。API 憑證可能已由當初設定 CI/CD 工作流程的人員建立。在這種情況下,您可以使用現有憑證,不必為每個人產生新憑證。
將 API 憑證儲存在主目錄中,並將權限設為最低。.netrc
您可以使用下列指令建立具有正確權限的空白檔案:
touch $HOME/.netrc
chmod 600 $HOME/.netrc
在檔案中新增下列項目,但請使用您自己的 Looker 伺服器主機名稱 (適用於 machine
)、登入 API client_id
,以及密碼 API client_secret
。例如:
machine dev.example.looker.com
login 80ka7nl6lj87ftmn
password u7kw3mj5h2trfz0
machine qa.example.looker.com
login fi3qtv5at5crvd1q
password bdxtaeghnzyz0wm
machine example.looker.com
login k7lr6yv57wvzy9p2
password wcvr5qjd2isbs2s
針對每個伺服器執行 Gazer 指令 (例如下列指令),測試這項功能是否正常運作:
gzr user me --host dev.example.looker.com
結果應類似於以下內容:
+----+---------------+---------+----------+------------------+--------------+
| id|email |last_name|first_name|personal_folder_id|home_folder_id|
+----+---------------+---------+----------+------------------+--------------+
|2345|jsm@example.com|Smith |John | 2161| 708|
+----+---------------+---------+----------+------------------+--------------+
如果先前的指令無法運作,您可能需要在 gzr
指令結尾新增 --port 443
,如下所示:
gzr user me --host dev.example.looker.com --port 443
設定 Spectacles
Spectacles 使用與 Gazer 相同的 API client_id
和 client_secret
。在 Spectacles 目錄中,為每個層級建立名為 config-TIER.yaml
的檔案,例如 config-dev.yaml
。視該層級的 Looker 執行個體而定,在檔案中加入下列內容:
config-dev.yaml
base_url: https://dev.example.looker.com/
client_id: 80ka7nl6lj87ftmn
client_secret: u7kw3mj5h2trfz0
config-qa.yaml
base_url: https://qa.example.looker.com/
client_id: fi3qtv5at5crvd1q
client_secret: bdxtaeghnzyz0wm
config-prod.yaml
base_url: https://example.looker.com/
client_id: k7lr6yv57wvzy9p2
client_secret: wcvr5qjd2isbs2s
您可以執行下列指令並代入每個檔案名稱,測試每個檔案:
$ spectacles connect --config-file config-dev.yaml
您應該會收到類似以下的回覆:
Connected to Looker version 23.18.60 using Looker API 4.0