Merge pull request #13 from HomeOfTheWizard/develop

prepare release 1.1.3

docs/_config.yml

@@ -20,6 +20,7 @@
 
 title: vault-maven-plugin
 logo: "/assets/images/Vault-Maven-Plugin-colored.png"
+favicon_ico: "assets/images/favicon.png"
 email: [email protected]
 description: >- # this means to ignore newlines until "baseurl:"
   Vault Maven Plugin is a plugin that allows fetching secrets from vault during the maven build of your project.

docs/index.markdown

@@ -1,6 +1,7 @@
 ---
 layout: page
 title: About Vault Maven Plugin
+nav_order: 1
 ---
 
 # No need to store your credentials locally anymore 
@@ -34,35 +35,42 @@ or some encryption keys for securing the communication itself.
 [Hashicorp Vault](https://www.vaultproject.io/) allows us to securely store those secrets, and share them with necessary counterparts.
 Those counterparts may be developers who want to run the application on their local environments, or the application's different execution environments (Test, Production, CI ect...)  
 
-{: .warning }
 Organisations that has a Hashicorp Vault, in general, are already using a cloud based architecture.    
 Hence, already have some ways for the application's credentials to be fetched automatically from Vault, instead of storing them locally on each environment separately.  
 Ex: Orchestrated Container environments like Kubernetes,  
 or CI tools like Jenkins have a Vault plugin to do so.  
-The idea behind using those tools, is to fetch the credentials in advance, to speed up the start time of your application.
 
-But it may be the case that : 
-* Your enterprise's IT infrastructure does not have such tools yet,  
-* It may be in a transition phase, or maybe some legacy applications that are not compatible with such tools.  
-* For some reason even if you have such tools, the Vault plugins are not available.   
-* Such tools are not available on developers' local environments,  
-where lots of enterprises still provide Windows PCs without a Docker or K8s.
-
-This plugin aims to help those cases :santa:.  
-
-**But not only!** There are some cases where we don't want to store any configuration related to Vault in any execution environment, but only credentials to access it.    
-For example batch applications may prefer to tradeoff for the simplicity of configuration over the speed of startup :massage_man:.
+{: .warning }
+All those plugins/tools, all require you to declare your secrets on their own configuration file, causing duplication among different config files.
 
 {: .important }
-In short, this plugin gives you a simpler and more secure way to manage your secrets.  
-Everything, except the credentials to vault, can be stored on version control.   
+By using this plugin to fetch your secrets, you can unify all your configuration and secrets declaration in a single file, the pom.xml.  
+So everything, except the credentials to vault, can be stored on version control.  
 And if you use Github PAT authentication, even that can be on version control!  
 
 {: .warning }
-Just keep in mind that fetching the secrets in time of execution has an implication of I/O, network and additional time of startup. 
+The idea behind using those plugins/tools, like jenkins Vault plugin or the Vault Agent that is used to save your secrets on K8s, is to fetch the credentials in advance, so that they are available right away at the start time of your application, making it to boot faster.
+
+{: .important }
+But there are some cases, for example batch applications, where we may prefer to tradeoff for the simplicity of configuration over the speed of startup :massage_man:.  
+Just keep in mind that fetching the secrets in time of execution has an implication of I/O, network and additional time of startup.  
+
+But still If you are sensible to the boot time of your application, lets say you have a web scaling app running on K8s,  
+You can still use this plugin, still with a single definition of your secrets in the pom.xml, to create your secret.yaml for K8s at its deployment time instead of the boot time. :wink:   
+
+
+But it may also be the case that : 
+* Your enterprise's IT infrastructure does not have such tools yet,  
+* It may be in a transition phase, or maybe some legacy applications that are not compatible with such tools.  
+* For some reason even if you have such tools, the Vault plugins are not available.   
+* **Such tools are not available on developers' local environments,**  
+where lots of enterprises still provide Windows PCs without a Docker or K8s.
+
+This plugin aims to help all those cases :santa:.
+
 
 ## Example use cases
-Some CI tools that already working with maven, for example maven plugins, like liquibase or sonar-scanner plugins,    
+Some CI tools that already working with maven, for example liquibase or sonar-scanner which both have maven plugins,    
 are the best suite for using the Vault Maven Plugin.  
 
 Java applications that use maven to build/package can also profit from it.     

docs/usage.markdown

@@ -1,6 +1,7 @@
 ---
 layout: page
 title: How to use it
+nav_order: 2
 ---
 
 ## How to configure it

docs/use-cases/appTypes.markdown

@@ -0,0 +1,288 @@
+---
+layout: page
+title: By Application Type
+parent: Practical use cases
+---
+
+# 1. Other maven plugins
+Many CI tools are used via maven plugins for the convenience of not having to manage executables.
+Sonar scanner and liquibase are one of them.
+The example below shows you how to fetch the credentials necessary to use those plugins, via the vault-maven-plugin.
+
+Let's say you are using liquibase and have the following pom.xml
+```xml
+<build>
+    <plugins>
+        <plugin>
+            <groupId>org.liquibase</groupId>
+            <artifactId>liquibase-maven-plugin</artifactId>
+            <version>4.6.1</version>
+            <executions>
+                <execution>
+                    <phase>compile</phase>
+                    <goals>
+                        <goal>update</goal>
+                    </goals>
+                </execution>
+            </executions>
+            <configuration>
+                <propertyFile>target/classes/liquibase.properties</propertyFile>
+            </configuration>
+        </plugin>
+    </plugins>
+    <resources>
+        <resource>
+            <directory>src/main/resources</directory>
+            <filtering>true</filtering>
+            <includes>
+                <include>*.properties</include>
+            </includes>
+        </resource>
+    </resources>
+</build>
+``` 
+
+Your property file might be like below.
+```properties
+changeLogFile=src/main/resources/liquibase/.../changelog.xml
+url=...
+database=...
+username=...
+password=${database.password}
+```
+
+Usually the property `database.password` if given to maven as system property or environment variables.
+
+If you don't have a tool that will fetch the secret and create the environment variable for you, you can use the maven vault plugin.
+You just add the following to fetch the secrets and inject them as properties in maven.
+```xml
+<plugin>
+    <groupId>com.homeofthewizard</groupId>
+    <artifactId>vault-maven-plugin</artifactId>
+    <version>1.1.2-SNAPSHOT</version>
+    <executions>
+        <execution>
+            <id>pull</id>
+            <phase>initialize</phase>
+            <goals>
+                <goal>pull</goal>
+            </goals>
+        </execution>
+    </executions>
+    <configuration>
+        <servers>
+            <server>
+                <url>https://your-vault-host</url>
+                <token>XXXXXXX</token>
+                <paths>
+                    <path>
+                        <name>secret/data/some-app</name>
+                        <mappings>
+                            <mapping>
+                                <key>vaultSecretKey</key>
+                                <property>database.password</property>
+                            </mapping>
+                        </mappings>
+                    </path>
+                </paths>
+            </server>
+        </servers>
+    </configuration>
+</plugin>
+```
+
+and Voilà! :tada:  
+When you execute your liquibase plugin `mvn clean compile`,  
+the vault plugin will fetch the secrets,  
+the resource plugin will put it in the property file by replacing the placeholder,  
+then the liquibase plugin will run using the secret!  
+
+No need to handle secrets in the execution environment anymore ! :massage_man:  
+You only need to give set the execution environment's credentials to access Vault!
+
+# 2. Maven Applications  
+
+{: .warning }
+As already mentionned [here](https://homeofthewizard.github.io/vault-maven-plugin/#example-use-cases), if your application is using Spring-Cloud,  
+You should use [Spring Cloud Vault](https://spring.io/projects/spring-cloud-vault) instead of this maven plugin.
+
+Many Java application like Spring applications externalise their configurations in a property file,  
+as recommended by the [12 factor app](https://12factor.net/config).    
+Secrets are part of those configuration files. The configuration file can be stored in version control.    
+But a good security practice is not to store the secrets on version control.    
+Hence, the secrets are fetched generally from environment variables on the system where we run the app.  
+
+You can do the following to fetch the secrets from vault via the Vault Plugin,  
+then run your application with maven, and your secrets will be injected as system properties.    
+
+Let's say you are using Spring and have the following `application.properties`   
+```properties
+app.secret=${APPLICATION_SECRET}
+```  
+
+You can define the following in your pom.xml to fetch the credential for `APPLICATION_SECRET`.  
+```xml
+<plugins>
+    <plugin>
+        <groupId>com.homeofthewizard</groupId>
+        <artifactId>vault-maven-plugin</artifactId>
+        <version>1.1.2-SNAPSHOT</version>
+        <executions>
+            <execution>
+                <id>pull</id>
+                <phase>initialize</phase>
+                <goals>
+                    <goal>pull</goal>
+                </goals>
+            </execution>
+        </executions>
+        <configuration>
+            <servers>
+                <server>
+                    <url>https://your-vault-host</url>
+                    <token>XXXXXXX</token>
+                    <paths>
+                        <path>
+                            <name>secret/data/some-app</name>
+                            <mappings>
+                                <mapping>
+                                    <key>vaultSecretKey</key>
+                                    <property>APPLICATION_SECRET</property>
+                                </mapping>
+                            </mappings>
+                        </path>
+                    </paths>
+                </server>
+            </servers>
+            <outputMethod>SystemProperties</outputMethod>
+        </configuration>
+    </plugin>
+</plugins>
+```
+
+The above code will first fetch the secrets from vault with the vault-plugin, then they will be added to Maven's system properties (`<outputMethod>` configuration).    
+After that you can run your java app with either [exec-maven-plugin](http://www.mojohaus.org/exec-maven-plugin/usage.html) or the [spring-boot-maven-plugin](https://docs.spring.io/spring-boot/docs/current/maven-plugin/reference/htmlsingle/)
+By running your application with maven, maven's system properties will be shared with your application.  
+
+<p><img src="../assets/images/old%20vs%20new%20way.png"/></p>
+
+### In case you have a Non-Spring Java application
+Spring boot manages system properties and environment variables differently that the standard way.  
+You will find here a [blog post](https://homeofthewizard.github.io/secrets-in-java) that explains how the two works in java, and [here](https://www.baeldung.com/spring-boot-properties-env-variables) a post explaining spring's difference.  
+But in short, Spring allows you to access both via the same API (using placeholders like `${myVar}`). So for a spring application that requires environment variables, we can emulate them by injecting System properties instead.    
+
+For a non Spring application that requires environment variables, we cannot do that, we need to give the JVM real environment variables.  
+Let's say you have a simple java application, with a main class like this
+```java
+package org.example;
+
+public class Main {
+    public static void main(String[] args) {
+        System.out.println("Env variable fetched: "+ System.getenv("ENV_VAR_SECRET"));
+    }
+}
+```
+
+you have the following pom.xml
+```xml
+<plugins>
+    <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-jar-plugin</artifactId>
+        <configuration>
+            <archive>
+                <manifest>
+                    <addClasspath>true</addClasspath>
+                    <mainClass>org.example.Main</mainClass>
+                </manifest>
+            </archive>
+        </configuration>
+    </plugin>
+</plugins>
+```
+
+This app is using some environment variables given by its execution environment  
+when run via `java -jar myApp.jar`.
+
+Now if we use the Vault Maven Plugin, we can fetch the secret, run the app via maven, and the env variable will be injected directly.  
+By adding the followings to your pom.xml like so:
+```xml
+<plugins>
+    <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-jar-plugin</artifactId>
+        <configuration>
+            <archive>
+                <manifest>
+                    <addClasspath>true</addClasspath>
+                    <mainClass>org.example.Main</mainClass>
+                </manifest>
+            </archive>
+        </configuration>
+    </plugin>
+    <plugin>
+        <groupId>com.homeofthewizard</groupId>
+        <artifactId>vault-maven-plugin</artifactId>
+        <version>1.1.2-SNAPSHOT</version>
+        <executions>
+            <execution>
+                <id>pull</id>
+                <phase>initialize</phase>
+                <goals>
+                    <goal>pull</goal>
+                </goals>
+            </execution>
+        </executions>
+        <configuration>
+            <servers>
+                <server>
+                    <url>https://your-vault-host</url>
+                    <token>XXXXX</token>
+                    <paths>
+                        <path>
+                            <name>secret/data/myJavaApp</name>
+                            <mappings>
+                                <mapping>
+                                    <key>secretKey</key>
+                                    <property>mavenPropertyForSecret</property>
+                                </mapping>
+                            </mappings>
+                        </path>
+                    </paths>
+                </server>
+            </servers>
+        </configuration>
+    </plugin>
+    <plugin>
+        <groupId>org.codehaus.mojo</groupId>
+        <artifactId>exec-maven-plugin</artifactId>
+        <version>1.2.1</version>
+        <configuration>
+            <executable>java</executable>
+            <environmentVariables>
+                <ENV_VAR_SECRET>${mavenPropertyForSecret}</ENV_VAR_SECRET>
+            </environmentVariables>
+            <arguments>
+                <argument>-classpath</argument>
+                <classpath />
+                <argument>org.example.Main</argument>
+            </arguments>
+        </configuration>
+    </plugin>
+</plugins>
+```
+And Voilà! :tada:  
+Now you just need to run `mvn vault:pull exec:exec`  
+The only thing to provide is the token to authenticate to Vault server (`<token>XXXXX</token>`).  
+Isn't that magical ? :mage:
+
+# 3. Application that does not use Maven
+Many developers use .env files to manage environment variables on their localhost.  
+It may be the case even on production for application that do not have tools to fetch the secrets directly from a secure shared place like Vault.      
+
+If that is the case, the plugin can generate a .env file for you.    
+The configuration `<outputMethod>EnvFile</outputMethod>` allows this.    
+
+Then you can inject it with [dotenv-java](https://github.com/cdimascio/dotenv-java) for example.    
+
+There are also IntelliJ plugins that help you inject secrets via .env files before running/debugging the application in your local environment.