从客户托管的 Looker 实例导出数据

客户托管型 Looker 实例的管理员可以考虑迁移到 Looker 托管型环境,主要是为了用基础架构管理开销换取更高的便利性、更强的功能可用性和托管可靠性。使用 Looker 托管式实例可大大减少安装、配置和维护 Looker 应用所需的工作量,因为与 Looker 应用相关的所有必要 IT 功能都会为您处理。

将客户托管的实例迁移到 Looker 托管的环境涉及以下主要步骤:

  1. 接收和设置:您向 Looker 团队提交工单,并填写 Looker 本地迁移调查问卷。Looker 团队会根据您对调查问卷的回答创建一个新的托管实例。
  2. 加密:Looker SRE 会生成 GnuPG (GPG) 密钥对,并与您共享公钥。
  3. 导出:您停止 Looker 实例并导出其数据(数据库、文件系统和客户管理的密钥 [CMK])。
  4. 数据传输和导入:Looker 团队将备份导入 Looker 托管式实例并进行验证。

本页面介绍了如何执行第 3 步:导出所需的任务:

准备工作

您必须先确保 Looker 实例、数据库和加密配置满足迁移要求,然后才能使用本页面上的脚本备份实例的数据。

所需配置

如需运行本页面中所述的脚本,您需要使用以下 Looker 和数据库版本:

  • 您的 Looker 实例必须运行受支持的 Looker 发布版本。
  • 您的实例必须使用与 MySQL 8.0.0 或更高版本兼容的数据库,以便 Looker 可以使用导出的数据库架构文件。

如果您使用的是 AWS KMS,请按照更改 Looker 的加密密钥文档页面上所述的步骤,迁移到 Looker 的 AES-256 GCM 加密。

为确保正确存储数据和显示字符,您的数据库排序规则必须设置为 utf8mb4(推荐)或 utf8。使用其他排序规则可能会导致数据损坏或在保存特殊字符时出错。

评估实例以进行迁移

如需确定您的客户托管型 Looker 实例是否可以迁移到 Looker 托管型 Looker(原始)实例,您必须评估实例的数据库和文件系统的大小和性能。此评估还会评估您的来源环境是否可以处理备份生成过程中发生的数据提取。这些信息有助于 Looker 团队为目标 Looker 托管实例分配足够的资源。

如需执行评估,您必须克隆 GitHub 代码库,其中包含 Looker 的脚本,用于评估 Looker 实例的计算用量和文件系统性能。此脚本依赖于 Go Looker SDK,可在 GitHub 上的 Looker O2C Migration Evaluation 代码库中找到。

以下部分将介绍运行评估实例的脚本所需完成的步骤,其中包括以下任务:

  1. 克隆包含脚本的代码库。
  2. 生成 API 凭证。
  3. 执行命令以查看计算用量。
  4. 执行命令以检查文件系统性能。

安装评估工具

在要备份 Looker 实例数据的机器上安装以下工具、语言和 SDK:

  1. Git
  2. Go 编程语言
  3. Go Looker SDK

克隆 Looker O2C 迁移评估代码库

如需克隆包含评估脚本的代码库,请从将执行分析和备份的用户的宿主目录运行以下命令:

git clone https://github.com/looker-open-source/looker-o2c-migration-tool.git

生成 API 凭证

评估脚本使用 Looker SDK 检索数据,充当 API 客户端,通过网络向 Looker 服务器发送请求。运行脚本的管理员用户必须拥有 Looker API 客户端 ID 和客户端密钥。如需为 Looker 管理员账号生成 API 凭证,请按以下步骤操作:

  1. 前往管理面板中的用户页面。
  2. 选择账号对应的修改。
  3. 在账号的详情页面上,找到 API3 密钥部分,然后选择修改密钥。
  4. 选择新建 API 密钥。
  5. Looker 将显示客户端 ID 和客户端密钥。复制这些值并将其保存在安全的位置。

生成计算使用情况信息

如需使用迁移评估脚本返回有关实例计算用量的信息,请在与 Looker 应用的 API 端点有直接网络连接的机器上运行以下命令:

