你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

安装 Azure 运营商见解引入代理并将其配置为上传数据

按照本文进行操作时,可以在网络中的虚拟机 (VM) 上设置 Azure 运营商见解引入代理,并将其配置为将数据上传到数据产品。 此引入代理支持上传以下内容:

  • 存储在 SFTP 服务器上的文件。
  • Affirmed Mobile Content Cloud (MCC) 事件数据记录 (EDR) 数据流。

有关引入代理的概述,请参阅引入代理概述

先决条件

从数据产品的文档中获取以下内容:

  • 计划在其中安装 VM 代理的 VM 的规格。
  • 引入代理的示例配置。

VM 安全建议

用于引入代理的 VM 应按照安全性最佳做法进行设置。 建议执行以下操作:

网络

使用 Azure VM 时:

  • 提供 VM 专用 IP 地址。
  • 配置网络安全组 (NSG),仅允许在用于运行代理和维护 VM 的端口上有网络流量。
  • 除此之外,网络配置取决于是否对数据产品设置了受限访问(是否使用服务终结点访问数据产品的输入存储帐户)。 某些网络配置可能会产生额外的成本,例如 VM 与数据产品输入存储帐户之间的 Azure 虚拟网络。

使用本地 VM 时:

  • 配置防火墙,仅允许在用于运行代理和维护 VM 的端口上有网络流量。

磁盘加密

确保已启用 Azure 磁盘加密(这是创建 VM 时的默认行为)。

OS 版本

  • 保持最新的 OS 版本,以避免已知漏洞。
  • 将 VM 配置为定期检查,以确认缺少的系统更新。

Access

将 VM 的访问权限限制为最少的用户集。 在 VM 上配置审核日志记录(例如,使用 Linux 审核包),以记录登录用户执行的登录尝试和操作。

建议限制以下内容:

  • 对 VM 的管理员访问权限(例如,停止/启动/安装引入代理)。
  • 对存储日志的目录的访问权限:/var/log/az-aoi-ingestion/
  • 对此过程中创建的服务主体的托管标识或证书和私钥的访问权限。
  • 对此过程中在 VM 上创建的机密目录的访问权限。

Microsoft Defender for Cloud

使用 Azure VM 时,还需遵循 Microsoft Defender for Cloud 的所有建议。 可以通过导航到 VM 并选择“安全性”,在门户中找到这些建议。

设置 Azure 身份验证

引入代理必须能够向数据产品创建的 Azure Key Vault 进行身份验证,以检索存储凭据。 身份验证方法可以是:

  • 具有证书凭据的服务主体。 如果引入代理在 Azure 外部(例如本地网络)运行,则必须使用此项。
  • 托管标识。 如果引入代理在 Azure VM 上运行,我们建议使用此方法。 它不需要处理任何凭据(与服务主体不同)。

重要

可能需要组织中的 Microsoft Entra 租户管理员来为你执行此设置。

使用托管标识进行身份验证

如果引入代理在 Azure 中运行,我们建议使用托管标识。 有关更多详细信息,请参阅托管标识概述

注意

Azure VM 上的引入代理支持系统分配的托管标识和用户分配的托管标识。 对于多个代理来说,用户分配的托管标识更简单,因为你可以为运行代理的所有 VM 向数据产品密钥保管库授权该标识。

  1. 创建或获取用户分配的托管标识,请按照管理用户分配的托管标识中的说明进行操作。 如果计划使用系统分配的托管标识,请不要创建用户分配的托管标识。
  2. 根据使用的托管标识类型,按照使用 Azure 门户为 VM 上的 Azure 资源配置托管标识中的说明操作。
  3. 记下托管标识的对象 ID。 这是 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 形式的 UUID,其中每个字符都是十六进制数字。

现在可以授予数据产品密钥保管库的权限

使用服务主体进行身份验证

如果引入代理在 Azure 外部(如本地网络)运行,则不能使用托管标识,而必须使用带有证书凭据的服务主体向数据产品密钥保管库进行身份验证。 每个代理还必须具有存储在虚拟机上的证书的副本。

