Service Registry Configuration

您可以使用 DiscoveryClient（例如来自 Spring Cloud Consul）通过设置 spring.cloud.vault.discovery.enabled=true（默认 false）来找到 Vault 服务器。最终结果是您的应用程序需要一个 application.yml（或一个环境变量）带有适当的发现配置。这样做的好处是只要发现服务是一个固定点，Vault 就可以更改其坐标。默认服务 ID 是 vault，但您可以使用`spring.cloud.vault.discovery.serviceId`在客户端上更改它。

You can use a DiscoveryClient (such as from Spring Cloud Consul) to locate a Vault server by setting spring.cloud.vault.discovery.enabled=true (default false). The net result of that is that your apps need a application.yml (or an environment variable) with the appropriate discovery configuration. The benefit is that the Vault can change its co-ordinates, as long as the discovery service is a fixed point. The default service id is vault but you can change that on the client with spring.cloud.vault.discovery.serviceId.

所有发现客户端实现都支持某种元数据映射（例如，对于 Eureka，我们有 eureka.instance.metadataMap）。服务的某些附加属性可能需要在其服务注册元数据中进行配置，以便客户端可以正常连接。不提供传输层安全性详细信息的服务注册表需要提供一个 scheme 元数据条目，将其设置为 https 或 http。如果未配置方案并且服务未公开为安全服务，则配置默认为 spring.cloud.vault.scheme，在未设置时为 https。

The discovery client implementations all support some kind of metadata map (e.g. for Eureka we have eureka.instance.metadataMap). Some additional properties of the service may need to be configured in its service registration metadata so that clients can connect correctly. Service registries that do not provide details about transport layer security need to provide a scheme metadata entry to be set either to https or http. If no scheme is configured and the service is not exposed as secure service, then configuration defaults to spring.cloud.vault.scheme which is https when it’s not set.

spring.cloud.vault.discovery:
    enabled: true
    service-id: my-vault-service

Vault Client Fail Fast

在某些情况下，如果无法连接到 Vault 服务器，可能需要让服务的启动失败。如果是这种期望的行为，请设置引导配置属性`spring.cloud.vault.fail-fast=true`，客户端将停止并引发异常。

In some cases, it may be desirable to fail startup of a service if it cannot connect to the Vault Server. If this is the desired behavior, set the bootstrap configuration property spring.cloud.vault.fail-fast=true and the client will halt with an Exception.

spring.cloud.vault:
    fail-fast: true

Vault Enterprise Namespace Support

Vault Enterprise 可以使用命名空间将多个 Vault 隔离在单个 Vault 服务器上。通过设置`spring.cloud.vault.namespace=…`配置命名空间可以在使用 Vault `RestTemplate`或 `WebClient`时对每个传出 HTTP 请求启用`X-Vault-Namespace`标题。

Vault Enterprise allows using namespaces to isolate multiple Vaults on a single Vault server. Configuring a namespace by setting spring.cloud.vault.namespace=… enables the namespace header X-Vault-Namespace on every outgoing HTTP request when using the Vault RestTemplate or WebClient.

请注意，此功能不受 Vault 社区版支持，并且不会对 Vault 操作产生任何影响。

Please note that this feature is not supported by Vault Community edition and has no effect on Vault operations.

spring.cloud.vault:
    namespace: my-namespace

另请参见： Vault Enterprise: Namespaces

See also: Vault Enterprise: Namespaces

Vault Client SSL configuration

可以通过设置各种属性来以声明方式配置 SSL。您可以设置 `javax.net.ssl.trustStore`以配置全 JVM SSL 设置，也可以设置`spring.cloud.vault.ssl.trust-store`仅为 Spring Cloud Vault Config 设置 SSL 设置。

SSL can be configured declaratively by setting various properties. You can set either javax.net.ssl.trustStore to configure JVM-wide SSL settings or spring.cloud.vault.ssl.trust-store to set SSL settings only for Spring Cloud Vault Config.

spring.cloud.vault:
    ssl:
        trust-store: classpath:keystore.jks
        trust-store-password: changeit
        trust-store-type: JKS
        enabled-protocols: TLSv1.2,TLSv1.3
        enabled-cipher-suites: TLS_AES_128_GCM_SHA256

  • trust-store sets the resource for the trust-store. SSL-secured Vault communication will validate the Vault SSL certificate with the specified trust-store.

  • trust-store-password sets the trust-store password

  • trust-store-type sets the trust-store type. Supported values are all supported KeyStore types including PEM.

  • enabled-protocols sets the list of enabled SSL/TLS protocols (since 3.0.2).

  • enabled-cipher-suites sets the list of enabled SSL/TLS cipher suites (since 3.0.2).

请注意，配置 `spring.cloud.vault.ssl.*`仅当 Apache Http Components 或 okhttp 客户端位于您的类路径中时才能应用。

Please note that configuring spring.cloud.vault.ssl.* can be only applied when either Apache Http Components or the OkHttp client is on your class-path.

Lease lifecycle management (renewal and revocation)

对于每个机密，Vault 都会创建一个租赁：包含时段、可续期性和更多信息等数据的元数据。

With every secret, Vault creates a lease: metadata containing information such as a time duration, renewability, and more.

Vault 承诺数据在给定的期限内或生存时间 (TTL) 内有效。一旦租赁期满，Vault 就可以撤销数据，并且机密的使用者将不再确定它是否有效。

