This plugin adds a new build step and build wrapper that are used to read/write/delete Key/Value data from/to specified HashiCorp [Consul](https://www.consul.io/) servers. or clusters. # Use Case \* You have a build that needs to read data from Consul Key/Value store and use those data later in the build or even in downstream parameterized builds. \* You have a build that needs to deploy, and part of that deployment is to configure Consul Key/Value settings. # Build Wrapper Usage The Consul K/V Builder Plugin can be used as a Build Wrapper, so it is added to the project configuration by selecting under the "Build Environment" checkboxes. As a build wrapper, it can be added multiple times to read multiple Key/Value pairs. ![](docs/images/BuildWrapper.png){width="800"} # Build Step Usage The Consul K/V Builder Plugin can also be used as a Build Step, so it is added to the project configuration via the “Add Build Step” button towards the bottom of the project configuration window. As a build step, it can be added multiple times to read/write/delete multiple Key/Value pairs. ![](docs/images/build-step.png){width="200"} ### To read data from Consul, you configure the build step with the following settings: | Field name | Description | |------------------|------------------------------------------------------------------------| | ACL Token | optional, supplies the Consul ACL entry ID that is used to access data | | Host URL | URL of the Consul server/cluster | | Key | Key used to store and lookup data in Consul | | ENV Variable Key | Key used to store the data into a Jenkins build environment variable | ![](docs/images/read.png){width="800"} ### To write Consul data, you must expose the "Advanced" settings. | Field name | Description | |--------------------|------------------------------------------------------------------------------------------------| | Request Mode | Set to write | | Debug Mode | Optionally enable debug mode for additional logging | | Value | Value to write to Consul with the specified key from above | | API URL Override | optional, used to specify the non-default URI for the Consul server RESTful HTTP API endpoints | | Connection timeout | optional, used to specify connection timeout, default is 10 seconds | | Response timeout | optional, used to specify response timeout, default is 30 seconds | ![](docs/images/write.png){width="800"} Handy Hint This example shows the use of a build parameter *acl\_token* ### To delete Consul data, you must expose the "Advanced" settings, and choose delete. | Field name | Description | |--------------------|------------------------------------------------------------------------------------------------| | Request Mode | Set to delete | | Debug Mode | Optionally enable debug mode for additional logging | | Value | N/A | | API URL Override | optional, used to specify the non-default URI for the Consul server RESTful HTTP API endpoints | | Connection timeout | optional, used to specify connection timeout, default is 10 seconds | | Response timeout | optional, used to specify response timeout, default is 30 seconds | ![](docs/images/delete.png){width="800"} # Pipeline Usage This plugin can be used in Jenkins Pipeline scripts with "wrap" and "step" constructs: ![](docs/images/Pipeline_step_wrap.png){width="800"} ![](docs/images/pipeline-read-wrap.png){height="150"} # Features   ### Build Wrapper \* Read Key/Value data from Consul server/cluster, write to ENV variable ### Build Step \* Read Key/Value data from Consul server/cluster, write to ENV variable \* Write Key/Value data to Consul server/cluster \* Delete Key/Value data from Consul server/cluster \* Optional debug mode for additional logging \* Supports Consul ACL ids, including using build parameters for ACL ids \* Optional override Consul RESTful HTTP API URI \* Optional override connection timeout \* Optional override response timeout ### Global Settings \* Set global settings that can be leveraged in jobs ![](docs/images/global-settings.png){width="800"} # Changelog ### Version 1.0.6 (May 11 2016) \* Initial release ### Version 2.0.4 (June 3 2016) \* Added Build Wrapper and Jenkins Pipeline compatibility ### Version 2.0.7 (September 20 2016) \* Added build/run failure model settings \* Added listener error settings ### Version 2.0.12 (October 3 2016) \* Added global Consul settings that can used/ignored at the job-config level ### Version 2.0.13 (November 2 2016) \* Attempted to Fix issue: . Pipeline Steps implementing the SimpleBuildStep interface cannot write data to run-level environment variables. The workaround may be to write a single-value custom step that returns a string, or use the wrapper to set a local var in the node. **Pipeline Wrapper Workarounds** ``` syntaxhighlighter-pre node('master') { TEST_KEY = '' wrap([$class: 'ConsulKVReadWrapper', reads: [[aclToken: '', apiUri: '', debugMode: 'ENABLED', envKey: 'test_key', hostUrl: '', key: 'test/test-key']]]) { echo env.test_key TEST_KEY = env.test_key } echo TEST_KEY } //or for a global var: import groovy.transform.Field @Field String TEST_KEY node('master') { wrap([$class: 'ConsulKVReadWrapper', reads: [[aclToken: '', apiUri: '', debugMode: 'ENABLED', envKey: 'test_key', hostUrl: '', key: 'test/test-key']]]) { echo env.test_key TEST_KEY = env.test_key } echo TEST_KEY } node ('master') { echo TEST_KEY } //Use Wrapper to get multiple key/values node ('master') { wrap([$class: 'ConsulKVReadWrapper', reads: [[aclToken: '', apiUri: '', debugMode: 'ENABLED', envKey: 'test_key', hostUrl: '', key: 'test/test-key'], [aclToken: '', apiUri: '', debugMode: 'ENABLED', envKey: 'test_key2', hostUrl: '', key: 'test/test-key'], [aclToken: '', apiUri: '', debugMode: 'ENABLED', envKey: 'test_key3', hostUrl: '', key: 'test/test-key']]]) { echo env.test_key echo env.test_key2 echo env.test_key3 } } ```