创建服务主体

  1. 创建或获取 Microsoft Entra ID 服务主体。 请按照在门户中创建 Microsoft Entra 应用和服务主体中的详细说明进行操作。 将“重定向 URI”字段留空。
  2. 记下应用程序(客户端)ID 和 Microsoft Entra Directory(租户)ID(这些 ID 是 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 形式的 UUID,其中每个字符都是十六进制数字)。

为服务主体准备证书

引入代理仅支持服务主体的证书凭据。 可以自行决定是为每个 VM 使用相同的证书和密钥,还是为每个 VM 使用唯一的证书和密钥。 每个 VM 使用单独的证书可以增强安全性,并且密钥泄露或证书过期的影响更小。 但是,这种方法需要更多维护并增加操作复杂性。

  1. 获取一个或多个证书。 强烈建议使用来自证书颁发机构的可信证书。 可以从 Azure Key Vault 生成证书:请参阅使用 Azure 门户从 Key Vault 中设置和检索证书。 这样就可以配置过期警报,并让你有时间重新生成新证书并在过期之前将其应用到引入代理中。 证书过期后,代理将无法进行 Azure 身份验证,并且不会再上传数据。 有关此方法的详细信息,请参阅续订 Azure 密钥保管库证书。 如果选择使用 Azure Key Vault:
    • 此 Azure Key Vault 必须是与数据产品密钥保管库不同的实例,可以是你已控制的实例,也可以是一个新实例。
    • 将证书添加到 Key Vault 需要 Azure Key Vault 上的“Key Vault 证书主管”角色。 有关如何在 Azure 中分配角色的详细信息,请参阅使用 Azure 门户分配 Azure 角色
  2. 按照在门户中创建 Microsoft Entra 应用和服务主体中的说明,将证书作为凭据添加到服务主体。
  3. 确保证书以 PKCS#12 (P12) 格式提供,并且不受密码保护。
    • 如果证书存储在 Azure Key Vault 中,请下载 PFX 格式的证书。 PFX 与 P12 相同。
    • 在 Linux 上,可以使用 OpenSSL 转换证书和私钥。 当系统提示输入导出密码时,请按 Enter 以提供空密码。 然后,可以按照步骤 1 中所述,将其存储在 Azure Key Vault 中。
    openssl pkcs12 -nodes -export -in <certificate.pem> -inkey <key.pem> -out <certificate.p12>
    

重要

P12 文件不得使用密码保护。

  1. 验证 P12 文件。 这将显示有关 P12 文件的信息,包括证书和私钥。

    openssl pkcs12 -nodes -in <certificate.p12> -info
    
  2. 确保 P12 文件是 base64 编码的。 在 Linux 上,可以使用 base64 命令对 P12 证书进行 base64 编码。

    base64 -w 0 <certificate.p12> > <base64-encoded-certificate.p12>
    

授予对数据产品密钥保管库的权限

  1. 查找保存输入存储帐户的存储凭据的 Azure 密钥保管库。 此 Key Vault 位于名为 <data-product-name>-HostedResources-<unique-id> 的资源组中。
  2. 向服务主体授予此密钥保管库上的“密钥保管库机密用户”角色。 需要 Azure 订阅的所有者级别权限。 有关如何在 Azure 中分配角色的详细信息,请参阅使用 Azure 门户分配 Azure 角色
  3. 设置密钥保管库的名称。

准备 SFTP 服务器

仅 SFTP 拉取源需要此部分。

在 SFTP 服务器上:

  1. 确保 VM 的端口 22/TCP 已打开。
  2. 在 SFTP 服务器上创建一个新用户或确定一个现有用户,引入代理应使用该用户连接到 SFTP 服务器。
  3. 确定引入代理用于连接到 SFTP 服务器的身份验证方法。 该代理支持:
    • 密码验证
    • SSH 密钥身份验证
  4. 将 SFTP 服务器配置为在一段时间(保持期)后删除文件。 确保保持期足够长,能让代理在 SFTP 服务器删除文件之前处理完文件。 示例配置文件包含每五分钟检查一次新文件的配置。

