From 693f9cd46dd2a532ede253cb46da64d1e323c552 Mon Sep 17 00:00:00 2001 From: Mark Paluch Date: Thu, 24 Aug 2023 10:26:32 +0200 Subject: [PATCH] Migrate Documentation to Antora. Closes #810 --- .github/workflows/docs-build.yml | 32 ++ .gitignore | 5 + pom.xml | 8 + spring-vault-distribution/pom.xml | 332 ++++++------------ src/main/antora/antora-playbook.yml | 37 ++ src/main/antora/antora.yml | 12 + .../modules/ROOT/examples}/KeyValueV1.java | 0 .../modules/ROOT/examples}/KeyValueV2.java | 0 .../antora/modules/ROOT/examples}/PKI.java | 0 .../antora/modules/ROOT/examples}/Token.java | 0 .../modules/ROOT/examples}/Transit.java | 0 src/main/antora/modules/ROOT/nav.adoc | 14 + src/main/antora/modules/ROOT/pages/index.adoc | 18 + .../pages/introduction}/dependencies.adoc | 5 +- .../pages/introduction}/getting-started.adoc | 23 +- .../ROOT/pages/introduction/introduction.adoc | 14 + .../pages/introduction/knowing-vault.adoc | 22 ++ .../pages/introduction}/new-features.adoc | 44 +-- .../ROOT/pages/vault}/authentication.adoc | 0 .../ROOT/pages/vault}/client-support.adoc | 0 .../pages/vault}/imperative-template.adoc | 0 .../ROOT/pages/vault}/propertysource.adoc | 2 +- .../ROOT/pages/vault}/reactive-template.adoc | 2 +- .../ROOT/pages/vault/spring-security.adoc} | 9 +- .../ROOT/pages/vault}/vault-repositories.adoc | 0 .../pages/vault}/vault-secret-engines.adoc | 20 +- .../modules/ROOT/pages/vault/vault.adoc | 5 + .../resources/antora-resources/antora.yml | 17 + src/main/asciidoc/index.adoc | 25 -- src/main/asciidoc/preface.adoc | 83 ----- src/main/asciidoc/reference/vault.adoc | 36 -- 31 files changed, 338 insertions(+), 427 deletions(-) create mode 100644 .github/workflows/docs-build.yml create mode 100644 src/main/antora/antora-playbook.yml create mode 100644 src/main/antora/antora.yml rename {spring-vault-core/src/test/java/org/springframework/vault/documentation => src/main/antora/modules/ROOT/examples}/KeyValueV1.java (100%) rename {spring-vault-core/src/test/java/org/springframework/vault/documentation => src/main/antora/modules/ROOT/examples}/KeyValueV2.java (100%) rename {spring-vault-core/src/test/java/org/springframework/vault/documentation => src/main/antora/modules/ROOT/examples}/PKI.java (100%) rename {spring-vault-core/src/test/java/org/springframework/vault/documentation => src/main/antora/modules/ROOT/examples}/Token.java (100%) rename {spring-vault-core/src/test/java/org/springframework/vault/documentation => src/main/antora/modules/ROOT/examples}/Transit.java (100%) create mode 100644 src/main/antora/modules/ROOT/nav.adoc create mode 100644 src/main/antora/modules/ROOT/pages/index.adoc rename src/main/{asciidoc/reference => antora/modules/ROOT/pages/introduction}/dependencies.adoc (91%) rename src/main/{asciidoc/reference => antora/modules/ROOT/pages/introduction}/getting-started.adoc (82%) create mode 100644 src/main/antora/modules/ROOT/pages/introduction/introduction.adoc create mode 100644 src/main/antora/modules/ROOT/pages/introduction/knowing-vault.adoc rename src/main/{asciidoc => antora/modules/ROOT/pages/introduction}/new-features.adoc (56%) rename src/main/{asciidoc/reference => antora/modules/ROOT/pages/vault}/authentication.adoc (100%) rename src/main/{asciidoc/reference => antora/modules/ROOT/pages/vault}/client-support.adoc (100%) rename src/main/{asciidoc/reference => antora/modules/ROOT/pages/vault}/imperative-template.adoc (100%) rename src/main/{asciidoc/reference => antora/modules/ROOT/pages/vault}/propertysource.adoc (99%) rename src/main/{asciidoc/reference => antora/modules/ROOT/pages/vault}/reactive-template.adoc (99%) rename src/main/{asciidoc/reference/misc.adoc => antora/modules/ROOT/pages/vault/spring-security.adoc} (92%) rename src/main/{asciidoc/reference => antora/modules/ROOT/pages/vault}/vault-repositories.adoc (100%) rename src/main/{asciidoc/reference => antora/modules/ROOT/pages/vault}/vault-secret-engines.adoc (95%) create mode 100644 src/main/antora/modules/ROOT/pages/vault/vault.adoc create mode 100644 src/main/antora/resources/antora-resources/antora.yml delete mode 100644 src/main/asciidoc/index.adoc delete mode 100644 src/main/asciidoc/preface.adoc delete mode 100644 src/main/asciidoc/reference/vault.adoc diff --git a/.github/workflows/docs-build.yml b/.github/workflows/docs-build.yml new file mode 100644 index 00000000..a9c039b5 --- /dev/null +++ b/.github/workflows/docs-build.yml @@ -0,0 +1,32 @@ +name: Deploy Docs Dispatch +on: + push: + branches-ignore: [ gh-pages ] + tags: '**' + repository_dispatch: + types: request-build-reference # legacy + #schedule: + #- cron: '0 10 * * *' # Once per day at 10am UTC + workflow_dispatch: +permissions: + actions: write +jobs: + build: + runs-on: ubuntu-latest + if: github.repository_owner == 'spring-projects' + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + ref: docs-build + fetch-depth: 1 + - name: Dispatch (partial build) + if: github.ref_type == 'branch' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run docs-build.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }} + - name: Dispatch (full build) + if: github.ref_type == 'tag' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run docs-build.yml -r $(git rev-parse --abbrev-ref HEAD) diff --git a/.gitignore b/.gitignore index b73c7d35..ca321fbc 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,8 @@ release.properties /vault/ download/ work/ + +node +node_modules +package.json +package-lock.json diff --git a/pom.xml b/pom.xml index 1081834d..5e965aac 100644 --- a/pom.xml +++ b/pom.xml @@ -18,6 +18,7 @@ + 0.0.3 3.24.2 2.18.24 1.70 @@ -535,6 +536,13 @@ 3.11.0 + + org.apache.maven.plugins + maven-resources-plugin + 3.3.1 + + + org.apache.maven.plugins maven-jar-plugin diff --git a/spring-vault-distribution/pom.xml b/spring-vault-distribution/pom.xml index 976c9971..5a714692 100644 --- a/spring-vault-distribution/pom.xml +++ b/spring-vault-distribution/pom.xml @@ -22,7 +22,24 @@ + + + ${project.basedir}/../src/main/antora/resources/antora-resources + true + + + + org.apache.maven.plugins + maven-resources-plugin + + + + resources + + + + org.apache.maven.plugins maven-antrun-plugin @@ -31,14 +48,6 @@ org.apache.maven.plugins maven-assembly-plugin - - org.codehaus.mojo - wagon-maven-plugin - - - org.asciidoctor - asciidoctor-maven-plugin - org.jfrog.buildinfo artifactory-maven-plugin @@ -47,6 +56,94 @@ + + + antora-process-resources + + + + io.spring.maven.antora + antora-component-version-maven-plugin + ${antora.version} + + + + antora-component-version + + + + + + + org.apache.maven.plugins + maven-antrun-plugin + + + export-properties + generate-resources + + + + ${spring.version} + + + + + + true + + + run + + + + + + + + + + + antora + + + true + true + true + true + true + + + + + + org.apache.maven.plugins + maven-deploy-plugin + + true + + + + io.spring.maven.antora + antora-maven-plugin + ${antora.version} + true + + ${project.basedir}/../src/main/antora/antora-playbook.yml + + + + + antora + + compile + + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - run - - - - - - - org.asciidoctor - asciidoctor-maven-plugin - - - org.asciidoctor - asciidoctorj-pdf - 2.0.3 - - - org.asciidoctor - asciidoctorj-epub3 - 1.5.1 - - - io.spring.asciidoctor.backends - spring-asciidoctor-backends - ${spring-asciidoctor-backends.version} - - - - - - html - compile - - process-asciidoc - - - - ${generated-asciidoc-sources.directory} - - index.adoc - - spring-html - ${generated-docs.directory} - - highlight.js - - - true - shared - css/ - spring.css - true - font - left - highlightjs - - js/highlight - github - - - - - - epub - compile - - process-asciidoc - - - - ${generated-asciidoc-sources.directory} - - index.adoc - - epub3 - - ${project.build.directory}/generated-docs - - coderay - - - - - pdf - compile - - process-asciidoc - - - - ${generated-asciidoc-sources.directory} - - index.adoc - - pdf - - ${project.build.directory}/generated-docs - - coderay - - - - - - - book - - book - shared - font - false - images - ${project.version} - ${project.name} - ${project.version} - ${spring.version} - - ${spring-data-bom.version} - - true - 4 - true - - - - - - org.apache.maven.plugins maven-assembly-plugin diff --git a/src/main/antora/antora-playbook.yml b/src/main/antora/antora-playbook.yml new file mode 100644 index 00000000..ac7a8868 --- /dev/null +++ b/src/main/antora/antora-playbook.yml @@ -0,0 +1,37 @@ +# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2 +# +# The purpose of this Antora playbook is to build the docs in the current branch. +antora: + extensions: + - '@antora/collector-extension' + - require: '@springio/antora-extensions/root-component-extension' + root_component_name: 'vault' +site: + title: Spring Vault + url: https://docs.spring.io/spring-vault/reference/ +content: + sources: + - url: ./../../.. + branches: HEAD + start_path: src/main/antora + worktrees: true +asciidoc: + attributes: + page-pagination: '' + hide-uri-scheme: '@' + tabs-sync-option: '@' + chomp: 'all' + extensions: + - '@asciidoctor/tabs' + - '@springio/asciidoctor-extensions' + sourcemap: true +urls: + latest_version_segment: '' +runtime: + log: + failure_level: warn + format: pretty +ui: + bundle: + url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.3/ui-bundle.zip + snapshot: true diff --git a/src/main/antora/antora.yml b/src/main/antora/antora.yml new file mode 100644 index 00000000..cc61502b --- /dev/null +++ b/src/main/antora/antora.yml @@ -0,0 +1,12 @@ +name: vault +version: true +title: Spring Vault +nav: + - modules/ROOT/nav.adoc +ext: + collector: + - run: + command: ./mvnw validate process-resources -pl :spring-vault-distribution -am -Pantora-process-resources + local: true + scan: + dir: spring-vault-distribution/target/classes/ diff --git a/spring-vault-core/src/test/java/org/springframework/vault/documentation/KeyValueV1.java b/src/main/antora/modules/ROOT/examples/KeyValueV1.java similarity index 100% rename from spring-vault-core/src/test/java/org/springframework/vault/documentation/KeyValueV1.java rename to src/main/antora/modules/ROOT/examples/KeyValueV1.java diff --git a/spring-vault-core/src/test/java/org/springframework/vault/documentation/KeyValueV2.java b/src/main/antora/modules/ROOT/examples/KeyValueV2.java similarity index 100% rename from spring-vault-core/src/test/java/org/springframework/vault/documentation/KeyValueV2.java rename to src/main/antora/modules/ROOT/examples/KeyValueV2.java diff --git a/spring-vault-core/src/test/java/org/springframework/vault/documentation/PKI.java b/src/main/antora/modules/ROOT/examples/PKI.java similarity index 100% rename from spring-vault-core/src/test/java/org/springframework/vault/documentation/PKI.java rename to src/main/antora/modules/ROOT/examples/PKI.java diff --git a/spring-vault-core/src/test/java/org/springframework/vault/documentation/Token.java b/src/main/antora/modules/ROOT/examples/Token.java similarity index 100% rename from spring-vault-core/src/test/java/org/springframework/vault/documentation/Token.java rename to src/main/antora/modules/ROOT/examples/Token.java diff --git a/spring-vault-core/src/test/java/org/springframework/vault/documentation/Transit.java b/src/main/antora/modules/ROOT/examples/Transit.java similarity index 100% rename from spring-vault-core/src/test/java/org/springframework/vault/documentation/Transit.java rename to src/main/antora/modules/ROOT/examples/Transit.java diff --git a/src/main/antora/modules/ROOT/nav.adoc b/src/main/antora/modules/ROOT/nav.adoc new file mode 100644 index 00000000..873c97a0 --- /dev/null +++ b/src/main/antora/modules/ROOT/nav.adoc @@ -0,0 +1,14 @@ +* xref:index.adoc[Index] +* xref:introduction/introduction.adoc[] +** xref:introduction/getting-started.adoc[] +** xref:introduction/dependencies.adoc[] +** xref:introduction/new-features.adoc[] +* xref:vault/vault.adoc[] +** xref:vault/imperative-template.adoc[] +** xref:vault/vault-secret-engines.adoc[] +** xref:vault/reactive-template.adoc[] +** xref:vault/propertysource.adoc[] +** xref:vault/vault-repositories.adoc[] +** xref:vault/client-support.adoc[] +** xref:vault/authentication.adoc[] +** xref:vault/spring-security.adoc[] diff --git a/src/main/antora/modules/ROOT/pages/index.adoc b/src/main/antora/modules/ROOT/pages/index.adoc new file mode 100644 index 00000000..571dac35 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/index.adoc @@ -0,0 +1,18 @@ +[[spring-vault-reference-documentation]] += Spring Vault +:revnumber: {version} +:revdate: {localdate} +:feature-scroll: true + +[horizontal] +xref:introduction/introduction.adoc[Introduction] :: Introduction to Spring Vault +xref:vault/vault.adoc[Vault Core Support] :: Vault Template and Repositories +xref:vault/authentication.adoc[Authentication] :: Supported Authentication Methods +xref:vault/propertysource.adoc[Vault Property Source] :: Mounting Vault Secret Backends as Property Source + +Mark Paluch + +(C) 2008-2023 VMware, Inc. + +Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. + diff --git a/src/main/asciidoc/reference/dependencies.adoc b/src/main/antora/modules/ROOT/pages/introduction/dependencies.adoc similarity index 91% rename from src/main/asciidoc/reference/dependencies.adoc rename to src/main/antora/modules/ROOT/pages/introduction/dependencies.adoc index 84cf7a55..0e78da94 100644 --- a/src/main/asciidoc/reference/dependencies.adoc +++ b/src/main/antora/modules/ROOT/pages/introduction/dependencies.adoc @@ -1,16 +1,17 @@ [[dependencies]] -== Dependencies += Dependencies If you want to use Spring Vault in your project, declare a dependency to the `spring-vault-core` artifact. .Declaring a dependency to Spring Vault ==== -[source,xml] +[source,xml,subs="verbatim,attributes"] ---- org.springframework.vault spring-vault-core + {version} ---- diff --git a/src/main/asciidoc/reference/getting-started.adoc b/src/main/antora/modules/ROOT/pages/introduction/getting-started.adoc similarity index 82% rename from src/main/asciidoc/reference/getting-started.adoc rename to src/main/antora/modules/ROOT/pages/introduction/getting-started.adoc index 5ecd77a1..61d1ca80 100644 --- a/src/main/asciidoc/reference/getting-started.adoc +++ b/src/main/antora/modules/ROOT/pages/introduction/getting-started.adoc @@ -2,15 +2,15 @@ = Getting Started Spring Vault support requires Vault 0.6 or higher and Java SE 6 or higher. -An easy way to bootstrap setting up a working environment is to create a -Spring based project in https://spring.io/tools/sts[STS]. +An easy way to bootstrap setting up a working environment is to create a Spring based project in https://spring.io/tools/sts[STS]. First you need to set up a running Vault server. Refer to the https://www.vaultproject.io/intro/[Vault] for an explanation on how to startup a Vault instance. To create a Spring project in STS go to File -> New -> Spring Template Project -> Simple Spring Utility Project -> -press Yes when prompted. Then enter a project and a package name such as `org.spring.vault.example`. +press Yes when prompted. +Then enter a project and a package name such as `org.spring.vault.example`. Then add the following to `pom.xml` dependencies section. @@ -32,8 +32,7 @@ Then add the following to `pom.xml` dependencies section. ---- ==== -If you are using a milestone or release candidate, you will also need to add the location of the Spring -Milestone repository to your maven `pom.xml` which is at the same level of your `` element. +If you are using a milestone or release candidate, you will also need to add the location of the Spring Milestone repository to your maven `pom.xml` which is at the same level of your `` element. ==== [source,xml] @@ -42,7 +41,7 @@ Milestone repository to your maven `pom.xml` which is at the same level of your spring-milestone Spring Maven MILESTONE Repository - https://repo.spring.io/libs-milestone + https://repo.spring.io/milestone ---- @@ -50,8 +49,7 @@ Milestone repository to your maven `pom.xml` which is at the same level of your The repository is also https://repo.spring.io/milestone/org/springframework/vault/[browseable here]. -If you are using a SNAPSHOT, you will also need to add the location of the Spring -Snapshot repository to your maven `pom.xml` which is at the same level of your `` element. +If you are using a SNAPSHOT, you will also need to add the location of the Spring Snapshot repository to your maven `pom.xml` which is at the same level of your `` element. ==== [source,xml] @@ -135,8 +133,7 @@ object and the `ClientAuthentication`. You are not required to spin up a Spring Context to use Spring Vault. * Vault is expected to be configured with a root token of `00000000-0000-0000-0000-000000000000` to run this application. -* The mapper works against standard POJO objects without the need for any -additional metadata (though you can optionally provide that information). -* Mapping conventions can use field access. Notice the `Secrets` class has only getters. -* If the constructor argument names match the field names of the stored document, -they will be used to instantiate the object. +* The mapper works against standard POJO objects without the need for any additional metadata (though you can optionally provide that information). +* Mapping conventions can use field access. +Notice the `Secrets` class has only getters. +* If the constructor argument names match the field names of the stored document, they will be used to instantiate the object. diff --git a/src/main/antora/modules/ROOT/pages/introduction/introduction.adoc b/src/main/antora/modules/ROOT/pages/introduction/introduction.adoc new file mode 100644 index 00000000..0aa18f26 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/introduction/introduction.adoc @@ -0,0 +1,14 @@ +[[vault.introduction]] += Introduction + +This section explains introductory topics such as how to get started and the new and noteworthy changes for each release. + +The Vault support contains a wide range of features which are summarized below. + +* Spring configuration support using Java based @Configuration classes +* xref:vault/imperative-template.adoc[`VaultTemplate`] helper class that increases productivity performing common Vault operations and its xref:vault/reactive-template.adoc[reactive variant]. +Includes integrated object mapping between Vault responses and POJOs. +* xref:vault/propertysource.adoc[`@VaultPropertySource`] support to mount Vault secret backends as property sources. +* xref:vault/vault-repositories.adoc[Vault repositories] to interact with Vault as data source using Spring Data repositories. + +For most tasks, you will find yourself using `VaultTemplate` that leverages the rich communication functionality. `VaultTemplate` is the place to look for accessing functionality such as reading data from Vault or issuing administrative commands. `VaultTemplate` also provides callback methods so that it is easy for you to get a hold of the low-level API artifacts such as `RestTemplate` to communicate directly with Vault. diff --git a/src/main/antora/modules/ROOT/pages/introduction/knowing-vault.adoc b/src/main/antora/modules/ROOT/pages/introduction/knowing-vault.adoc new file mode 100644 index 00000000..48fa60cf --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/introduction/knowing-vault.adoc @@ -0,0 +1,22 @@ +[[vault.vaultproject]] += Knowing Vault + +Security and working with secrets is a concern of every developer working with databases, user credentials or API keys. +Vault steps in by providing a secure storage combined with access control, revocation, key rolling and auditing. +In short: Vault is a service for securely accessing and storing secrets. +A secret is anything that you want to tightly control access to, such as API keys, passwords, certificates, and more. + +The jumping off ground for learning about Vault is https://www.vaultproject.io[www.vaultproject.io]. +Here is a list of useful resources: + +* The manual introduces Vault and contains links to getting started guides, reference documentation and tutorials. + +* The online shell provides a convenient way to interact with a Vault instance in combination with the online tutorial. + +* https://learn.hashicorp.com/collections/vault/getting-started[Getting Started with Vault] + +* https://www.vaultproject.io/docs[HashiCorp Vault Documentation] + +Spring Vault provides client-side support for accessing, storing and revoking secrets. +With https://www.vaultproject.io[HashiCorp's Vault] you have a central place to manage external secret data for applications across all environments. +Vault can manage static and dynamic secrets such as application data, username/password for remote applications/resources and provide credentials for external services such as MySQL, PostgreSQL, Apache Cassandra, Consul, AWS and more. diff --git a/src/main/asciidoc/new-features.adoc b/src/main/antora/modules/ROOT/pages/introduction/new-features.adoc similarity index 56% rename from src/main/asciidoc/new-features.adoc rename to src/main/antora/modules/ROOT/pages/introduction/new-features.adoc index 43bfca86..ba357755 100644 --- a/src/main/asciidoc/new-features.adoc +++ b/src/main/antora/modules/ROOT/pages/introduction/new-features.adoc @@ -1,76 +1,76 @@ [[new-features]] -== New & Noteworthy += New & Noteworthy [[new-features.3-0-0]] -=== What's new in Spring Vault 3.0 +== What's new in Spring Vault 3.0 * Upgrade to Spring Framework 6 and Java 17 baseline * Upgrade to AWS SDK 2. -=== What's new in Spring Vault 2.4 +== What's new in Spring Vault 2.4 -* Support for <> for Username/Password, LDAP, Okta, and RADIUS authentication. +* Support for xref:vault/authentication.adoc#vault.authentication.userpass[Username/Password authentication] for Username/Password, LDAP, Okta, and RADIUS authentication. * Support of versioned Key/Value secrets engines for Vault repositories. -* <>. +* xref:vault/vault-repositories.adoc#repositories.optimistic-locking[Optimistic locking support through Vault repositories using versioned Key/Value secrets engines]. [[new-features.2-3-0]] -=== What's new in Spring Vault 2.3 +== What's new in Spring Vault 2.3 * Support for PEM-encoded certificates for keystore and truststore usage. * `ReactiveVaultEndpointProvider` for non-blocking lookup of `VaultEndpoint`. * `VaultKeyValueMetadataOperations` for Key-Value metadata interaction. * Support for `transform` secrets engine (Enterprise Feature). -* Documentation of <>. +* Documentation of xref:vault/vault-secret-engines.adoc[how to use Vault secret backends]. * Login credentials for Kubernetes and PCF authentication are reloaded for each login attempt. * `SecretLeaseContainer` publishes `SecretLeaseRotatedEvent` instead of `SecretLeaseExpiredEvent` and `SecretLeaseCreatedEvent` on successful secret rotation. * `AbstractVaultConfiguration.threadPoolTaskScheduler()` bean type changed to `TaskSchedulerWrapper` instead of `ThreadPoolTaskScheduler`. * Since 2.3.2: `GcpIamCredentialsAuthentication` [[new-features.2-2-0]] -=== What's new in Spring Vault 2.2 +== What's new in Spring Vault 2.2 * Support for Key-Value v2 (versioned secrets engine) secrets through `@VaultPropertySource`. * SpEL support in `@Secret`. * Add support for Jetty as reactive HttpClient. * `LifecycleAwareSessionManager` and `ReactiveLifecycleAwareSessionManager` emit now ``AuthenticationEvent``s. -* <>. +* xref:vault/vault-secret-engines.adoc#vault.authentication.pcf[PCF Authentication]. * Deprecation of `AppIdAuthentication`. Use `AppRoleAuthentication` instead as recommended by HashiCorp Vault. * `CubbyholeAuthentication` and wrapped `AppRoleAuthentication` now use `sys/wrapping/unwrap` endpoints by default. * Kotlin Coroutines support for `ReactiveVaultOperations`. [[new-features.2-1-0]] -=== What's new in Spring Vault 2.1 +== What's new in Spring Vault 2.1 -* <>, <>, and <> authentication. +* xref:vault/authentication.adoc#vault.authentication.gcpgce[GCP Compute], xref:vault/authentication.adoc#vault.authentication.gcpiam[GCP IAM], and xref:vault/authentication.adoc#vault.authentication.azuremsi[Azure] authentication. * Template API support for versioned and unversioned Key/Value secrets engines and for Vault wrapping operations. * Support full pull mode in reactive AppRole authentication. * Improved Exception hierarchy for Vault login failures. [[new-features.2-0-0]] -=== What's new in Spring Vault 2.0 +== What's new in Spring Vault 2.0 -* Authentication steps DSL to <>. -* <> via `ReactiveVaultOperations`. -* <> based on Spring Data KeyValue. +* Authentication steps DSL to xref:vault/authentication.adoc#vault.authentication.steps[compose authentication flows]. +* xref:vault/reactive-template.adoc[Reactive Vault client] via `ReactiveVaultOperations`. +* xref:vault/vault-repositories.adoc[Vault repository support] based on Spring Data KeyValue. * Transit batch encrypt and decrypt support. * Policy management for policies stored as JSON. * Support CSR signing, certificate revocation and CRL retrieval. -* <>. -* RoleId/SecretId unwrapping for <>. -* <> with transit secrets engine-based `BytesKeyGenerator` and `BytesEncryptor`. +* xref:vault/authentication.adoc#vault.authentication.kubernetes[Kubernetes authentication]. +* RoleId/SecretId unwrapping for xref:vault/authentication.adoc#vault.authentication.approle[AppRole authentication]. +* Spring Security integration with transit secrets engine-based `BytesKeyGenerator` and `BytesEncryptor`. [[new-features.1-1-0]] -=== What's new in Spring Vault 1.1.0 +== What's new in Spring Vault 1.1.0 -* <>. +* AWS IAM authentication. * Configuration of encryption/decryption versions for transit keys. -* Pull mode for <>. +* Pull mode for AppRole authentication. * Transit batch encrypt and decrypt support. * TTL-based generic secret rotation. [[new-features.1-0-0]] -=== What's new in Spring Vault 1.0 +== What's new in Spring Vault 1.0 * Initial Vault support. diff --git a/src/main/asciidoc/reference/authentication.adoc b/src/main/antora/modules/ROOT/pages/vault/authentication.adoc similarity index 100% rename from src/main/asciidoc/reference/authentication.adoc rename to src/main/antora/modules/ROOT/pages/vault/authentication.adoc diff --git a/src/main/asciidoc/reference/client-support.adoc b/src/main/antora/modules/ROOT/pages/vault/client-support.adoc similarity index 100% rename from src/main/asciidoc/reference/client-support.adoc rename to src/main/antora/modules/ROOT/pages/vault/client-support.adoc diff --git a/src/main/asciidoc/reference/imperative-template.adoc b/src/main/antora/modules/ROOT/pages/vault/imperative-template.adoc similarity index 100% rename from src/main/asciidoc/reference/imperative-template.adoc rename to src/main/antora/modules/ROOT/pages/vault/imperative-template.adoc diff --git a/src/main/asciidoc/reference/propertysource.adoc b/src/main/antora/modules/ROOT/pages/vault/propertysource.adoc similarity index 99% rename from src/main/asciidoc/reference/propertysource.adoc rename to src/main/antora/modules/ROOT/pages/vault/propertysource.adoc index c7186e2c..13529c4e 100644 --- a/src/main/asciidoc/reference/propertysource.adoc +++ b/src/main/antora/modules/ROOT/pages/vault/propertysource.adoc @@ -1,5 +1,5 @@ [[vault.core.propertysupport]] -= Vault Property Source Support += Property Sources Vault can be used in many different ways. One specific use-case is using Vault to store encrypted properties. Spring Vault supports Vault as property diff --git a/src/main/asciidoc/reference/reactive-template.adoc b/src/main/antora/modules/ROOT/pages/vault/reactive-template.adoc similarity index 99% rename from src/main/asciidoc/reference/reactive-template.adoc rename to src/main/antora/modules/ROOT/pages/vault/reactive-template.adoc index 0224d97c..7768e890 100644 --- a/src/main/asciidoc/reference/reactive-template.adoc +++ b/src/main/antora/modules/ROOT/pages/vault/reactive-template.adoc @@ -1,5 +1,5 @@ [[vault.core.reactive.template]] -= Introduction to ReactiveVaultTemplate += Reactive Infrastructure This section covers basic information on the reactive programming support using Spring Vault. diff --git a/src/main/asciidoc/reference/misc.adoc b/src/main/antora/modules/ROOT/pages/vault/spring-security.adoc similarity index 92% rename from src/main/asciidoc/reference/misc.adoc rename to src/main/antora/modules/ROOT/pages/vault/spring-security.adoc index 5d8cd586..57f6018d 100644 --- a/src/main/asciidoc/reference/misc.adoc +++ b/src/main/antora/modules/ROOT/pages/vault/spring-security.adoc @@ -1,10 +1,5 @@ -[[vault.misc]] -= Miscellaneous - -Learn in this chapter about details worth mentioning like the Spring Security integration. - -[[vault.misc.spring-security]] -== Spring Security +[[vault.spring-security]] += Spring Security Spring Vault integrates with Spring Security by providing implementations for https://docs.spring.io/spring-security/site/docs/current/reference/htmlsingle/#spring-security-crypto-keygenerators[`BytesKeyGenerator`] and https://docs.spring.io/spring-security/site/docs/current/reference/htmlsingle/#spring-security-crypto-encryption[`BytesEncryptor`]. Both implementations use Vault's `transit` backend. diff --git a/src/main/asciidoc/reference/vault-repositories.adoc b/src/main/antora/modules/ROOT/pages/vault/vault-repositories.adoc similarity index 100% rename from src/main/asciidoc/reference/vault-repositories.adoc rename to src/main/antora/modules/ROOT/pages/vault/vault-repositories.adoc diff --git a/src/main/asciidoc/reference/vault-secret-engines.adoc b/src/main/antora/modules/ROOT/pages/vault/vault-secret-engines.adoc similarity index 95% rename from src/main/asciidoc/reference/vault-secret-engines.adoc rename to src/main/antora/modules/ROOT/pages/vault/vault-secret-engines.adoc index 8578657f..ae633b4b 100644 --- a/src/main/asciidoc/reference/vault-secret-engines.adoc +++ b/src/main/antora/modules/ROOT/pages/vault/vault-secret-engines.adoc @@ -34,7 +34,7 @@ The following example uses the Key-Value version 1: ==== [source,java,indent=0] ---- -include::../{example-root}/KeyValueV1.java[tags=keyValueApi] +include::example$KeyValueV1.java[tags=keyValueApi] ---- ==== @@ -47,7 +47,7 @@ The `kv` secrets engine is mounted at `secret`: ==== [source,java,indent=0] ---- -include::../{example-root}/KeyValueV1.java[tags=vaultOperations] +include::example$KeyValueV1.java[tags=vaultOperations] ---- ==== @@ -72,7 +72,7 @@ The following example uses Key-Value version 2: ==== [source,java,indent=0] ---- -include::../{example-root}/KeyValueV2.java[tags=keyValueApi] +include::example$KeyValueV2.java[tags=keyValueApi] ---- ==== @@ -83,7 +83,7 @@ You can also interact with the specifics of the versioned key-value API. This is ==== [source,java,indent=0] ---- -include::../{example-root}/KeyValueV2.java[tags=versionedApi] +include::example$KeyValueV2.java[tags=versionedApi] ---- <1> Store secrets at `elvis` in that is available under the `secret/` mount. <2> Storing data in the versioned backend returns metadata such as the version number. @@ -99,7 +99,7 @@ Specifically, interaction with the actual secrets requires wrapping and unwrappi ==== [source,java,indent=0] ---- -include::../{example-root}/KeyValueV2.java[tags=vaultOperations] +include::example$KeyValueV2.java[tags=vaultOperations] ---- ==== @@ -122,7 +122,7 @@ The following examples explain briefly the use of how to issue and revoke certif ==== [source,java,indent=0] ---- -include::../{example-root}/PKI.java[tags=pkiApi] +include::example$PKI.java[tags=pkiApi] ---- <1> Construct a certificate request by using the `VaultCertificateRequest` builder. <2> Request a certificate from Vault. @@ -157,7 +157,7 @@ The following examples show how to request, renew and revoke a Vault token from ==== [source,java,indent=0] ---- -include::../{example-root}/Token.java[tags=tokenApi] +include::example$Token.java[tags=tokenApi] ---- <1> Create an token by applying role defaults. <2> Using the builder API, you can define fine-grained settings for the token to request. @@ -196,7 +196,7 @@ The following examples shows how to create a key and how to encrypt and decrypt ==== [source,java,indent=0] ---- -include::../{example-root}/Transit.java[tags=encryptSimple] +include::example$Transit.java[tags=encryptSimple] ---- <1> First, we need a key to begin with. Each key requires the type to be specified. `aes128-gcm96` supports encryption, decryption, key derivation, and convergent encryption, of which we need encryption and decryption for this example. @@ -217,7 +217,7 @@ To encrypt and decrypt binary data, use the `Plaintext` and `Ciphertext` value o ==== [source,java,indent=0] ---- -include::../{example-root}/Transit.java[tags=encryptPlaintext] +include::example$Transit.java[tags=encryptPlaintext] ---- <1> Assuming a key `my-aes-key` is already in place, we're encrypting the `Plaintext` object. In return, the `encrypt` method returns a `Ciphertext` object. @@ -239,7 +239,7 @@ Internally, the hash gets computed and encrypted using the private key to create ==== [source,java,indent=0] ---- -include::../{example-root}/Transit.java[tags=signVerify] +include::example$Transit.java[tags=signVerify] ---- <1> Signing requires an asymmetric key. You can use any Elliptic Curve Cryptography or RSA key type. Once the key is created, you have all the prerequisites in place to create a signature. <2> The signature gets created for a plain text message. The returned `Signature` contains an ASCII-safe string that uses Base64 characters. diff --git a/src/main/antora/modules/ROOT/pages/vault/vault.adoc b/src/main/antora/modules/ROOT/pages/vault/vault.adoc new file mode 100644 index 00000000..b343e87c --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/vault/vault.adoc @@ -0,0 +1,5 @@ +[[vault.reference]] += Vault +:page-section-summary-toc: 1 + +This chapter points out the specialties for Vault support. diff --git a/src/main/antora/resources/antora-resources/antora.yml b/src/main/antora/resources/antora-resources/antora.yml new file mode 100644 index 00000000..5e10c650 --- /dev/null +++ b/src/main/antora/resources/antora-resources/antora.yml @@ -0,0 +1,17 @@ +version: ${antora-component.version} +prerelease: ${antora-component.prerelease} + +asciidoc: + attributes: + version: ${project.version} + springversionshort: ${spring.version.short} + springversion: ${spring.version} + attribute-missing: 'warn' + include-xml-namespaces: false + self-docs-root: https://docs.spring.io/spring-vault/reference/ + spring-data-commons-docs-url: https://docs.spring.io/spring-data-commons/reference + spring-data-commons-javadoc-base: https://docs.spring.io/spring-data/commons/docs/current/api/ + spring-framework-docs: https://docs.spring.io/spring-framework/reference/{springversionshort} + springjavadocurl: https://docs.spring.io/spring-framework/docs/${spring.version}/javadoc-api + spring-framework-javadoc: '{springjavadocurl}' + springDataVersion: ${spring-data-bom.version} diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc deleted file mode 100644 index 64f45b1d..00000000 --- a/src/main/asciidoc/index.adoc +++ /dev/null @@ -1,25 +0,0 @@ -= Spring Vault - Reference Documentation -Mark Paluch; -:revnumber: {version} -:revdate: {localdate} -:spring-framework-docs: https://docs.spring.io/spring/docs/{springVersion}/spring-framework-reference/ -:self-docs-root: https://docs.spring.io/spring-vault/docs/{version}/ -:example-root: ../../../../spring-vault-core/src/test/java/org/springframework/vault/documentation - -(C) 2016-2022 The original authors. - -NOTE: _Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically._ - -toc::[] - -include::preface.adoc[] - -include::new-features.adoc[] - -ifndef::ebook-format[= Reference documentation [[reference-documentation]]] - -:leveloffset: +1 - -include::reference/vault.adoc[] - -:leveloffset: -1 diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc deleted file mode 100644 index 9bbbdcd2..00000000 --- a/src/main/asciidoc/preface.adoc +++ /dev/null @@ -1,83 +0,0 @@ -[[preface]] -= Preface - -The Spring Vault project applies core Spring concepts to the development of solutions using HashiCorp Vault. We provide a "template" as a high-level abstraction for storing and querying documents. You will notice similarities to the REST support in the Spring Framework. - -This document is the reference guide for Spring Vault. It explains Vault concepts and semantics and the syntax. - -This part of the reference documentation explains the core functionality offered by Spring Vault. - -<> introduces the Vault module feature set. - -[[preface.document-structure]] -== Document Structure - -This section provides basic introduction to Spring and Vault. -It contains details about following development and how to get support. - -The rest of the document refers to Spring Vault features and assumes -the user is familiar with https://www.vaultproject.io[HashiCorp Vault] -as well as Spring concepts. - -[[get-started:first-steps:spring]] -== Knowing Spring - -Spring Vault uses Spring framework's {spring-framework-docs}core.html[core] functionality, such as {spring-framework-docs}/core.html[IoC] container. While it is not important to know the Spring APIs, understanding the concepts behind them is. At a minimum, the idea behind IoC should be familiar for whatever IoC container you choose to use. - -The core functionality of the Vault support can be used directly, with no need to invoke the IoC services of the Spring Container. This is much like `RestTemplate` which can be used 'standalone' without any other services of the Spring container. To leverage all the features of Spring Vault document, such as the session support, you will need to configure some parts of the library using Spring. - -To learn more about Spring, you can refer to the comprehensive (and sometimes disarming) documentation that explains in detail the Spring Framework. There are a lot of articles, blog entries and books on the matter - take a look at the Spring framework https://spring.io/docs[home page ] for more information. - -[[get-started:first-steps:vault]] -== Knowing Vault - -Security and working with secrets is a concern of every developer working with databases, user credentials or API keys. Vault steps in by providing a secure storage combined with access control, revocation, key rolling and auditing. In short: Vault is a service for securely accessing and storing secrets. A secret is anything that you want to tightly control access to, such as API keys, passwords, certificates, and more. - -The jumping off ground for learning about Vault is https://www.vaultproject.io[www.vaultproject.io]. Here is a list of useful resources: - -* The manual introduces Vault and contains links to getting started guides, reference documentation and tutorials. - -* The online shell provides a convenient way to interact with a Vault instance in combination with the online tutorial. - -* https://learn.hashicorp.com/collections/vault/getting-started[Getting Started with Vault] - -* https://www.vaultproject.io/docs[HashiCorp Vault Documentation] - -Spring Vault provides client-side support for accessing, storing and revoking secrets. -With https://www.vaultproject.io[HashiCorp's Vault] you have a central place to -manage external secret data for applications across all environments. -Vault can manage static and dynamic secrets such as application data, -username/password for remote applications/resources and provide credentials -for external services such as MySQL, PostgreSQL, Apache Cassandra, Consul, AWS and more. - -[[requirements]] -== Requirements - -Spring Vault 2.x binaries requires JDK level 8.0 and above, and https://spring.io/docs[Spring Framework] {springVersion} and above. - -In terms of Vault, https://www.vaultproject.io/[Vault] at least v0.9.6. - -[[get-started:additional-help]] -== Additional Help Resources - -Learning a new framework is not always straight forward. In this section, we try to provide what we think is an easy to follow guide for starting with Spring Vault module. However, if you encounter issues or you are just looking for advice, feel free to use one of the links below: - -[[get-started:help]] -=== Support - -There are a few support options available: - -[[get-started:help:community]] -==== Community Forum - -Post questions regarding Spring Vault on https://stackoverflow.com/questions/tagged/spring-vault[Stackoverflow] to share information and help each other. Note that registration is needed *only* for posting. - -[[get-started:help:professional]] -==== Professional Support - -Professional, from-the-source support, with guaranteed response time, is available from https://pivotal.io/[Pivotal Software, Inc.], the company behind Spring Vault and Spring. - -[[get-started:up-to-date]] -=== Following Development - -For information on the Spring Vault source code repository, nightly builds and snapshot artifacts please see the https://projects.spring.io/spring-vault/[Spring Vault homepage]. You can help make Spring Vault best serve the needs of the Spring community by interacting with developers through the Community on https://stackoverflow.com/questions/tagged/spring-vault[Stackoverflow]. If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Vault issue https://github.com/spring-projects/spring-vault/issues[tracker]. To stay up to date with the latest news and announcements in the Spring ecosystem, subscribe to the Spring Community https://spring.io[Portal]. Lastly, you can follow the Spring https://spring.io/blog[blog ]or the project team on Twitter (https://twitter.com/springcentral[SpringCentral]). diff --git a/src/main/asciidoc/reference/vault.adoc b/src/main/asciidoc/reference/vault.adoc deleted file mode 100644 index 07de18f5..00000000 --- a/src/main/asciidoc/reference/vault.adoc +++ /dev/null @@ -1,36 +0,0 @@ -[[vault.core]] -= Vault support - -The Vault support contains a wide range of features which are summarized below. - -* Spring configuration support using Java based @Configuration classes -* `VaultTemplate` helper class that increases productivity performing common -Vault operations. Includes integrated object mapping between Vault responses and POJOs. - -For most tasks, you will find yourself using `VaultTemplate` that leverages the -rich communication functionality. `VaultTemplate` is the place to look for -accessing functionality such as reading data from Vault or issuing -administrative commands. `VaultTemplate` also provides callback methods so that it is easy for you to -get a hold of the low-level API artifacts such as `RestTemplate` to communicate -directly with Vault. - - -include::dependencies.adoc[] - -include::getting-started.adoc[] - -include::imperative-template.adoc[] - -include::vault-secret-engines.adoc[] - -include::reactive-template.adoc[] - -include::propertysource.adoc[] - -include::vault-repositories.adoc[] - -include::client-support.adoc[] - -include::authentication.adoc[] - -include::misc.adoc[]