diff --git a/README.adoc b/README.adoc index e18f4780..8af6080e 100644 --- a/README.adoc +++ b/README.adoc @@ -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: org.springframework.boot spring-boot-starter-parent - 2.0.0.RELEASE + 2.4.0.RELEASE @@ -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 <>. -.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 diff --git a/docs/pom.xml b/docs/pom.xml index 824f483a..a738359c 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -21,9 +21,34 @@ spring-cloud-vault ${basedir}/.. + spring.cloud.vault.*| + deploy + + + ${project.groupId} + spring-cloud-starter-vault-config + + + ${project.groupId} + spring-cloud-vault-config-aws + + + ${project.groupId} + spring-cloud-vault-config-consul + + + ${project.groupId} + spring-cloud-vault-config-databases + + + ${project.groupId} + spring-cloud-vault-config-rabbitmq + + + src/main/asciidoc @@ -61,7 +86,7 @@ docs - + pl.project13.maven git-commit-id-plugin diff --git a/docs/src/main/asciidoc/_attributes.adoc b/docs/src/main/asciidoc/_attributes.adoc new file mode 100644 index 00000000..0bc84708 --- /dev/null +++ b/docs/src/main/asciidoc/_attributes.adoc @@ -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 diff --git a/docs/src/main/asciidoc/_configprops.adoc b/docs/src/main/asciidoc/_configprops.adoc new file mode 100644 index 00000000..cbd4fd1e --- /dev/null +++ b/docs/src/main/asciidoc/_configprops.adoc @@ -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.

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:

  • Version 1 (unversioned key-value backend).
  • Version 2 (versioned key-value backend).
+|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. + +|=== \ No newline at end of file diff --git a/docs/src/main/asciidoc/appendix.adoc b/docs/src/main/asciidoc/appendix.adoc new file mode 100644 index 00000000..39eb1593 --- /dev/null +++ b/docs/src/main/asciidoc/appendix.adoc @@ -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[] diff --git a/docs/src/main/asciidoc/new-features.adoc b/docs/src/main/asciidoc/new-features.adoc new file mode 100644 index 00000000..f572b09e --- /dev/null +++ b/docs/src/main/asciidoc/new-features.adoc @@ -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 <>. diff --git a/docs/src/main/asciidoc/spring-cloud-vault.adoc b/docs/src/main/asciidoc/spring-cloud-vault.adoc index 61db9428..61027bf4 100644 --- a/docs/src/main/asciidoc/spring-cloud-vault.adoc +++ b/docs/src/main/asciidoc/spring-cloud-vault.adoc @@ -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[]