重要

SFTP 服务器必须在适当的保持期后删除文件,以保证不会耗尽磁盘空间。 引入代理不会自动移除文件。

较短的保持时间可减少磁盘使用量、提高代理的速度并降低重复上传的风险。 但是,如果代理无法检索数据或上传到 Azure 运营商见解,那么较短的保持期会增加数据丢失的风险。

准备 VM

对要安装代理的每个 VM 重复以下步骤。

  1. 确保你有向 VM 开放的 SSH 会话,并且具有 sudo 权限。

  2. 在 VM 上安装 systemd、logrotate 和 zip(如果尚未安装)。 例如:

    sudo dnf install systemd logrotate zip
    
  3. 如果使用服务主体,请将 base64 编码的 P12 证书(在准备证书步骤中创建)复制到 VM 中引入代理可访问的位置。

  4. 根据引入源的类型配置代理 VM。

    1. 验证 VM 已打开以下端口。 这些端口必须在云网络安全组和 VM 本身上运行的任何防火墙(例如 firewalld 或iptables)中打开。
      • 向 Azure 出站的端口 443/TCP
      • 向 SFTP 服务器出站的端口 22/TCP
    2. 创建用于存储代理机密的目录。 我们将此目录称为机密目录。 记下其路径。
    3. 在机密目录中创建一个文件,其中包含 SFTP 服务器的密码或 SSH 私钥。
      • 该文件不得有文件扩展名。
      • 为此文件选择适当的名称,并记下以备后用。 此名称在代理配置中引用。
      • 该文件必须仅包含机密值(密码或 SSH 密钥),不含额外的空格。
    4. 如果使用有密码的 SSH 密钥进行身份验证,请按照同一种方法另行创建一个包含密码的单独文件。
    5. 确保 SFTP 服务器的 SSH 公钥列在位于 /etc/ssh/ssh_known_hosts 的 VM 全局 known_hosts 文件中

    提示

    使用 Linux 命令 ssh-keyscan 手动将服务器的 SSH 公钥添加到 VM 的 known_hosts 文件中。 例如 ssh-keyscan -H <server-ip> | sudo tee -a /etc/ssh/ssh_known_hosts

确保 VM 能够解析 Microsoft 主机名

检查 VM 是否可以将公共主机名解析为 IP 地址。 例如,打开 SSH 会话并使用 dig login.microsoftonline.com 来检查 VM 是否可以将 login.microsoftonline.com 解析为 IP 地址。

如果 VM 无法使用 DNS 将公共 Microsoft 主机名解析为 IP 地址,则将所需的主机名映射到 IP 地址。 完成配置后,返回到此过程。

安装代理软件

代理软件包托管在“Microsoft 产品的 Linux 软件存储库”上,网址为 https://packages.microsoft.com

引入代理包的名称未 az-aoi-ingestion

要从软件存储库下载并安装包,请按照如何使用 Linux 存储库安装 Microsoft 软件包中针对你的 VM Linux 发行版的相关步骤进行操作。

例如,如果要在运行 Red Hat Enterprise Linux (RHEL) 8 的 VM 上进行安装,请按照基于 Red Hat 的 Linux 发行版标题下的说明进行操作,并替换以下参数:

  • distribution:rhel
  • version:8
  • package-name:az-aoi-ingestion

配置代理软件

