Property Sources

Vault 可以用许多不同的方式。一个特定的用例是使用 Vault 来存储加密属性。Spring Vault 支持 Vault 作为属性源，以便使用 Spring’s {spring-framework-docs}core.html#beans-property-source-abstraction[属性源抽象] 获取配置属性。

Vault can be used in many different ways. One specific use-case is using Vault to store encrypted properties. Spring Vault supports Vault as property source to obtain configuration properties using Spring’s {spring-framework-docs}core.html#beans-property-source-abstraction[PropertySource abstraction].

您可以在其他属性源中引用存储在 Vault 中的属性，或使用 @Value(…) 进行值注入。在引导需要存储在 Vault 内的数据的 bean 时，需要特别注意。必须在该时间初始化 VaultPropertySource 以从 Vault 检索属性。

You can reference properties stored inside Vault in other property sources or use value injection with @Value(…). Special attention is required when bootstrapping beans that require data stored inside of Vault. A VaultPropertySource must be initialized at that time to retrieve properties from Vault.

Spring Boot/Spring Cloud 用户可以受益于 Spring Cloud Vault 的配置集成，该集成在应用程序启动期间初始化各种属性源。

Spring Boot/Spring Cloud users can benefit from Spring Cloud Vault's configuration integration that initializes various property sources during application startup.

Registering VaultPropertySource

Spring Vault 提供 VaultPropertySource，可与 Vault 一起使用来获取属性。它使用嵌套 data 元素来公开存储在 Vault 中的加密属性。

Spring Vault provides a VaultPropertySource to be used with Vault to obtain properties. It uses the nested data element to expose properties stored and encrypted in Vault.

ConfigurableApplicationContext ctx = new GenericApplicationContext();
MutablePropertySources sources = ctx.getEnvironment().getPropertySources();
sources.addFirst(new VaultPropertySource(vaultTemplate, "secret/my-application"));

在上述代码中，已将 VaultPropertySource 添加到搜索中，并具有最高优先级。如果它包含“foo”属性，将在检测到任何其他 PropertySource 中的任何 foo 属性之前检测到它并返回它。MutablePropertySources 公开许多方法，允许精确地操作属性源集。

In the code above, VaultPropertySource has been added with highest precedence in the search. If it contains a ´foo` property, it will be detected and returned ahead of any foo property in any other PropertySource. MutablePropertySources exposes a number of methods that allow for precise manipulation of the set of property sources.

@VaultPropertySource

@VaultPropertySource 注释提供了一种方便且具有声明性的机制，用于向 Spring 的 Environment 中添加 PropertySource，以与 @Configuration 类结合使用。

The @VaultPropertySource annotation provides a convenient and declarative mechanism for adding a PropertySource to Spring’s Environment to be used in conjunction with @Configuration classes.

@VaultPropertySource 采用 secret/my-application 等 Vault 路径，并在 PropertySource 中公开存储在节点中的数据。@VaultPropertySource 支持为与租期关联的秘密（例如，mysql 后端的凭据）续约租期，并在终端租期到期后对凭据进行轮换。默认情况下，禁用续约租期。

@VaultPropertySource takes a Vault path such as secret/my-application and exposes the data stored at the node in a PropertySource. @VaultPropertySource supports lease renewal for secrets associated with a lease (i. e. credentials from the mysql backend) and credential rotation upon terminal lease expiration. Lease renewal is disabled by default.

Example 1. Properties stored in Vault
{
  // …

  "data": {
    "database": {
      "password": ...
    },
    "user.name": ...,
  }

  // …
}
Example 2. Declaring a @VaultPropertySource
@Configuration
@VaultPropertySource("secret/my-application")
public class AppConfig {

    @Autowired Environment env;

    @Bean
    public TestBean testBean() {
        TestBean testBean = new TestBean();
        testBean.setUser(env.getProperty("user.name"));
        testBean.setPassword(env.getProperty("database.password"));
        return testBean;
    }
}
Example 3. Declaring a @VaultPropertySource with credential rotation and prefix
@Configuration
@VaultPropertySource(value = "aws/creds/s3-access",
                     propertyNamePrefix = "aws.",
                     renewal = Renewal.ROTATE)
public class AppConfig {
  // provides aws.access_key and aws.secret_key properties
}

从 generic 秘密后端获取的机密与 TTL (refresh_interval) 关联，但与租约 ID 无关。Spring Vault 的 PropertySource 在达到其 TTL 时轮换通用机密。

Secrets obtained from generic secret backends are associated with a TTL (refresh_interval) but not a lease Id. Spring Vault’s PropertySource rotates generic secrets when reaching its TTL.

您可以使用 @VaultPropertySource 从版本化 Key-Value 后端获取最新的机密版本。请确保路径中不包含 data/ 段。

You can use @VaultPropertySource to obtain the newest secret version from the versioned Key-Value backend. Make sure to not include the data/ segment in the path.

已在 @VaultPropertySource 路径中存在的任何 ${…​} 占位符都使用已针对环境注册的属性源集进行解析，如下例所示：

Any ${…​} placeholders present in a @VaultPropertySource path are resolved against the set of property sources already registered against the environment, as the following example shows:

Example 4. Declaring a @VaultPropertySource path using placeholders
@Configuration
@VaultPropertySource(value = "aws/creds/${my.placeholder:fallback/value}",
                     propertyNamePrefix = "aws.",
                     renewal = Renewal.ROTATE)
public class AppConfig {
}

假设 my.placeholder 位于已注册的某个属性源中（例如，系统属性或环境变量），则占位符将解析为相应的值。如果没有，则 fallback/value 用作默认值。如果未指定默认值且无法解析属性，则会引发 IllegalArgumentException。

Assuming that my.placeholder is present in one of the property sources already registered (for example, system properties or environment variables), the placeholder is resolved to the corresponding value. If not, then fallback/value is used as a default. If no default is specified and a property cannot be resolved, an IllegalArgumentException is thrown.

在某些情况下，使用 @VaultPropertySource 注解时，严格控制属性源顺序可能不可行或不切实际。例如，如果上面的 @Configuration 类是通过组件扫描注册的，那么顺序就很难预测。在这种情况（如果覆盖很重要）下，建议用户退回到使用编程属性源 API。请参阅 ConfigurableEnvironment 和 MutablePropertySources 以了解更多详情。

In certain situations, it may not be possible or practical to tightly control property source ordering when using @VaultPropertySource annotations. For example, if the @Configuration classes above were registered via component-scanning, the ordering is difficult to predict. In such cases - and if overriding is important - it is recommended that the user fall back to using the programmatic PropertySource API. See ConfigurableEnvironment and MutablePropertySources for details.