localenv 开发人员指南

此集合中的 “localenv” 角色会设置运行集成测试所需的外部依赖项。其理念是为贡献者提供一种预打包的方式，以一致且可重复的方式设置其本地环境。

注意

本指南正在进行中，并且非常缺乏细节。目前，如果您正在考虑新的 localenv，最好在存储库中打开一个 issue 来讨论它。查看 setup_localenv_docker 也应该会有所帮助，因为它是目前最完整的。

所需的外部依赖项

HashiCorp Vault

集成测试需要一个 Vault 服务器。建议使用 Vault 开发服务器模式，因为它是启动服务器最简单快捷的方式。

出于我们的目的，必须使用未加密（纯 HTTP）的监听器，因为大多数测试都期望以这种方式连接。

要运行专门处理 TLS/HTTPS 访问的测试，您必须使用启用 TLS 的监听器启动 Vault 服务器。必须提供 TLS 地址：端口和 CA 证书（如果自签名，则为证书本身）。

需要 Vault 服务器的根令牌，因为集成测试会更改 Vault 的配置，并希望拥有该令牌才能这样做。可以在启动时让 Vault 生成令牌，然后再检索它，但最简单的方法可能是预先生成一个令牌，并通过 -dev-root-token-id 选项或 VAULT_DEV_ROOT_TOKEN_ID 环境变量将其传递到 Vault（请参阅 开发选项）。

相关的 integration_config.yml 变量

变量

示例

描述

vault_test_server_http

http://myvault:8200

您的 Vault 测试服务器的完整 HTTP URL。

vault_test_server_https

https://myvault:8300

您的 Vault 测试服务器的完整 HTTPS URL。

vault_dev_root_token_id

3ee9a1f7-f115-4f7c-90a3-d3c73361bcb5

用于向 Vault 进行身份验证的根令牌。

vault_version

1.7.3

正在使用的 Vault 版本（通常由 localenv 写入，因此手动设置的值不会在任何地方使用）。

vault_cert_content

-----BEGIN CERTIFICATE-----<snip>

为 Vault 的 TLS 监听器签名的 CA 的公共证书（如果自签名，则为证书本身）。

代理服务器

代理服务器用于测试代理连接选项。

理论上，任何支持 http/s 目标的代理都可以用于此目的，但建议使用 tinyproxy，因为它很小巧，易于配置和运行，并且可以在软件包管理器和容器中使用。

相关的 integration_config.yml 变量

变量

示例

描述

vault_proxy_server

http://proxy:8080

您的代理服务器的完整 HTTP URL。

MMock 服务器

MMock（Monster Mock 的缩写） 是一个 HTTP 服务器，旨在模拟 HTTP 响应。它也可以透明地代理到真实的服务器。我们使用它来代理我们的测试 Vault 服务器，同时拦截对 Vault 的某些 API 调用并返回模拟的响应。

这对于在我们的 CI 环境中更难设置的 Vault 集成很有用。

例如，我们将此用于测试 aws_iam 身份验证方法，因为我们没有可以从 GitHub CI 使用、配置和连接的 AWS 帐户。

对于这些集成测试，所有 Vault 交互都定向到 MMock 而不是直接定向到 Vault，并且我们预先配置 MMock 以模拟真实 Vault 服务器的成功和失败响应的方式来响应相关的调用。

相关的 integration_config.yml 变量

变量

示例

描述

vault_mmock_server_http

http://mmock:8900

MMock 服务器的完整 HTTP URL。

localenv 角色约定

  • 使用 files/.output 来保存生成的工件。

  • 任何生成的内容都应在 .gitignore 文件中；反之，任何不在 .gitignore 文件中的内容都不应被此过程覆盖或修改。也就是说，由此不应产生任何 git 状态的更改。

  • 考虑提供一个 setup.sh 脚本，以避免手动运行 ansible- 命令。它理想情况下应在当前工作目录无关的情况下正确运行。

  • 生成一个可用的 integration_config.yml 文件，使其可以使用 localenv 的结果。在角色输出中生成它，而不是在角色外部生成。将其复制到正确的位置，但不要覆盖现有的文件。

  • 如果角色有外部依赖项，请尝试将这些依赖项编入文件，以便由正确的工具使用，例如用于 ansible-galaxy 的 requirements.yml 等。

  • localenv 角色旨在 在 ansible-test 环境之外运行，但它们可以（重）用其他角色。