所需的配置与源的类型和数据产品相关。 确保你有权访问数据产品的文档以查看所需的值。 例如:

  1. 通过 SSH 连接到 VM。

  2. 更改为配置目录。

    cd /etc/az-aoi-ingestion
    
  3. 创建默认配置文件的副本。

    sudo cp example_config.yaml config.yaml
    
  4. agent_id 字段设置为代理实例的唯一标识符,例如 london-sftp-1。 此名称将在运营商见解中成为所有代理引入数据的可搜索元数据。 必须正确地对保留的 URL 字符进行转义。

  5. 配置 secret_providers 部分。

    SFTP 源需要两种类型的机密提供程序。

    • key_vault 类型的机密提供程序,其中包含连接到数据产品的 Azure Key Vault 以及允许连接到数据产品的输入存储帐户所需的详细信息。
    • file_system 类型的机密提供程序,它指定 VM 上的一个目录,用于存储用于连接到 SFTP 服务器的凭据。
    1. 对于类型为 key_vault 且名称为 data_product_keyvault 的机密提供程序,设置以下字段。
    2. 对于类型为 file_system 且名称为 local_file_system 的机密提供程序,设置以下字段。
      • secrets_directory:代理 VM 上机密目录的绝对路径,该目录是在准备 VM 步骤中创建的。

    可以添加更多机密提供程序(例如,如果要上传到多个数据产品),或更改默认机密提供程序的名称。

  6. 使用示例配置和数据产品的文档来配置 pipelines 部分。 每个 pipeline 都有三个配置部分。

    • id。 ID 用于标识管道,不得与此引入代理的任何其他管道 ID 相同。 必须对任何 URL 保留字符进行百分比编码。 有关任何建议,请参阅数据产品的文档。

    • source。 源配置用于控制引入哪些文件。 可以配置多个源。

      删除示例中除包含 sftp_pull 源配置的 contoso-logs 示例之外的所有管道。

      更新示例以满足你的要求。 以下字段是每个源的必填字段。

      • host:SFTP 服务器的主机名或 IP 地址。
      • filtering.base_path:SFTP 服务器上的文件夹路径,文件将从中上传到 Azure 运营商见解。
      • known_hosts_file:VM 上全局 known_hosts 文件的路径,位于 /etc/ssh/ssh_known_hosts。 此文件应包含 SFTP 主机服务器的公共 SSH 密钥,如 准备 VM中所述。
      • user:代理应在连接时使用的 SFTP 服务器上的用户名。
      • 根据在准备 VM 中选择的身份验证方法,设置 passwordprivate_key
        • 对于密码验证,将 secret_name 设置为 secrets_directory 文件夹中包含密码的文件的名称。
        • 对于 SSH 密钥身份验证,将 key_secret 设置为 secrets_directory 文件夹中包含 SSH 密钥的文件的名称。 如果私钥使用密码进行保护,请将 passphrase_secret_name 设置为 secrets_directory 文件夹中包含该密码的文件的名称。

      有关其他字段的必需值或建议值,请参阅数据产品的文档。

      提示

      代理支持以下附加可选配置:

      • 指定 base_path 文件夹中将上传的文件模式(默认情况下将上传文件夹中的所有文件)。
      • 指定 base_path 文件夹中不应上传的文件模式。
      • 不上传 base_path 文件夹中文件的截止时间和日期。
      • 引入代理上传文件的频率(示例配置文件中提供的值对应每小时一次)。
      • 处置时间,即从最后一次修改文件时起到上传文件为止,代理等待的时间(示例配置文件中提供的值为 5 分钟)。

      有关这些配置选项的详细信息,请参阅 Azure 运营商见解引入代理的配置参考

    • sink。 接收器配置控制将数据上传到数据产品的输入存储帐户。

      • sas_token 部分中,将 secret_provider 设置为数据产品的相应 key_vault 机密提供程序,或使用默认 data_product_keyvault(如果之前使用过默认名称)。 secret_name 保持不变。
      • 有关其他参数所需值的信息,请参阅数据产品的文档。

        重要

        container_name 字段必须完全按照数据产品文档的指定进行设置。

启动代理软件

  1. 启动代理。
    sudo systemctl start az-aoi-ingestion
    
  2. 检查代理是否正在运行。
    sudo systemctl status az-aoi-ingestion
    
    1. 如果看到除 active (running) 之外的任何状态,请根据监视 Azure 运营商见解的引入代理并对其进行故障排除中所述查看日志,以了解错误。 某些配置可能不正确。
    2. 解决问题后,再次尝试启动代理。
    3. 如果问题仍然存在,请提交支持工单。
  3. 代理开始运行后,确保其在重启后自动启动。
    sudo systemctl enable az-aoi-ingestion.service
    

