向 Logging 代理授权

本指南介绍如何确保您在虚拟机 (VM) 实例上安装的 Logging 代理获得将遥测数据发送到 Google Cloud Observability 的授权。

授权概览

授权过程用于确定经过身份验证的客户端对一组资源具有哪些权限。Google Cloud 使用应用默认凭据 (ADC) 向 Compute Engine 虚拟机实例上的 Logging 代理授权。

Logging 代理支持使用 ADC 对虚拟机的关联服务账号或服务账号密钥进行身份验证。

  • 关联的服务账号是指特定于给定资源（例如虚拟机）的服务账号。该服务账号具有自己的唯一凭据。ADC 使用虚拟机的元数据服务器来获取服务的凭据。
  • 服务账号密钥是指用于向项目中的服务账号的密钥对进行授权的私钥，可让您创建访问令牌。您可以使用该令牌提供身份，以便代表服务账号与 Google Cloud API 进行交互。

我们建议您尽可能将 ADC 配置为对关联的服务账号进行身份验证，因为私钥需要本地存储，该存储可能会被破解。如需详细了解服务账号密钥，请参阅管理服务账号密钥的最佳实践。

对于 AWS EC2 虚拟机实例，Logging 代理仅支持使用服务账号密钥方法进行身份验证。

准备工作

如果以下任何一项适用于您，请阅读本指南：

  • 如果您运行非常旧的 Compute Engine 实例，或者您已修改 Compute Engine 实例的访问权限范围或服务账号设置，则必须完成本指南中的步骤才能安装代理。这些虚拟机可能没有所需的服务账号密钥文件。如需了解如何验证实例的访问权限范围和服务账号设置，请参阅验证 Compute Engine 凭据。

    在新创建的 Compute Engine 虚拟机实例上，访问权限范围和服务账号设置足以运行代理。

  • 如果您运行 Amazon EC2 (AWS VC2) 虚拟机实例，请在安装代理之前执行以下操作：

    1. 通过 EC2 实例确定 AWS 账号的 AWS 托管项目。托管项目是一个 Google Cloud 项目，其唯一目的是将 EC2 实例的指标和日志存储在 AWS 账号中。

      如果您有 AWS 账号的 AWS 连接器项目，则连接器项目为 AWS 宿主项目。

      如果该账号没有 AWS 连接器项目，请搜索现有 Google Cloud 项目以确定您之前是否为该账号创建了 AWS 托管项目。如果找到托管项目，则使用该项目。

      如果您找不到该账号的 AWS 托管项目，我们建议您创建一个 Google Cloud 项目作为托管项目。如果您在多个 AWS 账号中拥有 EC2 实例，请为每个账号创建一个 Google Cloud 项目。我们还建议您对这些项目使用命名惯例，或使用项目标签，以便识别托管项目。我们不建议重复使用现有的 Google Cloud 项目，尤其是它包含任何 Google Cloud 资源时。

    2. 完成使用服务账号密钥文件为代理授权的步骤。

如需验证访问权限范围，请执行以下操作：

  1. 通过在 Compute Engine 实例上运行以下命令来查询访问权限范围：
    curl --silent --connect-timeout 1 -f -H "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/scopes

  2. 在命令输出中，如果列出了访问权限范围 https://www.googleapis.com/auth/cloud-platform，则表明您拥有足够的授权。

    如果未列出 https://www.googleapis.com/auth/cloud-platform，则您将需要两个访问权限范围，即以下每个“Logging”和“Monitoring”对中的一个范围：

    • https://www.googleapis.com/auth/logging.write 或
      https://www.googleapis.com/auth/logging.admin
    • https://www.googleapis.com/auth/monitoring.write 或
      https://www.googleapis.com/auth/monitoring.admin

如需修改访问权限范围，请执行以下操作：

  1. 在 Google Cloud 控制台的导航面板中，选择 Compute Engine，然后选择虚拟机实例：

    前往虚拟机实例

  2. 如有必要，点击 Google Cloud 项目的下拉列表，然后选择您项目的名称。
  3. 从导航菜单中选择虚拟机实例，选择实例标签页，然后选择虚拟机的名称。
  4. 点击 停止以关停该虚拟机。
  5. 虚拟机停止后，点击 修改。
  6. 在页面的身份和 API 访问权限部分，找到访问权限范围，然后选择针对每个 API 设置访问权限。
  7. 对于 Stackdriver Logging API 和 Stackdriver Monitoring API 条目，请选择只写。
  8. 点击保存，然后点击  启动/恢复以重启虚拟机。