cd looker-o2c-migration-tool
go run main.go --client-id API_CLIENT_ID --client-secret API_CLIENT_SECRET --looker-instance-address LOOKER_INSTANCE_ADDRESS --output-csv-path OUTPUT_CSV_PATH --ssl=SSL

替换以下内容:

  • API_CLIENT_ID:上一步中的客户端 ID。
  • API_CLIENT_SECRET:上一步中的客户端密钥。
  • LOOKER_INSTANCE_ADDRESS:Looker 实例的地址,包括协议。
  • OUTPUT_CSV_PATH:CSV 输出的路径,例如 /content/compute_usage_info.csv。
  • SSL:您的机器与 Looker 实例之间的连接是否应使用 SSL 证书。默认情况下,其值为 true。

此命令会输出一个 CSV 文件,其中包含 Looker 实例的使用情况详细信息。

生成文件系统性能信息

此脚本会显示各个模型相关目录的大小和文件数量,并执行磁盘写入测速。本文档假定 Looker 安装在用户名为 looker 的用户的主目录中,如安装 Looker 应用文档页面中所述。

如需使用迁移评估脚本返回有关实例文件系统性能的信息,请在托管 Looker 实例的机器上运行以下命令:

cd looker-o2c-migration-tool
go run main.go --file-system-evaluation --output-csv-path OUTPUT_CSV_PATH

替换以下内容:

  • OUTPUT_CSV_PATH:CSV 输出的路径,例如 /content/fs_perf_info.csv

此命令会输出一个 CSV 文件,其中包含 Looker 实例的文件系统性能。

准备好实例以进行备份

安装运行本页面所述脚本所需的软件包和依赖项,为备份实例数据做好准备。您还可以设置一些环境变量,以简化命令编写。

安装并验证依赖项

安装备份 Looker 实例数据所需的依赖项时,请使用 Linux 发行版的标准软件包管理器。以下版本对应于 Debian 12 (Bookworm) 中提供的软件包,代表每个必需软件包的最低版本。

在要备份 Looker 实例数据的机器上安装以下软件包:

  1. bash 5.2.15

  2. gpg 2.2.40 (GnuPG) - 备份生成流程会使用 gpg 对数据库和文件系统备份进行加密,然后再与 Looker 团队共享。

  3. libgcrypt 1.10.2

  4. Gpg-agent 2.2.40 (GnuPG)

  5. GNU tar 1.34

  6. gzip 1.12

  7. md5sum 9.1 (GNU coreutils)

  8. GNU grep 3.11(支持 PCRE2 10.42 2022-12-11 或更高版本)

  9. GNU sed 4.9

  10. mysql-client:与您的 MySQL 8.x 版本匹配的官方 Oracle MySQL 客户端

由于 Debian 默认使用 MariaDB 作为其 MySQL 软件包,因此请在安装依赖项之前配置官方 Oracle MySQL APT 代码库。对于其他 Linux 发行版,请参阅在 Linux 上安装 MySQL。

如需在基于 Debian 的 Linux 系统上安装官方 Oracle mysql-client 软件包和其他必需的依赖项,请完成以下步骤:

  1. 下载 MySQL APT 代码库配置软件包。查看在 Linux 上安装 MySQL,了解当前版本号,如果有更高版本,请在以下命令中替换 0.8.32-1:

    wget https://dev.mysql.com/get/mysql-apt-config_0.8.32-1_all.deb
    
  2. 安装代码库配置软件包。出现提示时,选择与您的数据库匹配的 MySQL 8.x 版本,例如 MySQL 8.4:

    sudo apt-get install ./mysql-apt-config_0.8.32-1_all.deb
    
  3. 更新 APT 软件包缓存:

    sudo apt-get update
    
  4. 安装官方 mysql-client 软件包和其他必需的依赖项:

    sudo apt-get install -y \
      bash \
      gnupg \
      libgcrypt20 \
      gnupg-agent \
      tar \
      gzip \
      coreutils \
      grep \
      sed \
      mysql-client
    

定义变量

