Looker CI/CD 安装和配置

本页介绍了如何安装和配置必要的组件，以在 Looker 中实现 CI/CD 工作流。

以下说明使用了包含开发、质量检查和生产环境的三层系统。不过，同样的原则也可以应用于两层或四层系统。

以下说明还假定使用 GitHub 作为 Git 提供商。您可以使用其他 Git 提供商来创建 CI/CD 工作流；但是，您必须具备为提供商修改这些说明的专业知识。

请按照与您相关的部分中的说明操作：

前提条件

Linux 环境

此过程使用 Gazer 和 Spectacles 工具，这些工具旨在与类 Unix 操作系统配合使用。每位 LookML 开发者都必须在您计划在其中运行 CI/CD 工作流的 Linux 环境或 macOS 中访问命令行。

如果您使用的是 Windows，则可以在 Microsoft 的 适用于 Linux 的 Windows 子系统 (WSL) 中使用 Gazer 和 Spectacles。WSL 可让您运行各种不同的 Linux 风格。如果您没有首选的 Linux 操作系统，则最新版本的 Ubuntu Linux 因为它具有广泛的支持，因此是一个不错的选择。

这些说明提供了适用于 Linux 系统的示例，如果您使用的是 macOS 或 WSL，则可能需要进行修改。

每个层级一个 Looker 实例

如需启用此配置，系统的每个层级都需要一个 Looker 实例。例如，如果系统包含开发阶段、质量检查阶段和生产阶段，则需要三个单独的实例。这些实例可能由 Google 或客户托管。

相同的连接名称

数据库连接在每个 Looker 实例中应具有相同的名称，无论它们代表的层级如何。例如，sales 连接在所有实例中都应使用该名称，而不是 sales_dev 或 sales_qa。

这些连接可以指向相同或不同的数据库。但是，如果它们指向同一数据库，则应定义不同的预留架构，以便开发或质量检查实例中的永久派生表不会干扰生产环境。

例如，如果所有三个实例都使用相同的数据库，可按如下方式配置数据库：

生产 质量检查 开发
连接名称 sales sales sales
数据库 sales_db sales_db sales_db
暂存架构 prod_sales_scratch qa_sales_scratch dev_sales_scratch

或者，如果为所有三个实例使用唯一的数据库，则可以将它们配置如下：

生产 质量检查 开发
连接名称 sales sales sales
数据库 sales_db_prod sales_db_qa sales_db_dev
Scratch 架构 sales_scratch sales_scratch sales_scratch

Git 代码库

所有三个层级中的每个项目都将使用一个 git 代码库。开发实例将跟踪 main 分支，而 QA 和生产实例通常指向 Git 标记（稍后将详细介绍）。

仅限首次设置的步骤

拥有 Looker 管理员权限以及其 Git 提供程序的管理员权限的用户只需完成本部分中的步骤一次。

Git 凭据

每个开发者的 Linux 环境都需要连接到您用于管理 LookML 的同一代码库。这可能是在 GitHub 等服务中托管的外部代码库。您需要拥有该服务的账号，并且该账号必须具有适当的凭据才能配置代码库。您可以使用该账号设置 SSH 密钥，以允许您的 Linux 环境自动连接到该服务。

对于 GitHub，请按照向 GitHub 账号添加新的 SSH 密钥中的说明操作。

创建和配置 Git 服务器代码库

为了使 CI/CD 工作流正常运行，LookML 必须存储在 Git 代码库中，并与 Looker 项目相关联。在项目设置中，必须将 Git 正式版分支名称设置为 main，并启用启用高级部署模式。

如果您尚未执行以下步骤，请按照 GitHub 的以下说明操作：

创建新代码库

  1. 在 GitHub 界面中，按右上角的 + 按钮，然后选择新建代码库。
  2. 选择所有者（可能是贵组织），然后输入 REPOSITORY_NAME。
  3. 选择将代码库设为公开还是私有（私有代码库需要付费订阅 GitHub），然后选中相应复选框以使用自述文件初始化代码库。
  4. 按创建代码库按钮。
  5. 按标签为 <> Code 的绿色按钮，然后复制 SSH 网址。它看起来类似于：git@github.com:org_name/REPOSITORY_NAME.git。
  6. 在 Looker 中，创建新项目。
  7. 进入开发模式，从左侧边栏中选择项目设置项，然后点击 Configure Git。
  8. 粘贴代码库网址（本例中为 git@github.com:org_name/REPOSITORY_NAME.git），然后选择继续。
  9. 复制部署密钥并返回此代码库的 GitHub 界面。
  10. 依次选择设置和部署密钥。
  11. 点击添加部署密钥按钮，然后将部署密钥粘贴到密钥字段中。
  12. 添加一个标题（例如 Looker-REPOSITORY_NAME），选中允许写入权限复选框，然后按添加密钥按钮。
  13. 返回 Looker，然后选择测试并完成设置。
  14. 再次从左侧边栏中选择“项目设置”。将 Git Production Branch Name 更改为 main。
  15. 选择启用高级部署模式，然后选择保存项目配置。

在左侧的项目设置图标下方，您应该会看到 Deployment Manager 的部署图标。

使用现有代码库

  1. 导航到存储您的 LookML 的 GitHub 代码库。
  2. 按标签为 <> Code 的绿色按钮，然后复制 SSH 网址。它看起来类似于：git@github.com:org_name/REPOSITORY_NAME.git。
  3. 在 Looker 中，创建新项目。
  4. 进入开发模式，然后从左侧边栏中选择“项目设置”项，接着选择配置 Git。
  5. 粘贴代码库网址（在此示例中为 git@github.com:org_name/REPOSITORY_NAME.git），然后选择继续。
  6. 复制部署密钥并返回此代码库的 GitHub 界面。
  7. 依次选择设置和部署密钥。
  8. 点击添加部署密钥按钮，然后将部署密钥粘贴到密钥字段中。
  9. 添加一个标题（例如 Looker-REPOSITORY_NAME），选中允许写入权限复选框，然后按添加密钥按钮。
  10. 返回 Looker，然后选择测试并完成设置。
  11. 再次从左侧边栏中选择“项目设置”。将 Git Production Branch Name 更改为 main。
  12. 选择启用高级部署模式，然后选择保存项目配置。

在左侧的项目设置图标下方，您应该会看到 Deployment Manager 的部署图标。

创建 GitHub 操作

创建多个 GitHub 操作非常有用，这样每次进行 LookML 更改时，系统就会自动执行各种检查。如需添加这些操作，您需要能够在 Linux 环境中更改 Git 代码库。如果尚未安装，请按照配置 Git 中的说明操作。

如需添加 GitHub 操作，请在 Linux 环境中转到代码库的目录，并添加子目录 .github/workflows。设置完成后，您可以在 GitHub 界面的操作页面中手动运行这些操作。

Look-At-Me-Sideways (LAMS)

LAMS 是一个开源 linter，用于检查您的 LookML 是否存在错误和不良做法。将一个名为 lams.yml 的文件添加到 .github/workflows 目录中，其中包含以下内容：

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@v1
    - 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 是一款开源工具，可自动为版本添加正确的版本号标记。

将一个名为 release-please.yml 的文件添加到 .github/workflows 目录中，其中包含以下内容：

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
          package-name: sales_project

常规提交

此 GitHub Action 可确保拉取请求的标题符合传统提交标准。

将名为 lint_pr_title.yml 的文件添加到 .github/workflows 目录，其中包含以下内容：

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 }}

将更改推送到 GitHub

最后，使用以下命令提交这些 GitHub 操作更改并将其推送到 GitHub：

git add .github/workflows/
git commit -m "chore: Added github actions"
git push

保护 main 分支

在 GitHub 界面中，您应为 main 分支启用分支保护，以便普通开发者无法直接将更改推送到该分支。而是在其他分支中进行更改，然后打开拉取请求。拉取请求在获得批准并与 main 合并之前，可以由其他开发者进行审核。

如需配置分支保护，请转到代码库的 GitHub 界面，依次选择设置和分支，然后按添加分支保护规则按钮：

用于添加分支保护的 GitHub 界面。

输入 main 作为分支名称模式，然后检查以下选项：

  • 合并前要求提交拉取请求
  • 需要批准
  • 在推送新提交时忽略过时的拉取请求批准

用于设置分支保护选项的 GitHub 界面。

最后，按页面底部的创建按钮。

创建拉取请求后，系统将运行之前在这些说明中配置的 GitHub 操作。在它们首次运行后，您也可以在此界面中选择它们，这样它们必须成功，才能将拉取请求合并到 main 中。

配置拉取请求

在 Looker 中，您可以要求使用拉取请求，并让 Looker 代表开发者打开 PR。此值应仅针对开发实例进行配置。QA 和生产实例将使用高级部署模式来获取其更新。

如需启用此功能，请前往每个项目的项目配置页面，然后选择 GitHub 集成标题下的 Pull Requests Required。

按相应按钮设置网络钩子 Secret，复制生成的随机字符串，然后按 Save Project Configuration（保存项目配置）按钮。

返回代码库的 GitHub 界面，依次选择 Settings（设置）和 Webhooks（Webhook）。按右上角的 Add webhook 按钮：

  • 在标记为载荷网址的字段中，输入 https://LOOKER_HOST_NAME/webhooks/projects/PROJECT_NAME/deploy
  • 在标记为密钥的字段中，粘贴您从 Looker 保存的密钥。
  • 对于问题“您想通过此 Webhook 触发哪些事件？”，请选择让我选择个别事件

用于配置 webhook 的 GitHub 界面。

确保选中拉取请求和推送：

用于拉取请求和推送的 GitHub 复选框。

最后，按页面底部的 Add webhook（添加 Webhook）按钮。

面向每位 Looker 开发者的设置步骤

以下所有安装步骤都应在您的 Linux 环境中执行。

安装 Ruby

您需要安装 Ruby 编程语言才能运行 Gazer。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 员工创建的一个开源项目，可让您使用命令行工具浏览和管理聊天室、外观和信息中心。

安装 Ruby 后，Ruby 的 Gem 工具可用于安装 Gazer：

gem install gazer

使用 gzr version 命令确认是否已安装 Gazer。这应该会返回类似于以下内容的响应：

v0.3.12

安装眼镜

Spectacles 是一款用于测试 LookML 的非 Google 工具。Spectacles 同时提供付费版本和开源版本，您可以在其使用入门页面上找到安装详情。

安装 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 变种的命令。例如，您可以在使用入门 - 安装 Git 中找到有关 Fedora 和 macOS 的说明。

配置 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 凭据。生成的 SSH 私钥应在 $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

使用您按照向 GitHub 账号添加新的 SSH 密钥说明生成的私钥文件的名称，替换 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，您需要拥有每个开发、质量检查和生产实例的 API 凭据。有关创建 API 凭据的说明，请参阅管理员设置 - 用户页面。API 凭据可能是由最初设置 CI/CD 工作流的人员创建的。在这种情况下，您可以使用现有凭据；无需为每个用户生成新的凭据。

将您的 API 凭据存储在主目录中具有最低权限的 .netrc 文件中。您可以使用以下命令创建一个具有正确权限的空文件：

touch $HOME/.netrc
chmod 600 $HOME/.netrc

将如下条目添加到该文件中，但针对 machine 使用您自己的 Looker 服务器主机名，针对登录使用 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