跳到主要内容

ConfigData API

DeepSeek V3 中英对照 ConfigData API

Spring Boot 自 2.4 版本起提供了一个 ConfigData API，允许声明配置源并将其作为属性源导入。

Spring Cloud Vault 从 3.0 版本开始使用 ConfigData API 来将 Vault 的密钥后端挂载为属性源。在之前的版本中，使用的是 Bootstrap 上下文。ConfigData API 更加灵活，因为它允许指定导入哪些配置系统以及导入的顺序。

备注

你可以通过设置配置属性 spring.cloud.bootstrap.enabled=true 或包含依赖 org.springframework.cloud:spring-cloud-starter-bootstrap 来启用引导上下文。由于引导上下文仅在极少数情况下需要，因此我们建议使用 Config Data API 以获得更灵活的属性源排序。

ConfigData 位置​

您可以通过一个或多个从 Vault 实例化的 PropertySource 来挂载 Vault 配置。Spring Cloud Vault 支持两种配置位置：

  • vault:// (默认位置)

  • vault:///<context-path> (上下文相关位置)

使用默认位置会为所有启用的密钥后端挂载属性源。在没有进一步配置的情况下，Spring Cloud Vault 会在 /secret/${spring.application.name} 路径挂载键值后端。每个激活的配置文件会按照 /secret/${spring.application.name}/${profile} 的形式添加另一个上下文路径。向类路径添加更多模块，例如 spring-cloud-config-databases，会提供额外的密钥后端配置选项，这些选项在启用时会作为属性源挂载。

如果您想要控制从 Vault 挂载哪些上下文路径作为 PropertySource，您可以使用上下文位置 (vault:///my/context/path) 或配置一个 VaultConfigurer。

上下文位置需要单独指定并挂载。Spring Cloud Vault 将每个位置挂载为独立的 PropertySource。你可以将默认位置与上下文位置（或其他配置系统）混合使用，以控制属性源的顺序。这种方法特别有用，如果你想禁用默认的键值路径计算，并自行挂载每个键值后端。

spring.config.import: vault://first/context/path, vault://other/path, vault://

在 Spring Environment 中，属性名称必须是唯一的，以避免被覆盖。如果您在不同的上下文路径中使用相同的密钥名称，并且希望将这些密钥作为单独的属性公开，您可以通过在位置中添加 prefix 查询参数来区分它们。

示例 1. application.yml

spring.config.import: vault://my/path?prefix=foo., vault://my/other/path?prefix=bar.
secret: ${foo.secret}
other.secret: ${bar.secret}
备注

前缀会按原样添加到 Vault 返回的所有属性名称前。如果您希望键名在前缀和键名之间用点号分隔，请确保在前缀末尾添加一个点号。

有条件地启用/禁用 Vault 配置​

在某些情况下，可能需要在不使用 Vault 的情况下启动应用程序。您可以通过位置字符串指定 Vault 配置位置是可选的还是必需的（默认）：

  • optional:vault:// (默认位置)

  • optional:vault:///<context-path> (上下文相关位置)

如果通过 spring.cloud.vault.enabled=false 禁用了 Vault 支持，则在应用程序启动期间会跳过可选位置。

备注

无法找到的 Vault 上下文路径（HTTP 状态 404）将被跳过，无论配置位置是否标记为可选。Vault 客户端快速失败 允许在启动时因 HTTP 状态 404 导致 Vault 上下文路径无法找到而失败。

基础设施自定义​

Spring Cloud Vault 需要基础设施类来与 Vault 交互。当不使用 ConfigData API 时（意味着您没有指定 spring.config.import=vault:// 或上下文相关的 Vault 路径），Spring Cloud Vault 会通过 VaultAutoConfiguration 和 VaultReactiveAutoConfiguration 来定义其 Bean。Spring Boot 在 Spring 上下文可用之前会引导应用程序。因此，VaultConfigDataLoader 会自行注册 Bean，以便稍后将这些 Bean 传播到应用程序上下文中。

你可以通过使用 Bootstrapper API 注册自定义实例来定制 Spring Cloud Vault 使用的基础设施：

ClientOptions options = new ClientOptions();
SslConfiguration sslConfiguration = SslConfiguration.unconfigured();
HttpClientBuilder builder = HttpComponents.getHttpClientBuilder(options, sslConfiguration);

InstanceSupplier<ClientFactoryWrapper> supplier = context ->
new ClientFactoryWrapper(new HttpComponentsClientHttpRequestFactory(builder.build()));

SpringApplication application = new SpringApplication(MyApplication.class);
application.addBootstrapRegistryInitializer(registry -> registry.register(ClientFactoryWrapper.class, supplier));
InstanceSupplier<RestTemplateBuilder> supplier = context -> {

	return RestTemplateBuilder
			.builder()
			.requestFactory(context.get(ClientFactoryWrapper.class).getClientHttpRequestFactory())
			.defaultHeader("X-Vault-Namespace", "my-namespace");
};

SpringApplication application = new SpringApplication(MyApplication.class);
application.addBootstrapRegistryInitializer(registry -> registry.register(RestTemplateBuilder.class, supplier));

另请参阅自定义要作为 PropertySource 公开的密钥后端以及 VaultConfigDataLoader 的源代码以了解自定义钩子。