以下命令定义了一些将在整个备份生成过程中使用的变量。请在您计划执行后续命令的所有终端上配置这些变量。

环境变量:设置备份目录路径

以下命令将设置备份目录的路径,文件将在该目录中创建。在您计划执行目录特定备份生成任务的任何终端上运行以下命令:

BACKUP_DIRECTORY="DIRECTORY_PATH"
BACKUP_DIRECTORY="${BACKUP_DIRECTORY%/}"

替换以下内容:

  • DIRECTORY_PATH:备份文件的创建路径。确保此目录足够大,可以容纳备份。请勿添加路径的前导 /。

环境变量:设置文件系统备份的来源路径

文件系统备份源路径的变量定义假定 looker 是安装 Looker 应用的用户的用户名,并且安装是在用户的主目录中进行的,如安装 Looker 应用文档页面中所述。如果您将 Looker 安装在其他目录中,则必须修改该变量。在将执行 Looker 文件系统备份的终端上设置此变量:

  LOOKER_USER="looker"
  ROOT_LOOKER_FS_DIRECTORY="$(getent passwd "$LOOKER_USER" | cut -d: -f 6)"

环境变量:定义新的 Looker 实例

定义变量来表示要导入到的实例的名称和唯一 ID。Looker 团队会为您提供这些变量的值。

export luid='LOOKER_HOSTED_INSTANCE_ID'
export customer='LOOKER_HOSTED_INSTANCE_NAME'

替换以下内容:

  • LOOKER_HOSTED_INSTANCE_ID:您要迁移到的 Looker 实例的唯一标识符
  • LOOKER_HOSTED_INSTANCE_NAME:您要迁移到的新 Looker 实例的名称

环境变量:加密密钥

以下命令将在您的实例上安装公共 GPG 密钥。在您将执行实例备份命令的任何终端上配置该变量(Looker 将为您提供该变量的值):

base64_encryption_key="BASE64_ENCRYPTION_KEY"

替换以下内容:

  • BASE64_ENCRYPTION_KEY:备份脚本用于加密备份的加密密钥。Looker 团队会为您提供此变量的值。

生成公开加密密钥

以下命令将在您的实例上安装一个公共 pgp 密钥。备份脚本会使用此密钥来加密备份。在您将执行命令来备份实例的任何终端上配置该变量。

echo -n "${base64_encryption_key}" | base64 -d | gpg --import

备份实例数据

运行以下命令,安全地打包实例文件系统和数据库架构的关键组件,以便将其转移并恢复到新的 Looker 托管式 Looker(原创版)实例。该脚本将执行备份,并使用 md5sum 验证备份的完整性。最后,它会使用 GnuPG 对备份进行加密,然后以 MD5 文件格式导出结果。

备份实例的文件系统数据

在要导出备份数据的目录中,以及在设置环境变量的同一终端中运行这些命令。选择您计划迁移到的 Looker 托管式实例类型的标签页。

Looker(原始版本)

运行以下命令,确保备份中包含用于数据验证或工作流自动化的所有自定义 Git 服务器端钩子:

cd "${BACKUP_DIRECTORY}"