使用服务账号

身份验证是指确定客户端身份的过程。 如果您要进行身份验证，建议使用服务账号，这种特殊的账号通常由应用或工作负载（而非真人）使用。如需了解详情，请参阅服务账号概览。

无论代码在何处（Compute Engine、App Engine 或本地）运行，您都可以使用服务账号进行身份验证。如需了解详情，请参阅在 Google 进行身份验证。

本部分介绍如何创建新的服务账号并向其授予必要的角色，以及如何更新现有服务账号（如果它没有必要的角色）。

创建服务账号

如需创建服务账号，请完成创建服务账号过程并提供以下信息：

  • 选择要在其中创建服务账号的 Google Cloud 项目。

    • 对于 Compute Engine 实例，请选择您在其中创建了实例的项目。

    • 对于 Amazon EC2 实例，请选择 AWS 托管项目。

  • 在角色下拉菜单中，选择以下角色：

    • Logging > Logs Writer。这将授权 Logging 代理提取日志。
    • Monitoring > Monitoring Metric Writer。这将授权 Logging 代理提取自己的运行状况指标。

  • 如果您计划使用服务账号密钥进行身份验证，请选择 JSON 作为密钥类型，然后点击创建。

    点击创建时，系统会将包含服务账号密钥的文件下载到您的本地系统。如需了解详情，请参阅创建和删除服务账号密钥。

接下来，根据您是使用关联的服务账号还是使用服务账号私钥进行授权来配置服务账号和设置。

验证并修改现有服务账号的角色

您可以使用 Google Cloud 控制台来确定现有服务账号具有哪些角色，并添加任何缺少的必要角色：

  1. 在 Google Cloud 控制台的导航面板中，选择 IAM：

    进入 IAM

  2. 如有必要，点击 Google Cloud 项目的下拉列表，然后选择您项目的名称。

  3. 如果您没有看到 IAM 主账号（用户和服务账号）的列表，请选择权限标签页。

  4. 在按主账号查看列表中，找到服务账号的条目。角色列列出了授予该服务账号的角色。

  5. 如果您的服务账号没有 Logging 代理所需的必要角色，请按照以下步骤添加创建服务账号部分所述的角色：

    1. 点击服务账号条目中的 修改。
    2. 点击添加其他角色以添加任何缺少的必要角色。
    3. 点击保存。

使用关联的服务账号进行授权

如需向具有关联的服务账号的 Compute Engine 虚拟机实例上安装的 Logging 代理进行授权，请执行以下操作：

  1. 确保您已验证虚拟机的访问权限范围。

  2. 尽可能向服务账号授予最小权限的 IAM 角色。 如需了解所需角色，请参阅本页面的创建服务账号部分。

  3. 关联服务账号到运行代理的虚拟机。

  4. 如果您尚未安装代理，请安装代理。如需了解如何安装代理，请参阅安装代理。

使用服务账号密钥进行授权

如需使用服务账号私钥向虚拟机实例上安装的 Logging 代理授权，请执行以下操作：

  1. 将服务账号密钥文件从本地系统转移到您的虚拟机实例：

    1. 创建环境变量以指向本地系统上的服务账号密钥文件。以下示例创建一个名为 CREDS 的变量：

      CREDS=~/Downloads/PROJECT-NAME-KEY-ID.json

    2. 完成下表中显示的步骤：

      Compute Engine

      1. 在 Google Cloud 控制台的导航面板中，选择 Compute Engine，然后选择虚拟机实例：

        前往虚拟机实例

        确定虚拟机的 INSTANCE_NAME 和 INSTANCE_ZONE。

      2. 在本地系统上，运行 Google Cloud CLI 命令以将密钥文件从本地系统复制到虚拟机实例：

        REMOTE_USER="$USER"
