SpringCloud/spring-cloud-vault
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Refine documentation

Browse Source 
Include common config properties. Add what's new section.

See gh-483
This commit is contained in:
Mark Paluch
2020-09-21 10:04:24 +02:00
parent fe9caa58f9
commit e1e15030f4
7 changed files with 203 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
README.adoc
View File

@@ -39,7 +39,7 @@ Specifically for Spring applications:
== Quick Start
:docs: https://cloud.spring.io/spring-cloud-vault/spring-cloud-vault.html
:docs: https://cloud.spring.io/spring-cloud-vault/reference/html/
*Prerequisites*
@@ -179,7 +179,7 @@ Example Maven configuration:
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.0.0.RELEASE</version>
<version>2.4.0.RELEASE</version>
<relativePath /> <!-- lookup parent from repository -->
</parent>
@@ -231,9 +231,9 @@ public class Application {
====
When it runs it will pick up the external configuration from the default local Vault server on port `8200` if it is running.
To modify the startup behavior you can change the location of the Vault server using `bootstrap.properties` (like `application.properties` but for the bootstrap phase of an application context), e.g.
To modify the startup behavior you can change the location of the Vault server using `application.properties`, for example
.bootstrap.yml
.application.yml
====
[source,yaml]
----
@@ -245,7 +245,7 @@ spring.cloud.vault:
connection-timeout: 5000
read-timeout: 15000
config:
order: -10
spring.config.import: vault://
----
====
@@ -257,7 +257,7 @@ Supported schemes are `http` and `https`.
* `uri` configure the Vault endpoint with an URI. Takes precedence over host/port/scheme configuration
* `connection-timeout` sets the connection timeout in milliseconds
* `read-timeout` sets the read timeout in milliseconds
* `config.order` sets the order for the property source
* `spring.config.import` mounts Vault as `PropertySource` using all enabled secret backends (key-value enabled by default)
Enabling further integrations requires additional dependencies and configuration.
Depending on how you have set up Vault you might need additional configuration like
@@ -268,6 +268,10 @@ If the application imports the `spring-boot-starter-actuator` project, the statu
The vault health indicator can be enabled or disabled through the property `management.health.vault.enabled` (default to `true`).
NOTE: With Spring Cloud Vault 3.0 and Spring Boot 2.4, the bootstrap context initialization (`bootstrap.yml`, `bootstrap.properties`) of property sources was deprecated.
Instead, Spring Cloud Vault favors Spring Boot's Config Data API which allows importing configuration from Vault.
You can enable the bootstrap context either by setting the configuration property `spring.cloud.bootstrap.enabled=true` or by including the dependency `org.springframework.cloud:spring-cloud-starter-bootstrap`.
=== Authentication
Vault requires an https://www.vaultproject.io/docs/concepts/auth.html[authentication mechanism] to https://www.vaultproject.io/docs/concepts/tokens.html[authorize client requests].
@@ -276,12 +280,13 @@ Spring Cloud Vault supports multiple {docs}#vault.config.authentication[authenti
For a quickstart, use the root token printed by the <<quickstart.vault.start,Vault initialization>>.
.bootstrap.yml
.application.yml
====
[source,yaml]
----
spring.cloud.vault:
token: 19aefa97-cccc-bbbb-aaaa-225940e63d76
spring.config.import: vault://
----
====
@@ -289,6 +294,7 @@ WARNING: Consider carefully your security requirements.
Static token authentication is fine if you want quickly get started with Vault, but a static token is not protected any further.
Any disclosure to unintended parties allows Vault use with the associated token roles.
== Building
=== Build requirements for Vault

27
docs/pom.xml
View File

@@ -21,9 +21,34 @@
<properties>
<docs.main>spring-cloud-vault</docs.main>
<main.basedir>${basedir}/..</main.basedir>
<configprops.inclusionPattern>spring.cloud.vault.*|
</configprops.inclusionPattern>
<upload-docs-zip.phase>deploy</upload-docs-zip.phase>
</properties>
<dependencies>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>spring-cloud-starter-vault-config</artifactId>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>spring-cloud-vault-config-aws</artifactId>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>spring-cloud-vault-config-consul</artifactId>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>spring-cloud-vault-config-databases</artifactId>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>spring-cloud-vault-config-rabbitmq</artifactId>
</dependency>
</dependencies>
<build>
<sourceDirectory>src/main/asciidoc</sourceDirectory>
<pluginManagement>
@@ -61,7 +86,7 @@
<profile>
<id>docs</id>
<build>
<plugins>
<plugins>
<plugin>
<groupId>pl.project13.maven</groupId>
<artifactId>git-commit-id-plugin</artifactId>

15
docs/src/main/asciidoc/_attributes.adoc Normal file
View File

@@ -0,0 +1,15 @@
:doctype: book
:idprefix:
:idseparator: -
:toc: left
:toclevels: 4
:tabsize: 4
:numbered:
:sectanchors:
:sectnums:
:icons: font
:hide-uri-scheme:
:docinfo: shared,private
:sc-ext: java
:project-full-name: Spring Cloud Vault

121
docs/src/main/asciidoc/_configprops.adoc Normal file
View File

@@ -0,0 +1,121 @@
|===
|Name | Default | Description
|spring.cloud.vault.app-id.app-id-path | app-id | Mount path of the AppId authentication backend.
|spring.cloud.vault.app-id.network-interface | | Network interface hint for the "MAC_ADDRESS" UserId mechanism.
|spring.cloud.vault.app-id.user-id | MAC_ADDRESS | UserId mechanism. Can be either "MAC_ADDRESS", "IP_ADDRESS", a string or a class name.
|spring.cloud.vault.app-role.app-role-path | approle | Mount path of the AppRole authentication backend.
|spring.cloud.vault.app-role.role | | Name of the role, optional, used for pull-mode.
|spring.cloud.vault.app-role.role-id | | The RoleId.
|spring.cloud.vault.app-role.secret-id | | The SecretId.
|spring.cloud.vault.application-name | application | Application name for AppId authentication.
|spring.cloud.vault.authentication | |
|spring.cloud.vault.aws-ec2.aws-ec2-path | aws-ec2 | Mount path of the AWS-EC2 authentication backend.
|spring.cloud.vault.aws-ec2.identity-document | http://169.254.169.254/latest/dynamic/instance-identity/pkcs7 | URL of the AWS-EC2 PKCS7 identity document.
|spring.cloud.vault.aws-ec2.nonce | | Nonce used for AWS-EC2 authentication. An empty nonce defaults to nonce generation.
|spring.cloud.vault.aws-ec2.role | | Name of the role, optional.
|spring.cloud.vault.aws-iam.aws-path | aws | Mount path of the AWS authentication backend.
|spring.cloud.vault.aws-iam.endpoint-uri | | STS server URI. @since 2.2
|spring.cloud.vault.aws-iam.role | | Name of the role, optional. Defaults to the friendly IAM name if not set.
|spring.cloud.vault.aws-iam.server-name | | Name of the server used to set {@code X-Vault-AWS-IAM-Server-ID} header in the headers of login requests.
|spring.cloud.vault.aws.access-key-property | cloud.aws.credentials.accessKey | Target property for the obtained access key.
|spring.cloud.vault.aws.backend | aws | aws backend path.
|spring.cloud.vault.aws.enabled | false | Enable aws backend usage.
|spring.cloud.vault.aws.role | | Role name for credentials.
|spring.cloud.vault.aws.secret-key-property | cloud.aws.credentials.secretKey | Target property for the obtained secret key.
|spring.cloud.vault.azure-msi.azure-path | azure | Mount path of the Azure MSI authentication backend.
|spring.cloud.vault.azure-msi.role | | Name of the role.
|spring.cloud.vault.cassandra.backend | cassandra | Cassandra backend path.
|spring.cloud.vault.cassandra.enabled | false | Enable cassandra backend usage.
|spring.cloud.vault.cassandra.password-property | spring.data.cassandra.password | Target property for the obtained password.
|spring.cloud.vault.cassandra.role | | Role name for credentials.
|spring.cloud.vault.cassandra.static-role | false | Enable static role usage. @since 2.2
|spring.cloud.vault.cassandra.username-property | spring.data.cassandra.username | Target property for the obtained username.
|spring.cloud.vault.config.lifecycle.enabled | true | Enable lifecycle management.
|spring.cloud.vault.config.lifecycle.expiry-threshold | | The expiry threshold. {@link Lease} is renewed the given {@link Duration} before it expires. @since 2.2
|spring.cloud.vault.config.lifecycle.lease-endpoints | | Set the {@link LeaseEndpoints} to delegate renewal/revocation calls to. {@link LeaseEndpoints} encapsulates differences between Vault versions that affect the location of renewal/revocation endpoints. Can be {@link LeaseEndpoints#SysLeases} for version 0.8 or above of Vault or {@link LeaseEndpoints#Legacy} for older versions (the default). @since 2.2
|spring.cloud.vault.config.lifecycle.min-renewal | | The time period that is at least required before renewing a lease. @since 2.2
|spring.cloud.vault.config.order | 0 | Used to set a {@link org.springframework.core.env.PropertySource} priority. This is useful to use Vault as an override on other property sources. @see org.springframework.core.PriorityOrdered
|spring.cloud.vault.connection-timeout | 5000 | Connection timeout.
|spring.cloud.vault.consul.backend | consul | Consul backend path.
|spring.cloud.vault.consul.enabled | false | Enable consul backend usage.
|spring.cloud.vault.consul.role | | Role name for credentials.
|spring.cloud.vault.consul.token-property | spring.cloud.consul.token | Target property for the obtained token.
|spring.cloud.vault.database.backend | database | Database backend path.
|spring.cloud.vault.database.enabled | false | Enable database backend usage.
|spring.cloud.vault.database.password-property | spring.datasource.password | Target property for the obtained password.
|spring.cloud.vault.database.role | | Role name for credentials.
|spring.cloud.vault.database.static-role | false | Enable static role usage.
|spring.cloud.vault.database.username-property | spring.datasource.username | Target property for the obtained username.
|spring.cloud.vault.discovery.enabled | false | Flag to indicate that Vault server discovery is enabled (vault server URL will be looked up via discovery).
|spring.cloud.vault.discovery.service-id | vault | Service id to locate Vault.
|spring.cloud.vault.elasticsearch.backend | database | Database backend path.
|spring.cloud.vault.elasticsearch.enabled | false | Enable elasticsearch backend usage.
|spring.cloud.vault.elasticsearch.password-property | spring.elasticsearch.rest.password | Target property for the obtained password.
|spring.cloud.vault.elasticsearch.role | | Role name for credentials.
|spring.cloud.vault.elasticsearch.static-role | false | Enable static role usage.
|spring.cloud.vault.elasticsearch.username-property | spring.elasticsearch.rest.username | Target property for the obtained username.
|spring.cloud.vault.enabled | true | Enable Vault config server.
|spring.cloud.vault.fail-fast | false | Fail fast if data cannot be obtained from Vault.
|spring.cloud.vault.gcp-gce.gcp-path | gcp | Mount path of the Kubernetes authentication backend.
|spring.cloud.vault.gcp-gce.role | | Name of the role against which the login is being attempted.
|spring.cloud.vault.gcp-gce.service-account | | Optional service account id. Using the default id if left unconfigured.
|spring.cloud.vault.gcp-iam.credentials.encoded-key | | The base64 encoded contents of an OAuth2 account private key in JSON format.
|spring.cloud.vault.gcp-iam.credentials.location | | Location of the OAuth2 credentials private key. <p> Since this is a Resource, the private key can be in a multitude of locations, such as a local file system, classpath, URL, etc.
|spring.cloud.vault.gcp-iam.gcp-path | gcp | Mount path of the Kubernetes authentication backend.
|spring.cloud.vault.gcp-iam.jwt-validity | 15m | Validity of the JWT token.
|spring.cloud.vault.gcp-iam.project-id | | Overrides the GCP project Id.
|spring.cloud.vault.gcp-iam.role | | Name of the role against which the login is being attempted.
|spring.cloud.vault.gcp-iam.service-account-id | | Overrides the GCP service account Id.
|spring.cloud.vault.host | localhost | Vault server host.
|spring.cloud.vault.kubernetes.kubernetes-path | kubernetes | Mount path of the Kubernetes authentication backend.
|spring.cloud.vault.kubernetes.role | | Name of the role against which the login is being attempted.
|spring.cloud.vault.kubernetes.service-account-token-file | /var/run/secrets/kubernetes.io/serviceaccount/token | Path to the service account token file.
|spring.cloud.vault.kv.application-name | application | Application name to be used for the context.
|spring.cloud.vault.kv.backend | secret | Name of the default backend.
|spring.cloud.vault.kv.backend-version | 2 | Key-Value backend version. Currently supported versions are: <ul> <li>Version 1 (unversioned key-value backend).</li> <li>Version 2 (versioned key-value backend).</li> </ul>
|spring.cloud.vault.kv.default-context | application | Name of the default context.
|spring.cloud.vault.kv.enabled | true | Enable the kev-value backend.
|spring.cloud.vault.kv.profile-separator | / | Profile-separator to combine application name and profile.
|spring.cloud.vault.kv.profiles | | List of active profiles. @since 3.0
|spring.cloud.vault.mongodb.backend | mongodb | MongoDB backend path.
|spring.cloud.vault.mongodb.enabled | false | Enable mongodb backend usage.
|spring.cloud.vault.mongodb.password-property | spring.data.mongodb.password | Target property for the obtained password.
|spring.cloud.vault.mongodb.role | | Role name for credentials.
|spring.cloud.vault.mongodb.static-role | false | Enable static role usage. @since 2.2
|spring.cloud.vault.mongodb.username-property | spring.data.mongodb.username | Target property for the obtained username.
|spring.cloud.vault.mysql.backend | mysql | mysql backend path.
|spring.cloud.vault.mysql.enabled | false | Enable mysql backend usage.
|spring.cloud.vault.mysql.password-property | spring.datasource.password | Target property for the obtained username.
|spring.cloud.vault.mysql.role | | Role name for credentials.
|spring.cloud.vault.mysql.username-property | spring.datasource.username | Target property for the obtained username.
|spring.cloud.vault.namespace | | Vault namespace (requires Vault Enterprise).
|spring.cloud.vault.pcf.instance-certificate | | Path to the instance certificate (PEM). Defaults to {@code CF_INSTANCE_CERT} env variable.
|spring.cloud.vault.pcf.instance-key | | Path to the instance key (PEM). Defaults to {@code CF_INSTANCE_KEY} env variable.
|spring.cloud.vault.pcf.pcf-path | pcf | Mount path of the Kubernetes authentication backend.
|spring.cloud.vault.pcf.role | | Name of the role against which the login is being attempted.
|spring.cloud.vault.port | 8200 | Vault server port.
|spring.cloud.vault.postgresql.backend | postgresql | postgresql backend path.
|spring.cloud.vault.postgresql.enabled | false | Enable postgresql backend usage.
|spring.cloud.vault.postgresql.password-property | spring.datasource.password | Target property for the obtained username.
|spring.cloud.vault.postgresql.role | | Role name for credentials.
|spring.cloud.vault.postgresql.username-property | spring.datasource.username | Target property for the obtained username.
|spring.cloud.vault.rabbitmq.backend | rabbitmq | rabbitmq backend path.
|spring.cloud.vault.rabbitmq.enabled | false | Enable rabbitmq backend usage.
|spring.cloud.vault.rabbitmq.password-property | spring.rabbitmq.password | Target property for the obtained password.
|spring.cloud.vault.rabbitmq.role | | Role name for credentials.
|spring.cloud.vault.rabbitmq.username-property | spring.rabbitmq.username | Target property for the obtained username.
|spring.cloud.vault.read-timeout | 15000 | Read timeout.
|spring.cloud.vault.scheme | https | Protocol scheme. Can be either "http" or "https".
|spring.cloud.vault.session.lifecycle.enabled | true | Enable session lifecycle management.
|spring.cloud.vault.session.lifecycle.expiry-threshold | 7s | The expiry threshold for a {@link LoginToken}. The threshold represents a minimum TTL duration to consider a login token as valid. Tokens with a shorter TTL are considered expired and are not used anymore. Should be greater than {@code refreshBeforeExpiry} to prevent token expiry.
|spring.cloud.vault.session.lifecycle.refresh-before-expiry | 5s | The time period that is at least required before renewing the {@link LoginToken}.
|spring.cloud.vault.ssl.cert-auth-path | cert | Mount path of the TLS cert authentication backend.
|spring.cloud.vault.ssl.key-store | | Trust store that holds certificates and private keys.
|spring.cloud.vault.ssl.key-store-password | | Password used to access the key store.
|spring.cloud.vault.ssl.trust-store | | Trust store that holds SSL certificates.
|spring.cloud.vault.ssl.trust-store-password | | Password used to access the trust store.
|spring.cloud.vault.token | | Static vault token. Required if {@link #authentication} is {@code TOKEN}.
|spring.cloud.vault.uri | | Vault URI. Can be set with scheme, host and port.
|===

14
docs/src/main/asciidoc/appendix.adoc Normal file
View File

@@ -0,0 +1,14 @@
:numbered!:
[appendix]
[[common-application-properties]]
== Common application properties
include::_attributes.adoc[]
Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches.
This appendix provides a list of common {project-full-name} properties and references to the underlying classes that consume them.
NOTE: Property contributions can come from additional jar files on your classpath, so you should not consider this an exhaustive list.
Also, you can define your own properties.
include::_configprops.adoc[]

8
docs/src/main/asciidoc/new-features.adoc Normal file
View File

@@ -0,0 +1,8 @@
== New & Noteworthy
This section briefly covers items that are new and noteworthy in the latest releases.
[[new-in-3.0.0]]
=== New in Spring Cloud Vault 3.0
* Migration of `PropertySource` initialization from Spring Cloud's Bootstrap Context to Spring Boot's <<vault.configdata,ConfigData API>>.

6
docs/src/main/asciidoc/spring-cloud-vault.adoc
View File

@@ -12,6 +12,10 @@ NOTE: _Copies of this document may be made for your own use and for distribution
include::intro.adoc[]
include::_attributes.adoc[]
include::new-features.adoc[]
== Quick Start
include::quickstart.adoc[]
@@ -23,3 +27,5 @@ include::authentication.adoc[]
include::secret-backends.adoc[]
include::other-topics.adoc[]
include::appendix.adoc[]