function findHookPath() {
rootPath=$1

find \
    ${rootPath}/models{-user-*,}/*/.git/config \
    -maxdepth 0 \
    -type f \
    -xtype f \
  | xargs -I {} grep hooksPath {} \
  | sort \
  | uniq \
  | sed -r -e 's/^.+hooksPath = //g' \
  | xargs -I {} dirname {} \
  | sort \
  | uniq \
  | sed -r -e "s#\.\.\/\.\.\/#${rootPath}/#g"

}

hooksPath=$(findHookPath "${ROOT_LOOKER_FS_DIRECTORY}" | sort | uniq | head -1)

运行以下命令,列出所有必要的目录并进行备份:

time find "${ROOT_LOOKER_FS_DIRECTORY}" \
  -maxdepth 1 \
  -type d \
  \( \
         -name marketplace \
      -o -name bare_models \
      -o -name deploy_keys \
      -o -name models \
      -o -name remote_dependencies \
      -o -name models-self-service \
      -o -name "models-user-*" \
      -o -wholename "${hooksPath}" \
  \) | tar \
  --gzip \
  --create \
  --file="${customer}_looker_fs_backup.tar.gz" \
  --files-from=-

运行以下命令,在加密前为备份创建“指纹”:

time md5sum "${customer}_looker_fs_backup.tar.gz" > "${customer}_fs_backup.md5"

运行以下命令来加密备份:

time gpg --encrypt --yes \
  --output "${customer}_looker_fs_backup.tar.gz.enc" \
  --recipient "looker-devops+migration-${luid}@google.com" \
  "${customer}_looker_fs_backup.tar.gz"

运行以下命令,在加密后获取另一个“指纹”:

time md5sum "${customer}_looker_fs_backup.tar.gz.enc" >> "${customer}_fs_backup.md5"

校验和可帮助 Looker 验证数据备份的完整性。

Looker (Google Cloud Core)

运行此命令,确保备份中包含用于数据验证或工作流自动化的任何自定义 Git 服务器端钩子:

cd "${BACKUP_DIRECTORY}"

function findHookPath() {
rootPath=$1

find \
    ${rootPath}/models{-user-*,}/*/.git/config \
    -maxdepth 0 \
    -type f \
    -xtype f \
  | xargs -I {} grep hooksPath {} \
  | sort \
  | uniq \
  | sed -r -e 's/^.+hooksPath = //g' \
  | xargs -I {} dirname {} \
  | sort \
  | uniq \
  | sed -r -e "s#\.\.\/\.\.\/#${rootPath}/#g"

}

hooksPath=$(findHookPath "${ROOT_LOOKER_FS_DIRECTORY}" | sort | uniq | head -1)

运行以下命令,列出所有必要的目录并进行备份:

time find "${ROOT_LOOKER_FS_DIRECTORY}" \
  -maxdepth 1 \
  -type d \
  \( \
         -name marketplace \
      -o -name bare_models \
      -o -name deploy_keys \
      -o -name models \
      -o -name remote_dependencies \
      -o -name models-self-service \
      -o -name "models-user-looker" \
      -o -wholename "${hooksPath}" \
  \) | tar \
  --gzip \
  --create \
  --file="${customer}_looker_fs_backup.tar.gz" \
  --files-from=-

运行以下命令,在加密前为备份创建“指纹”:

time md5sum "${customer}_looker_fs_backup.tar.gz" > "${customer}_fs_backup.md5"

运行以下命令来加密备份:

time gpg --encrypt --yes \
  --output "${customer}_looker_fs_backup.tar.gz.enc" \
  --recipient "looker-devops+migration-${luid}@google.com" \
  "${customer}_looker_fs_backup.tar.gz"

运行以下命令,在加密后获取另一个“指纹”:

time md5sum "${customer}_looker_fs_backup.tar.gz.enc" >> "${customer}_fs_backup.md5"

校验和可帮助 Looker 验证数据备份的完整性。

此脚本会为迁移的文件系统部分生成以下文件:

  1. ${customer}_looker_fs_backup.tar.gz.enc:加密、压缩的文件系统备份。
  2. ${customer}_fs_backup.md5:包含用于验证的校验和的文件。

备份实例数据库架构

这些命令会创建一个临时配置文件,以便迁移工具连接到 Looker 实例的内部数据库,从而为备份 Looker 实例数据库架构做好环境准备。此脚本不会将用户名和主机名等敏感数据直接传递到命令中,而是将这些数据写入配置文件,供 mysqldump 和 mysql 等工具读取。

运行以下命令以创建临时配置文件并设置各种设置:

export database_name="DATABASE_SCHEMA_NAME"
temporary_cnf_file="$(mktemp --tmpdir=. --suffix .cnf)"
echo "[client]
host=DATABASE_HOST
port=DATABASE_PORT
user=DATABASE_USER
password=PASSWORD

[mariadb-dump]
no-sandbox

[mysql]
no-auto-rehash