[可选] 配置日志收集以通过 Azure Monitor 进行访问

如果在 Azure VM 或通过 Azure Arc 连接的本地 VM 上运行引入代理,则可以使用 Azure Monitor 代理将引入代理日志发送到 Azure Monitor。 使用 Azure Monitor 访问日志比直接在 VM 上访问日志更简单。

若要收集引入代理日志,请遵循安装 Azure Monitor 代理并配置日志收集的 Azure Monitor 文档

  • 这些文档使用 Az PowerShell 模块创建日志表。 请先按照 Az PowerShell 模块安装文档进行操作。
    • 示例 $tableParams JSON 中的 YourOptionalColumn 部分对于引入代理是不必要的,可以移除。
  • 将数据源添加到数据收集规则时,请使用文件模式 /var/log/az-aoi-ingestion/stdout.log 添加 Custom Text Logs 源类型。
  • 添加数据收集规则后,可以通过 Log Analytics 工作区查询这些日志。 使用以下查询使其更易于使用:
    RawAgentLogs_CL
    | extend RawData = replace_regex(RawData, '\\x1b\\[\\d{1,4}m', '')  // Remove any color tags
    | parse RawData with TimeGenerated: datetime '  ' Level ' ' Message  // Parse the log lines into the TimeGenerated, Level and Message columns for easy filtering
    | order by TimeGenerated desc
    

    注意

    此查询不能用作数据源转换,因为 replace_regex 在数据源转换中不可用。

示例日志