Vault promises that the data will be valid for the given duration, or Time To Live (TTL). Once the lease is expired, Vault can revoke the data, and the consumer of the secret can no longer be certain that it is valid.

Spring Cloud Vault 在创建登录令牌和机密之外维护租赁生命周期。也就是说，与租赁关联的登录令牌和机密计划在租赁到期之前续订，直至最终到期。应用程序关闭将撤销已获得的登录令牌和可续期租赁。

Spring Cloud Vault maintains a lease lifecycle beyond the creation of login tokens and secrets. That said, login tokens and secrets associated with a lease are scheduled for renewal just before the lease expires until terminal expiry. Application shutdown revokes obtained login tokens and renewable leases.

机密服务和数据库后端（如 MongoDB 或 MySQL）通常会生成可续期租赁，因此在应用程序关闭时会禁用生成的证书。

Secret service and database backends (such as MongoDB or MySQL) usually generate a renewable lease so generated credentials will be disabled on application shutdown.

静态标记不会被更新或撤销。

Static tokens are not renewed or revoked.

租赁续订和吊销默认情况下处于启用状态，可以通过设置 `spring.cloud.vault.config.lifecycle.enabled`为 `false`来禁用。不建议这样做，因为租赁可能会过期，并且 Spring Cloud Vault 无法再使用生成的证书访问 Vault 或服务，且有效的证书在应用程序关闭后仍处于活动状态。

Lease renewal and revocation is enabled by default and can be disabled by setting spring.cloud.vault.config.lifecycle.enabled to false. This is not recommended as leases can expire and Spring Cloud Vault cannot longer access Vault or services using generated credentials and valid credentials remain active after application shutdown.

spring.cloud.vault:
    config.lifecycle:
    	enabled: true
    	min-renewal: 10s
    	expiry-threshold: 1m
    	lease-endpoints: Legacy

  • enabled controls whether leases associated with secrets are considered to be renewed and expired secrets are rotated. Enabled by default.

  • min-renewal sets the duration that is at least required before renewing a lease. This setting prevents renewals from happening too often.

  • expiry-threshold sets the expiry threshold. A lease is renewed the configured period of time before it expires.

  • lease-endpoints sets the endpoints for renew and revoke. Legacy for vault versions before 0.8 and SysLeases for later.

  • lease-strategy sets the LeaseStrategy (DropOnError, RetainOnError, RetainOnIoError) to control error handling on lease renewal.

另请参见： Vault Documentation: Lease, Renew, and Revoke

See also: Vault Documentation: Lease, Renew, and Revoke

Session token lifecycle management (renewal, re-login and revocation)

Vault 会话令牌（也称为`LoginToken`）与租赁非常相似，因为它有 TTL、最大 TTL，并且可能会过期。一旦登录令牌过期，就无法再使用它与 Vault 交互。因此，Spring Vault 附带了一个用于命令式和响应式用途的`SessionManager` API。

A Vault session token (also referred to as LoginToken) is quite similar to a lease as it has a TTL, max TTL, and may expire. Once a login token expires, it cannot be used anymore to interact with Vault. Therefore, Spring Vault ships with a SessionManager API for imperative and reactive use.

Spring Cloud Vault 默认情况下维护会话令牌生命周期。会话令牌是惰性获取的，因此实际登录被延迟，直到第一次会话绑定使用 Vault。一旦 Spring Cloud Vault 获得会话令牌，它就会保留它，直到它过期。下次使用会话绑定活动时，Spring Cloud Vault 将重新登录到 Vault 并获取一个新的会话令牌。在应用程序关闭时，如果会话令牌仍处于活动状态，Spring Cloud Vault 将撤销该令牌以终止会话。

Spring Cloud Vault maintains the session token lifecycle by default. Session tokens are obtained lazily so the actual login is deferred until the first session-bound use of Vault. Once Spring Cloud Vault obtains a session token, it retains it until expiry. The next time a session-bound activity is used, Spring Cloud Vault re-logins into Vault and obtains a new session token. On application shut down, Spring Cloud Vault revokes the token if it was still active to terminate the session.

会话生命周期默认启用，可以通过将 `spring.cloud.vault.session.lifecycle.enabled`设置为`false`来禁用它。不建议禁用，因为会话令牌可能会过期，并且 Spring Cloud Vault 将无法再访问 Vault。

Session lifecycle is enabled by default and can be disabled by setting spring.cloud.vault.session.lifecycle.enabled to false. Disabling is not recommended as session tokens can expire and Spring Cloud Vault cannot longer access Vault.

spring.cloud.vault:
    session.lifecycle:
        enabled: true
        refresh-before-expiry: 10s
        expiry-threshold: 20s

  • enabled controls whether session lifecycle management is enabled to renew session tokens. Enabled by default.

  • refresh-before-expiry controls the point in time when the session token gets renewed. The refresh time is calculated by subtracting refresh-before-expiry from the token expiry time. Defaults to 5 seconds.

  • expiry-threshold sets the expiry threshold. The threshold represents a minimum TTL duration to consider a session token as valid. Tokens with a shorter TTL are considered expired and are not used anymore. Should be greater than refresh-before-expiry to prevent token expiry. Defaults to 7 seconds.

另请参见： Vault Documentation: Token Renewal

See also: Vault Documentation: Token Renewal