Skip to content

Commit

Permalink
[New Docs PR] Integration Docs (#4566)
Browse files Browse the repository at this point in the history
  • Loading branch information
@arjav-desai
arjav-desai authored Jul 19, 2022
1 parent f06f877 commit 3d43ae4
Show file tree
Hide file tree
Showing 14 changed files with 444 additions and 1,234 deletions.
70 changes: 70 additions & 0 deletions docs/includes/oci.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
///////////////////////////////////////////////////////////////////////////////

Copyright (c) 2022 Oracle and/or its affiliates.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

///////////////////////////////////////////////////////////////////////////////
ifndef::rootdir[:rootdir: {docdir}/..]
== Resolving javax and jakarta package compatibility issue with OCI SDK
With Helidon 3, we are now implementing the MicroProfile 5 Platform and selected Jakarta EE 9.1 specifications. We are also going away from javax.* packages and fully embracing jakarta.* package.
However, the current release 2.35.0 of OCI Java SDK is still using javax.* packages which created compatibility issues e.g. Helidon 3 uses JAX-RS 3.0.0 (jakarta package names) and the corresponding Jersey implementation. OCI SDK 2.35.0 uses JAX-RS Client 2.1.6 (javax package names) and the corresponding Jersey implementation. Therefore, the OCI SDK is incompatible with Helidon 3 applications and any application that uses JAX-RS 3. We have filed an issue with OCI SDK team, see https://github.com/oracle/oci-java-sdk/issues/371 for details on this.
OCI SDK team has provided us with `shaded` jar as workaround as mentioned in the issue. However, this jar is not available in maven-central as of now. See issue https://github.com/oracle/oci-java-sdk/issues/410 for details on that, so user will have to do manual setup/install of this `shaded` jar. You only have to do this once per version of SDK.
* Download OCI SDK from https://github.com/oracle/oci-java-sdk/releases/download/v2.35.0/oci-java-sdk-2.35.0.zip
* Unzip the SDK
[source,bash]
----
unzip -j -p oci-java-sdk-2.35.0.zip shaded/lib/oci-java-sdk-full-shaded-2.35.0.jar > oci-java-sdk-shaded-full-2.35.0.jar
----
* Install `shaded` jar in your local maven repo, see https://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html
[source,bash]
----
mvn -N org.apache.maven.plugins:maven-install-plugin:install-file -Dfile=oci-java-sdk-shaded-full-2.35.0.jar -DlocalRepositoryPath="~/.m2/repository" -DgroupId=com.oracle.oci.sdk -DartifactId=oci-java-sdk-shaded-full -Dversion=2.35.0 -Dpackaging=jar
----
Now, when you want to use modules from OCI SDK in your application, instead of using individual modules as defined in our OCI integration documentation, you need to use `full shaded` jar.
[source,xml]
----
<dependency>
<groupId>com.oracle.oci.sdk</groupId>
<artifactId>oci-java-sdk-shaded-full</artifactId>
<version>2.35.0</version>
</dependency>
----
Since the `full shaded` jar doesn't bring in its transitive dependencies, you will also need to define following dependencies in your application so that it works at runtime.
[source,xml]
----
<dependency>
<groupId>org.bouncycastle</groupId>
<artifactId>bcpkix-jdk15on</artifactId>
<version>1.70</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-jdk14</artifactId>
<version>1.7.32</version>
<scope>runtime</scope>
</dependency>
----
Please refer to our link:{helidon-github-tree-url}/examples/integrations/oci[OCI SDK Usage Examples] to see this in action.
211 changes: 101 additions & 110 deletions docs/mp/vault.adoc → docs/mp/integrations/hcv.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,153 +16,140 @@

///////////////////////////////////////////////////////////////////////////////
= Vault
:description: Helidon Vault integration
:keywords: vault
:feature-name: Vault
:rootdir: {docdir}/..
= HashiCorp Vault
:description: Helidon HashiCorp Vault integration
:keywords: vault, hashicorp
:feature-name: HashiCorp Vault
:rootdir: {docdir}/../..
include::{rootdir}/includes/mp.adoc[]
HashiCorp Vault is a commonly used Vault in many microservices. The APIs are REST-based and Helidon implements them using reactive client.
Vault integration supports the following:
* *Secret Engines*: Key/Value version 2, Key/Value version 1, Cubbyhole, PKI, Transit, Database
* *Authentication Methods*: Token, Kubernetes (k8s), AppRole
* *Other Sys Operations and Configurations*
== Experimental
WARNING: Helidon Vault support is still experimental and not intended for production use. APIs and features have not yet been fully tested and are subject to change.
== Sys Operations
Each of these features is implemented as a separate module, with the Vault class binding them together. In Helidon MP, with injection, this binding is done automatically, and you can simply inject your favorite secret engine.
In addition to these features, Vault itself can be authenticated as follows:
== ToC
* Token authentication - token is configured when connecting to Vault
* AppRole authentication - AppRole ID and secret ID are configured, integration exchanges these for a temporary token that is used to connect to Vault
* K8s authentication - the k8s JWT token is discovered on current node and used to obtain a temporary token that is used to connect to Vault
== Extensibility
- <<Overview, Overview>>
- <<maven-coordinates, Maven Coordinates>>
- <<Usage, Usage>>
- <<Examples, Examples>>
- <<Local-Testing, Local Testing>>
- <<References, References>>
New secret engines and authentication methods can be implemented quite easily, as the integration is based on service providers (using ServiceLoader). This gives us (or you, as the users) the option to add new secret engines and/or authentication methods without adding a plethora of methods to the Vault class.
See the following SPIs:
== Overview
[source,listing]
----
io.helidon.integrations.vault.spi.AuthMethodProvider
io.helidon.integrations.vault.spi.SecretsEngineProvider
io.helidon.integrations.vault.spi.SysProvider
io.helidon.integrations.vault.spi.VaultAuth
io.helidon.integrations.vault.spi.InjectionProvider
----
== Modules
HashiCorp Vault is a commonly used Vault in many microservices. The APIs are REST-based and Helidon implements them using reactive client.
The following is a list of maven coordinates of all Vault modules available:
include::{rootdir}/includes/dependencies.adoc[]
[source,xml]
----
<dependencies>
<dependency>
<groupId>io.helidon.integrations.vault</groupId>
<artifactId>helidon-integrations-vault</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.auths</groupId>
<artifactId>helidon-integrations-vault-auths-token</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.auths</groupId>
<artifactId>helidon-integrations-vault-auths-approle</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.auths</groupId>
<artifactId>helidon-integrations-vault-auths-k8s</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.secrets</groupId>
<artifactId>helidon-integrations-vault-secrets-kv1</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.secrets</groupId>
<artifactId>helidon-integrations-vault-secrets-kv2</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.secrets</groupId>
<artifactId>helidon-integrations-vault-secrets-cubbyhole</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.secrets</groupId>
<artifactId>helidon-integrations-vault-secrets-transit</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.secrets</groupId>
<artifactId>helidon-integrations-vault-secrets-database</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.sys</groupId>
<artifactId>helidon-integrations-vault-sys</artifactId>
</dependency>
</dependencies>
<dependency>
<groupId>io.helidon.integrations.vault</groupId>
<artifactId>helidon-integrations-vault-cdi</artifactId>
</dependency>
----
To use Vault integration in MP, the following module must be added, as it enables injection of all features:
The following is a list of maven coordinates of all Vault modules available:
[source,xml]
----
<dependency>
<groupId>io.helidon.integrations.vault</groupId>
<artifactId>helidon-integrations-vault-cdi</artifactId>
<groupId>io.helidon.integrations.vault.auths</groupId>
<artifactId>helidon-integrations-vault-auths-token</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.auths</groupId>
<artifactId>helidon-integrations-vault-auths-approle</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.auths</groupId>
<artifactId>helidon-integrations-vault-auths-k8s</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.secrets</groupId>
<artifactId>helidon-integrations-vault-secrets-kv1</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.secrets</groupId>
<artifactId>helidon-integrations-vault-secrets-kv2</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.secrets</groupId>
<artifactId>helidon-integrations-vault-secrets-cubbyhole</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.secrets</groupId>
<artifactId>helidon-integrations-vault-secrets-transit</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.secrets</groupId>
<artifactId>helidon-integrations-vault-secrets-database</artifactId>
</dependency>
<dependency>
<groupId>io.helidon.integrations.vault.sys</groupId>
<artifactId>helidon-integrations-vault-sys</artifactId>
</dependency>
----
Configuration to connect to Vault.
== Usage
Vault integration supports the following:
* *Secret Engines*: Key/Value version 2, Key/Value version 1, Cubbyhole, PKI, Transit, Database
* *Authentication Methods*: Token, Kubernetes (k8s), AppRole
* *Other Sys Operations and Configurations*
. Authenticating using Token:
+
Each of these features is implemented as a separate module, with the Vault class binding them together. In Helidon MP, with injection, this binding is done automatically, and you can simply inject your favorite secret engine.
The following classes can be injected into any CDI bean (if appropriate module is on the classpath):
* Kv2Secrets - Key/Value Version 2 Secrets (versioned secrets, default)
* Kv1Secrets - Key/Value Version 1 Secrets (un-versioned secrets, legacy)
* CubbyholeSecrets - Cubbyhole secrets (token bound secrets)
* DbSecrets - Database secrets (for generating temporary DB credentials)
* PkiSecrets - PKI secrets (for generating keys and X.509 certificates)
* TransitSecrets - Transit operations (encryption, signatures, HMAC)
* AppRoleAuth - AppRole authentication method (management operations)
* K8sAuth - Kubernetes authentication method (management operations)
* TokenAuth - Token authentication method (management operations)
* Sys - System operations (management of Vault - enabling/disabling secret engines and authentication methods)
* *Rx - reactive counterparts to the classes defined above, usually not recommended in CDI, as it is a blocking environment
In addition to these features, Vault itself can be authenticated as follows:
* Token authentication - token is configured when connecting to Vault
[source,properties]
----
vault.address=http://localhost:8200
vault.token=my-token
----
+
. Authenticating using AppRole:
+
* AppRole authentication - AppRole ID and secret ID are configured, integration exchanges these for a temporary token that is used to connect to Vault
[source,properties]
----
vault.auth.app-role.role-id=app-role-id
vault.auth.app-role.secret-id=app-role-secret-id
----
+
. Authenticating using Kubernetes:
+
* K8s authentication - the k8s JWT token is discovered on current node and used to obtain a temporary token that is used to connect to Vault
[source,properties]
----
vault.auth.k8s.token-role=my-role <1>
----
<1> The token role must be configured in Vault
The following classes can be injected into any CDI bean (if appropriate module is on the classpath):
=== Extensibility
* Kv2Secrets - Key/Value Version 2 Secrets (versioned secrets, default)
* Kv1Secrets - Key/Value Version 1 Secrets (un-versioned secrets, legacy)
* CubbyholeSecrets - Cubbyhole secrets (token bound secrets)
* DbSecrets - Database secrets (for generating temporary DB credentials)
* PkiSecrets - PKI secrets (for generating keys and X.509 certificates)
* TransitSecrets - Transit operations (encryption, signatures, HMAC)
* AppRoleAuth - AppRole authentication method (management operations)
* K8sAuth - Kubernetes authentication method (management operations)
* TokenAuth - Token authentication method (management operations)
* Sys - System operations (management of Vault - enabling/disabling secret engines and authentication methods)
* *Rx - reactive counterparts to the classes defined above, usually not recommended in CDI, as it is a blocking environment
New secret engines and authentication methods can be implemented quite easily, as the integration is based on service providers (using ServiceLoader). This gives us (or you, as the users) the option to add new secret engines and/or authentication methods without adding a plethora of methods to the Vault class.
See the following SPIs:
== Usage
[source,listing]
----
io.helidon.integrations.vault.spi.AuthMethodProvider
io.helidon.integrations.vault.spi.SecretsEngineProvider
io.helidon.integrations.vault.spi.SysProvider
io.helidon.integrations.vault.spi.VaultAuth
io.helidon.integrations.vault.spi.InjectionProvider
----
== Examples
The following example shows usage of Vault to encrypt a secret using the default Vault configuration (in a JAX-RS resource):
Expand Down Expand Up @@ -529,7 +516,7 @@ public class TransitResource {
<9> Verify HMAC.
<10> Verify signature.
== Local testing
== Local Testing [[Local-Testing]]
Vault is available as a docker image, so to test locally, you can simply:
Expand All @@ -538,4 +525,8 @@ Vault is available as a docker image, so to test locally, you can simply:
docker run -e VAULT_DEV_ROOT_TOKEN_ID=my-token -d --name=vault -p8200:8200 vault
----
This will create a Vault docker image, run it in background and open it on localhost:8200 with a custom root token my-token, using name vault. This is of course only suitable for local testing, as the root token has too many rights, but it can be easily used with the examples below.
This will create a Vault docker image, run it in background and open it on `localhost:8200` with a custom root token my-token, using name vault. This is of course only suitable for local testing, as the root token has too many rights, but it can be easily used with the examples below.
== References
* link:{helidon-github-tree-url}/examples/integrations/vault[Hashicorp Vault Usage Examples]
Loading

0 comments on commit 3d43ae4

Please sign in to comment.