[2m2024-04-30T17:16:00.000544Z[0m [32m INFO[0m [1msftp_pull[0m[1m{[0m[3mpipeline_id[0m[2m=[0m"test-files"[1m}[0m[2m:[0m[1mexecute_run[0m[1m{[0m[3mstart_time[0m[2m=[0m"2024-04-30 17:16:00.000524 UTC"[1m}[0m[2m:[0m [2maz_ingestion_sftp_pull_source::sftp::source[0m[2m:[0m Starting run with 'last checkpoint' timestamp: None
[2m2024-04-30T17:16:00.000689Z[0m [32m INFO[0m [1msftp_pull[0m[1m{[0m[3mpipeline_id[0m[2m=[0m"test-files"[1m}[0m[2m:[0m[1mexecute_run[0m[1m{[0m[3mstart_time[0m[2m=[0m"2024-04-30 17:16:00.000524 UTC"[1m}[0m[2m:[0m [2maz_ingestion_sftp_pull_source::sftp::source[0m[2m:[0m Starting Completion Handler task
[2m2024-04-30T17:16:00.073495Z[0m [32m INFO[0m [1msftp_pull[0m[1m{[0m[3mpipeline_id[0m[2m=[0m"test-files"[1m}[0m[2m:[0m[1mexecute_run[0m[1m{[0m[3mstart_time[0m[2m=[0m"2024-04-30 17:16:00.000524 UTC"[1m}[0m[2m:[0m [2maz_ingestion_sftp_pull_source::sftp::sftp_file_tree_explorer[0m[2m:[0m Start traversing files with base path "/"
[2m2024-04-30T17:16:00.086427Z[0m [32m INFO[0m [1msftp_pull[0m[1m{[0m[3mpipeline_id[0m[2m=[0m"test-files"[1m}[0m[2m:[0m[1mexecute_run[0m[1m{[0m[3mstart_time[0m[2m=[0m"2024-04-30 17:16:00.000524 UTC"[1m}[0m[2m:[0m [2maz_ingestion_sftp_pull_source::sftp::sftp_file_tree_explorer[0m[2m:[0m Finished traversing files
[2m2024-04-30T17:16:00.086698Z[0m [32m INFO[0m [1msftp_pull[0m[1m{[0m[3mpipeline_id[0m[2m=[0m"test-files"[1m}[0m[2m:[0m[1mexecute_run[0m[1m{[0m[3mstart_time[0m[2m=[0m"2024-04-30 17:16:00.000524 UTC"[1m}[0m[2m:[0m [2maz_ingestion_sftp_pull_source::sftp::source[0m[2m:[0m File explorer task is complete, with result Ok(())
[2m2024-04-30T17:16:00.086874Z[0m [32m INFO[0m [1msftp_pull[0m[1m{[0m[3mpipeline_id[0m[2m=[0m"test-files"[1m}[0m[2m:[0m[1mexecute_run[0m[1m{[0m[3mstart_time[0m[2m=[0m"2024-04-30 17:16:00.000524 UTC"[1m}[0m[2m:[0m [2maz_ingestion_sftp_pull_source::sftp::source[0m[2m:[0m Send files to sink task is complete
[2m2024-04-30T17:16:00.087041Z[0m [32m INFO[0m [1msftp_pull[0m[1m{[0m[3mpipeline_id[0m[2m=[0m"test-files"[1m}[0m[2m:[0m[1mexecute_run[0m[1m{[0m[3mstart_time[0m[2m=[0m"2024-04-30 17:16:00.000524 UTC"[1m}[0m[2m:[0m [2maz_ingestion_sftp_pull_source::sftp::source[0m[2m:[0m Processed all completion notifications for run
[2m2024-04-30T17:16:00.087221Z[0m [32m INFO[0m [1msftp_pull[0m[1m{[0m[3mpipeline_id[0m[2m=[0m"test-files"[1m}[0m[2m:[0m[1mexecute_run[0m[1m{[0m[3mstart_time[0m[2m=[0m"2024-04-30 17:16:00.000524 UTC"[1m}[0m[2m:[0m [2maz_ingestion_sftp_pull_source::sftp::source[0m[2m:[0m Run complete with no retryable errors - updating last checkpoint timestamp
[2m2024-04-30T17:16:00.087351Z[0m [32m INFO[0m [1msftp_pull[0m[1m{[0m[3mpipeline_id[0m[2m=[0m"test-files"[1m}[0m[2m:[0m[1mexecute_run[0m[1m{[0m[3mstart_time[0m[2m=[0m"2024-04-30 17:16:00.000524 UTC"[1m}[0m[2m:[0m [2maz_ingestion_sftp_pull_source::sftp::source[0m[2m:[0m Run lasted 0 minutes and 0 seconds with result: RunStats { successful_uploads: 0, retryable_errors: 0, non_retryable_errors: 0, blob_already_exists: 0 }
[2m2024-04-30T17:16:00.087421Z[0m [32m INFO[0m [1msftp_pull[0m[1m{[0m[3mpipeline_id[0m[2m=[0m"test-files"[1m}[0m[2m:[0m[1mexecute_run[0m[1m{[0m[3mstart_time[0m[2m=[0m"2024-04-30 17:16:00.000524 UTC"[1m}[0m[2m:[0m [2maz_ingestion_sftp_pull_source::sftp::file[0m[2m:[0m Closing 1 active SFTP connections
[2m2024-04-30T17:16:00.087966Z[0m [32m INFO[0m [1msftp_pull[0m[1m{[0m[3mpipeline_id[0m[2m=[0m"test-files"[1m}[0m[2m:[0m[1mexecute_run[0m[1m{[0m[3mstart_time[0m[2m=[0m"2024-04-30 17:16:00.000524 UTC"[1m}[0m[2m:[0m [2maz_ingestion_common::scheduler[0m[2m:[0m Run completed successfully. Update the 'last checkpoint' time to 2024-04-30T17:15:30.000543200Z
[2m2024-04-30T17:16:00.088122Z[0m [32m INFO[0m [1msftp_pull[0m[1m{[0m[3mpipeline_id[0m[2m=[0m"test-files"[1m}[0m[2m:[0m [2maz_ingestion_common::scheduler[0m[2m:[0m Schedule next run at 2024-04-30T17:17:00Z

了解如何: