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。

这些连接可以指向相同或不同的数据库。但是，如果它们指向同一数据库，则应定义不同的临时架构，以使开发或 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 Admin 权限及其 Git 提供方管理员权限的用户完成一次。

Git 凭据

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

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

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

为了让 CI/CD 工作流正常运行，LookML 必须存储在 Git 代码库中，并连接到 Looker 项目。在项目设置中，必须将 Git Production Branch Name 设置为 main，并且必须启用启用高级部署模式。

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

创建新的代码库

  1. 在 GitHub 界面中，按右上角的 + 按钮，然后选择新建代码库。
  2. 选择所有者（可能是您的组织），然后输入 REPOSITORY_NAME。
  3. 选择将代码库设为公开还是私有（私有代码库需要付费的 GitHub 订阅），然后选中相应复选框以使用 README 文件对其进行初始化。
  4. 按创建代码库按钮。
  5. 按下标有 <> 的绿色按钮代码并复制 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. 按下标有 <> 的绿色按钮代码并复制 SSH 网址。格式类似于：git@github.com:org_name/REPOSITORY_NAME.git。
  3. 在 Looker 中，创建一个新项目。
  4. 进入开发模式，从左侧边栏中选择项目设置项，然后点击 Configure 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 界面的操作页面中手动运行这些操作。

侧向看 (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.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 操作将确保以符合传统提交标准的标题打开拉取请求。

将名为 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 和生产实例将使用高级部署模式来获取其更新。

如需启用此功能，请前往每个项目的 Project Settings，然后选择 GitHub Integration 标题下的 Pull Requests Required：

用于请求拉取请求的 Looker 界面。

按下按钮，设置网络钩子密钥，复制生成的随机字符串，然后按保存项目配置按钮。

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

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

用于配置 webhook 的 GitHub 界面。

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

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

最后，按页面底部的 Add 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 员工创建的开源项目，其目的是使用命令行工具导航和管理聊天室、Look 和信息中心。

安装 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 凭据。应在 $HOME/.ssh/config 文件中配置生成的 SSH 私钥。如需创建该文件，请使用以下命令：

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