INSTANCE="INSTANCE_NAME"
ZONE="INSTANCE_ZONE"
gcloud compute scp "$CREDS" "$REMOTE_USER@$INSTANCE:~/temp.json" --zone "$ZONE"

      3. 在 Compute Engine 实例上，将服务账号密钥文件从临时位置移动到永久位置；对于 Linux，确保只有 root 可以读取服务账号密钥文件。

        以下是代理预期的密钥文件位置：

        • Linux 虚拟机：/etc/google/auth/application_default_credentials.json
        • Windows 虚拟机：C:\ProgramData\Google\Auth\application_default_credentials.json
        • Linux 和 Windows 虚拟机：您存储在环境变量 GOOGLE_APPLICATION_CREDENTIALS 中的任何位置，该位置必须对代理的进程可见。如需了解配置信息，请参阅设置 GOOGLE_APPLICATION_CREDENTIALS。

        例如，在 Linux 上，您可以运行以下脚本，将服务账号密钥文件移动到默认位置，然后设置适当的权限：

        CREDENTIALS_FILE_LOCATION="/etc/google/auth/application_default_credentials.json"
sudo mkdir -p /etc/google/auth
sudo mv "$HOME/temp.json" "$CREDENTIALS_FILE_LOCATION"
sudo chown root:root "$CREDENTIALS_FILE_LOCATION"
sudo chmod 0400 "$CREDENTIALS_FILE_LOCATION"

      Amazon EC2

      1. 对于您的虚拟机，请确定 YOUR-INSTANCE'S-ID 和 YOUR-INSTANCE'S-AWS-REGION。

      2. 在本地系统上，使用 scp 将服务账号密钥文件从本地系统复制到虚拟机实例：

        KEY="YOUR-SSH-KEY-PAIR-FILE"
INSTANCE="ec2-YOUR-INSTANCE'S-ID.YOUR-INSTANCE'S-AWS-REGION.compute.amazonaws.com"
# The remote user depends on the installed OS: ec2-user, ubuntu, root, etc.
REMOTE_USER="EC2-USER"
scp -i "$KEY" "$CREDS" "$REMOTE_USER@$INSTANCE:~/temp.json"

        INSTANCE 环境变量的值假定 EC2 实例不在 us-east-1 区域中。如需了解如何在实例位于 us-east-1 区域时定义 INSTANCE 变量，请参阅 Amazon 定义的命名规则。

      3. 在 EC2 实例上，将服务账号密钥文件从临时位置移动到以下位置之一；对于 Linux，确保只有 root 可以读取服务账号密钥文件。

        以下是代理预期的密钥文件位置：

        • Linux 虚拟机：/etc/google/auth/application_default_credentials.json

        • Windows 虚拟机：C:\ProgramData\Google\Auth\application_default_credentials.json

        • Linux 和 Windows 虚拟机：您存储在环境变量 GOOGLE_APPLICATION_CREDENTIALS 中的任何位置，该位置必须对代理的进程可见。如需了解配置信息，请参阅设置 GOOGLE_APPLICATION_CREDENTIALS。

        例如，在 Linux 上，您可以运行以下脚本，将服务账号密钥文件移动到默认位置，然后设置适当的权限：

        CREDENTIALS_FILE_LOCATION="/etc/google/auth/application_default_credentials.json"
sudo mkdir -p /etc/google/auth
sudo mv "$HOME/temp.json" "$CREDENTIALS_FILE_LOCATION"
sudo chown root:root "$CREDENTIALS_FILE_LOCATION"
sudo chmod 0400 "$CREDENTIALS_FILE_LOCATION"

  2. 虚拟机实例现在有了代理需要的服务账号密钥文件。接下来，请安装或重启代理：

设置 GOOGLE_APPLICATION_CREDENTIALS

本部分介绍如何设置环境变量 GOOGLE_APPLICATION_CREDENTIALS，以使其对代理的进程可见。

Linux

  1. 修改以下配置文件，或创建该文件（如果该文件尚不存在）：

    /etc/default/google-fluentd

  2. 将以下内容添加到配置文件中：

    GOOGLE_APPLICATION_CREDENTIALS=PATH_TO_CREDENTIAL_FILE

  3. 通过在虚拟机实例上运行以下命令来重启该代理。

    sudo service google-fluentd restart

Windows

  1. 在 PowerShell 中，以管理员身份运行以下命令，以设置 Ops Agent 要使用的 GOOGLE_APPLICATION_CREDENTIALS 系统环境变量：

    [Environment]::SetEnvironmentVariable("GOOGLE_APPLICATION_CREDENTIALS", "PATH_TO_CREDENTIAL_FILE", "Machine")

  2. 通过在虚拟机实例上运行以下命令来重启该代理。

    Restart-Service -Name StackdriverLogging