Configuring with Vault

Page last updated:

Overview

HashiCorp Vault is a secrets management tool, which encrypts and stores credentials, API keys, and other secrets for use in distributed systems. It provides support for access control lists, secret revocation, auditing, and leases and renewals, and includes special capabilities for common infrastructure and systems such as AWS, MySQL, and RabbitMQ, among others. For more information about Vault, see the documentation.

Spring Cloud Config provides a Vault backend so that the Spring Cloud Config Server can serve configuration stored in Vault. The Spring Cloud Services Config Server supports this backend and can serve configuration stored in Vault to client apps which have been given access to the Vault server (this includes provision of a Vault access token for the client app).

Important: Spring Cloud Services does not provide a HashiCorp Vault server. You must provide your own Vault server in order to use Config Server with Vault.

See below for information about configuring a Config Server service instance to use a HashiCorp Vault server.

General Configuration

Parameters used to configure a Vault server are part of a JSON object called vault, as in {"vault": { "host": "127.0.0.1", "port": 8200 } }.

Important: The Spring Cloud Services Config Server supports only one Vault backend, so only one vault object is permitted in the configuration parameters.

General parameters used to configure the Config Server to use a Vault server are listed below.

Parameter Function
host The host of the Vault server
port The port of the Vault server
kvVersion The Vault API version to use (values `1` or `2`). (default value: `1`)
scheme The URI scheme used in accessing the Vault server. Default value: http
backend The name of the Vault backend from which to retrieve configuration. Default value: secret
defaultKey The default key from which to retrieve configuration. Default value: application
profileSeparator The value used to separate profiles. Default value: ,
skipSslValidation Whether to skip validation of the SSL certificate on the Vault server. Valid values: true, false

For information about writing a client app that accesses configuration values from a Config Server which has been configured to use Vault, see the Use a HashiCorp Vault Server section of Writing Client Applications.

HTTP(S) Proxy Repository Access

You can configure a Config Server service instance to access a Vault server using an HTTP or HTTPS proxy. To do so, you must provide proxy settings in either of the vault.proxy.http or vault.proxy.https JSON objects. You can set the proxy host and port, the proxy username and password (if applicable), and a list of hosts which the Config Server should access outside of the proxy.

Settings for an HTTP proxy are set in the vault.proxy.http object. These might be set as shown in the following command:

cf create-service p.config-server standard config-server -c '{"vault": { "proxy": { "http": { "host": "proxy.example.com", "port": "80" } } } }'

Settings for an HTTPS proxy are set in the vault.proxy.https object. These might be set as shown in the following command:

cf create-service p.config-server standard config-server -c '{"vault": { "proxy": { "https": { "host": "secure.example.com", "port": "443" } } } }'

Note: Some networks require that separate proxy servers are used for HTTP and HTTPS URLs. In such a case, you can set both the proxy.http and proxy.https objects.

The parameters used to configure HTTP or HTTPS proxy settings for the Config Server are listed below.

Parameter Function
proxy.http A proxy object, containing HTTP proxy fields
proxy.http.host The HTTP proxy host
proxy.http.port The HTTP proxy port
proxy.http.nonProxyHosts The hosts to access outside the HTTP proxy
proxy.http.username The username to use with an authenticated HTTP proxy
proxy.http.password The password to use with an authenticated HTTP proxy
proxy.https A proxy object, containing HTTPS proxy fields
proxy.https.host The HTTPS proxy host
proxy.https.port The HTTPS proxy port
proxy.https.nonProxyHosts The hosts to access outside the HTTPS proxy (if proxy.http.nonProxyHosts is also provided, http.nonProxyHosts will be used instead of https.nonProxyHosts)
proxy.https.username The username to use with an authenticated HTTPS proxy (if proxy.http.username is also provided, http.username will be used instead of https.username)
proxy.https.password The password to use with an authenticated HTTPS proxy (if proxy.http.password is also provided, http.password will be used instead of https.password)

To configure a Config Server service instance that uses an HTTP proxy to access a Vault server, use the following command:

cf create-service p.config-server standard config-server -c '{"vault": { "host": "127.0.0.1", "port": 8200, "proxy": { "http": { "host": "proxy.example.com", "port": "80" } } } }'

To configure a Config Server service instance that uses an authenticated HTTPS proxy to access a Vault server, specifying that example.com should be accessed outside of the proxy, use the following command:

cf create-service p.config-server standard config-server -c '{"vault": { "host": "127.0.0.1", "port": 8200, "proxy": { "https": { "host": "secure.example.com", "port": "443", "username": "jim", "password": "wright62", "nonProxyHosts": "example.org" } } } }'

Storing Configuration Properties

When using a HashiCorp Vault configuration source, you can write secrets to the Vault server using the vault Command Line Interface (CLI) tool. Configuration properties can be applicable to all apps that use the Config Server, specific to an app, or specific to a Spring application profile.

Global Configuration

You can store configuration properties so that they are served to all apps which use the Config Server. A secret written to the secret/application path will be served to all apps that access the Config Server.

An example of setting a global configuration property:

$ vault write secret/application message=Greetings

Application-Specific Configuration

You can store configuration properties so that they are served only to a specific app. A secret written to the secret/[APP-NAME] path contains configuration which will be served only to the APP-NAME app.

An example of setting an app-specific configuration property:

$ vault write secret/cook message=Hi

Profile-Specific Configuration

You can store configuration properties so that they are served only to apps which have activated a specific Spring application profile. A secret written to the secret/[APP-NAME],[PROFILE-NAME] path, where [APP-NAME] is the name of an app and [PROFILE-NAME] is the name of an application profile, contains configuration which will be served only to the APP-NAME app running with the [PROFILE-NAME] profile activated.

An example of setting a profile-specific configuration property:

$ vault write secret/cook,dev message=Ho