[mysqldump]
no-tablespaces
loose_set-gtid-purged=OFF
single-transaction
quick
max_allowed_packet=1G
ignore-table=${database_name}.LookerQ_LookerBQ_ACTIVEMQ_ACKS
ignore-table=${database_name}.LookerQ_LookerBQ_ACTIVEMQ_LOCK
ignore-table=${database_name}.LookerQ_LookerBQ_ACTIVEMQ_MSGS

[Server-specific settings - mostly for mysqld/mariadbd processes]
max_allowed_packet = 1024M
" > ${temporary_cnf_file}

替换以下内容:

  • DATABASE_HOST:Looker 数据库的 DNS 或 IP。
  • DATABASE_PORT:数据库端口。
  • DATABASE_USER:用于执行导出的数据库用户名。
  • PASSWORD:将执行导出操作的用户的密码明文值。Looker 不会检查此密码。不过,如果您不想提供明文密码,可以将此变量留空,这样系统会在您运行备份命令时强制提示您输入密码。
  • DATABASE_SCHEMA_NAME:数据库或架构的名称。

如果您的数据库需要 SSL 证书才能连接,请将以下路径添加到临时配置文件中:

设置证书授权机构 (CA) 文件的路径:

ssl-ca=/etc/mysql/certs/ca.pem

设置客户端 SSL 证书的路径:

ssl-cert=/etc/mysql/certs/client-cert.pem

设置客户端 SSL 私钥的路径:

ssl-key=/etc/mysql/certs/client-key.pem

对于 MySQL 数据库,需要 SSL 并验证服务器证书:

loose-ssl-mode=VERIFY_CA

对于 MariaDB 数据库,需要 SSL 并验证服务器证书:

loose-ssl-verify-server-cert=ON

运行以下命令,执行、加密和验证数据库架构备份。

前往要存储备份的目录:

cd "${BACKUP_DIRECTORY}"

运行以下命令来备份数据库:

time mysqldump \
    --defaults-file="${temporary_cnf_file}" \
    "${database_name}" \
  | gzip > "${customer}_looker_db_backup.sql.gz"

运行以下命令,在加密前为备份创建“指纹”:

time md5sum "${customer}_looker_db_backup.sql.gz" >> "${customer}_db_backup.md5"

运行以下命令来加密备份:

time gpg --encrypt --yes \
    --output "${customer}_looker_db_backup.sql.gz.enc" \
    --recipient "looker-devops+migration-${luid}@google.com" \
    "${customer}_looker_db_backup.sql.gz"

运行以下命令,在加密后获取另一个“指纹”:

time md5sum "${customer}_looker_db_backup.sql.gz.enc" >> "${customer}_db_backup.md5"

此脚本会为迁移的数据库架构部分生成以下文件:

  1. ${customer}_looker_db_backup.sql.gz.enc:加密、压缩的数据库架构备份。
  2. ${customer}_db_backup.md5:包含用于验证的校验和的文件。

加密客户管理的加密密钥 (CMK)

以下命令将验证、格式化和加密 CMK。如果没有此加密,迁移的数据库将无法在新的 Looker 环境中解密。

注意:下一个 CMK 命令只需在托管内部数据库的机器或托管 Looker 实例的机器上运行一次,而无需在两台机器上都运行。

首先,使用当前 CMK 设置一个变量,该变量应采用 base64 格式:

CMK="CUSTOMER_CMK_KEY"

替换以下内容:

  • CUSTOMER_CMK_KEY:CMK 的值

然后,运行以下命令以生成 CMK 密钥文件、生成解密后的 CMK 的校验和、加密 CMK 文件,以及生成加密后的 CMK 的校验和:

echo -n "${CMK}" > "${customer}_looker_cmk_key"

time md5sum "${customer}_looker_cmk_key" >> "${customer}_cmk_key.md5"

time gpg --encrypt --yes \
  --output "${customer}_looker_cmk_key.enc" \
  --recipient "looker-devops+migration-${luid}@google.com" \
  "${customer}_looker_cmk_key"

time md5sum "${customer}_looker_cmk_key.enc" >> "${customer}_cmk_key.md5"

