162 lines
7.5 KiB
Plaintext
162 lines
7.5 KiB
Plaintext
[[service-registry-configuration]]
|
|
= Service Registry Configuration
|
|
|
|
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`.
|
|
|
|
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.
|
|
|
|
[source,yaml]
|
|
----
|
|
spring.cloud.vault.discovery:
|
|
enabled: true
|
|
service-id: my-vault-service
|
|
----
|
|
|
|
[[vault.config.fail-fast]]
|
|
== Vault Client Fail Fast
|
|
|
|
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.
|
|
|
|
[source,yaml]
|
|
----
|
|
spring.cloud.vault:
|
|
fail-fast: true
|
|
----
|
|
|
|
[[vault.config.namespaces]]
|
|
== Vault Enterprise Namespace Support
|
|
|
|
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`.
|
|
|
|
Please note that this feature is not supported by Vault Community edition and has no effect on Vault operations.
|
|
|
|
[source,yaml]
|
|
----
|
|
spring.cloud.vault:
|
|
namespace: my-namespace
|
|
----
|
|
|
|
See also: https://www.vaultproject.io/docs/enterprise/namespaces/index.html[Vault Enterprise: Namespaces]
|
|
|
|
[[vault.config.ssl]]
|
|
== Vault Client SSL configuration
|
|
|
|
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.
|
|
|
|
[source,yaml]
|
|
----
|
|
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).
|
|
|
|
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.
|
|
|
|
[[vault-lease-renewal]]
|
|
== Lease lifecycle management (renewal and revocation)
|
|
|
|
With every secret, Vault creates a lease:
|
|
metadata containing information such as a time duration, renewability, and more.
|
|
|
|
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 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.
|
|
|
|
Secret service and database backends (such as MongoDB or MySQL) usually generate a renewable lease so generated credentials will be disabled on application shutdown.
|
|
|
|
NOTE: Static tokens are not renewed or revoked.
|
|
|
|
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.
|
|
|
|
[source,yaml]
|
|
----
|
|
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.
|
|
|
|
See also: https://www.vaultproject.io/docs/concepts/lease.html[Vault Documentation: Lease, Renew, and Revoke]
|
|
|
|
[[vault-session-lifecycle]]
|
|
== Session token lifecycle management (renewal, re-login and revocation)
|
|
|
|
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 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.
|
|
|
|
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.
|
|
|
|
[source,yaml]
|
|
----
|
|
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`.
|
|
|
|
See also: https://www.vaultproject.io/api-docs/auth/token#renew-a-token-self[Vault Documentation: Token Renewal]
|