此脚本会为迁移的 CMK 部分生成以下文件:

  • ${customer}_looker_cmk_key.enc:加密的 CMK 文件
  • ${BACKUP_DIRECTORY}/${customer}_cmk_key.md5:包含用于验证的校验和的文件

准备迁移文件

您到目前为止运行的脚本已生成以下文件:

  • compute_usage_info.csv:包含实例计算用量相关信息的 CSV 文件
  • fs_perf_info.csv:包含实例文件系统性能相关信息的 CSV 文件
  • ${customer}_looker_fs_backup.tar.gz.enc:加密、压缩的文件系统备份
  • ${customer}_fs_backup.md5:包含用于验证的校验和的文件
  • ${customer}_looker_db_backup.sql.gz.enc:加密、压缩的数据库架构备份
  • ${customer}_db_backup.md5:包含用于验证的校验和的文件
  • ${customer}_cmk_key.md5:包含用于验证的校验和的文件
  • ${customer}_looker_cmk_key.enc:加密的 CMK 文件

如需将 MD5 文件合并到名为 ${customer}_backup.md5 的单个文件中,请在备份目录中运行以下命令:

cat \
    "${customer}_db_backup.md5" \
    "${customer}_fs_backup.md5" \
    "${customer}_cmk_key.md5" \
  | sort | uniq \
  > "${customer}_backup.md5"

验证备份工件

为确保备份文件完整、安全且可供迁移,请使用 Looker On-Prem 数据验证工具。此工具会执行全面验证,包括检查 MD5 校验和、GPG 加密密钥、数据库结构和 CMK 有效性。

安装验证工具

如需运行验证工具,您必须在机器上安装 Go 和 GnuPG。

如需克隆代码库并构建工具,请运行以下命令:

git clone https://github.com/looker-open-source/customer-scripts.git
cd customer-scripts/onprem-data-verifier
go build -o onprem-verifier main.go

运行验证工具

该工具会对包含备份文件的目录执行操作。在运行该工具之前,请确保所有必需的文件(四个加密工件和三个解密工件)都位于 ${BACKUP_DIRECTORY} 中。

运行以下命令来验证您的制品:

./onprem-verifier \
  --backupDir "${BACKUP_DIRECTORY}" \
  --customerName "${customer}" \
  --luid "${luid}"

成功后,该工具会生成一个 metadata.json 文件。在将备份工件移交给 Looker 团队时,您必须包含此文件。

手动生成 metadata.json 文件

如果您无法生成 metadata.json 文件(例如,运行 onprem-verifier 工具失败),则可以手动生成该文件。此流程有助于及早发现迁移问题。

在定义环境变量的同一终端中运行以下脚本:

cd "${BACKUP_DIRECTORY:?}"

fs_size=$(wc -c < "${customer:?}_looker_fs_backup.tar.gz.enc" 2>/dev/null || echo 0)
db_size=$(wc -c < "${customer:?}_looker_db_backup.sql.gz.enc" 2>/dev/null || echo 0)
current_time=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
cat > metadata.json <<EOF
{
  "customer_name": "${customer:?}",
  "instance_id": "${luid:?}",
  "generated_at": "${current_time:?}",
  "fs_total_size_bytes": ${fs_size:?},
  "db_total_size_bytes": ${db_size:?},
  "file_size_in_bytes": {
$(for FILE in *; do
  [[ ! -f "${FILE}" || "${FILE}" == "metadata.json" ]] && continue
  echo "    \"${FILE}\": $(stat -c %s "${FILE}"),"
done)
    "_SENTINEL_": 0
  }
}
EOF

移交文件

备份和加密过程结束时,您应该会获得以下文件:

  • ${customer}_looker_db_backup.sql.gz.enc
  • ${customer}_looker_fs_backup.tar.gz.enc
  • ${customer}_looker_cmk_key.enc
  • ${customer}_backup.md5
  • metadata.json
  • compute_usage_info.csv
  • fs_perf_info.csv

将这些文件交付给 Looker 团队,以便导入 Looker 托管的实例。