From ad434cd77e4e9ff08dfc1c5db55c8fb6a354dce0 Mon Sep 17 00:00:00 2001 From: Keith Manning Date: Wed, 8 Jul 2020 16:59:44 -0400 Subject: [PATCH 1/7] Explain the importance of order --- README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/README.md b/README.md index f49baa57..a113e01c 100644 --- a/README.md +++ b/README.md @@ -130,6 +130,55 @@ This library was intended to be customizable and extendable - if you don't find 6. Call your `init()` method in your Jenkinsfile before calling `build()` on your pipeline. 7. If your plugin could be useful to others, feel free to put in a Pull Request. +# Plugin Order + +Plugins often work by wrapping your stages in Jenkinfile DSL blocks. If multiple plugins wrap your stages simultaneously, the order in which they are wrapped can be very important. On the whole, terraform-pipeline strives to preserve and maintain the order you initialize the plugins, so that the corresponding Jenkinsfile DSL blocks execute predictably. + +Take the following example: + +`ParameterStoreBuildWrapperPlugin` wraps your pipeline stages with the Jenkinsfile DSL `withAWSParameterStore { }` and can inject environment variables into your stage from ParameterStore key/value pairs. `WithAwsPlugin` wraps your pipeline stages with the Jenkinsfile DSL `withAws { }` and can execute your stage under the context of an IAM role that's defined by an environment variable. The two plugins can be used together - an IAM role can be defined in ParameterStore and translated to an environment variable `AWS_ROLE_ARN`, and that environment variable can in turn be used to configure the IAM role assumed by `WithAwsPlugin`. + +Using terraform-pipeline, you might initialize your pipeline as such: + +``` +WithAwsPlugin.init() // Wrap everything before this in withAWS { } +ParameterStoreBuildWrapperPlugin.init() // Wrap everything before this in withAWSParameterStore { } +``` + +The above would generate roughly the following Jenkinsfile DSL: + +``` +... + + // Set a key value pair in ParameterStore so that AWS_ROLE_ARN= + withAWSParameterStore { + ... + // AWS_ROLE_ARN is visible as an environment variable, and passed along to withAWS + withAWS(role: AWS_ROLE_ARN) { + ... + } + } +... +``` + +The order in which the plugins were initialized determined the order of the Jenkinsfile DSL. Had the plugins been initialized in the reverse order, the Jenkinsfile DSL would likewise be reversed, and would lead to an undesireable outcome. + +``` +ParameterStoreBuildWrapperPlugin.init() // Wrap everything before this in withAWSParameterStore { } +WithAwsPlugin.init() // Wrap everything before this in withAWS { } +... + + // AWS_ROLE_ARN is not defined - withAWS does nothing + withAWS(role: ) { + ... + // AWS_ROLE_ARN= is defined in ParameterStore, but it's too late + withAWSParameterStore { + ... + } + } +... +``` + # Control Where Your Jobs Are Run By default, the pipeline jobs are not assigned to a particular Jenkins slave label. If you want to tie your pipeline to particular Jenkins slave label, you can do so with the following line of code: From c8d2947e1bf2d30a50964a31fd27ad2c4829d143 Mon Sep 17 00:00:00 2001 From: Keith Manning Date: Wed, 8 Jul 2020 17:02:25 -0400 Subject: [PATCH 2/7] Fix formatting --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a113e01c..d82843a2 100644 --- a/README.md +++ b/README.md @@ -136,7 +136,9 @@ Plugins often work by wrapping your stages in Jenkinfile DSL blocks. If multipl Take the following example: -`ParameterStoreBuildWrapperPlugin` wraps your pipeline stages with the Jenkinsfile DSL `withAWSParameterStore { }` and can inject environment variables into your stage from ParameterStore key/value pairs. `WithAwsPlugin` wraps your pipeline stages with the Jenkinsfile DSL `withAws { }` and can execute your stage under the context of an IAM role that's defined by an environment variable. The two plugins can be used together - an IAM role can be defined in ParameterStore and translated to an environment variable `AWS_ROLE_ARN`, and that environment variable can in turn be used to configure the IAM role assumed by `WithAwsPlugin`. +* `ParameterStoreBuildWrapperPlugin` wraps your pipeline stages with the Jenkinsfile DSL `withAWSParameterStore { }` and can inject environment variables into your stage from ParameterStore key/value pairs. +* `WithAwsPlugin` wraps your pipeline stages with the Jenkinsfile DSL `withAws { }` and can execute your stage under the context of an IAM role that's defined by an environment variable. +* The two plugins can be used together - an IAM role can be defined in ParameterStore and translated to an environment variable `AWS_ROLE_ARN`, and that environment variable can in turn be used to configure the IAM role assumed by `WithAwsPlugin`. Using terraform-pipeline, you might initialize your pipeline as such: From 978636df0ee8819a6717fdb2745c243208916a1c Mon Sep 17 00:00:00 2001 From: Keith Manning Date: Wed, 8 Jul 2020 17:05:22 -0400 Subject: [PATCH 3/7] Fix formatting --- README.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d82843a2..f3c6c879 100644 --- a/README.md +++ b/README.md @@ -143,8 +143,11 @@ Take the following example: Using terraform-pipeline, you might initialize your pipeline as such: ``` -WithAwsPlugin.init() // Wrap everything before this in withAWS { } -ParameterStoreBuildWrapperPlugin.init() // Wrap everything before this in withAWSParameterStore { } +// Wrap everything before this in withAWS { } +WithAwsPlugin.init() + +// Wrap everything before this in withAWSParameterStore { } +ParameterStoreBuildWrapperPlugin.init() ``` The above would generate roughly the following Jenkinsfile DSL: @@ -155,7 +158,8 @@ The above would generate roughly the following Jenkinsfile DSL: // Set a key value pair in ParameterStore so that AWS_ROLE_ARN= withAWSParameterStore { ... - // AWS_ROLE_ARN is visible as an environment variable, and passed along to withAWS + // AWS_ROLE_ARN was set by ParameterStore + // AWS_ROLE_ARN is picked up and used by withAWS withAWS(role: AWS_ROLE_ARN) { ... } @@ -166,8 +170,11 @@ The above would generate roughly the following Jenkinsfile DSL: The order in which the plugins were initialized determined the order of the Jenkinsfile DSL. Had the plugins been initialized in the reverse order, the Jenkinsfile DSL would likewise be reversed, and would lead to an undesireable outcome. ``` -ParameterStoreBuildWrapperPlugin.init() // Wrap everything before this in withAWSParameterStore { } -WithAwsPlugin.init() // Wrap everything before this in withAWS { } +// Wrap everything before this in withAWSParameterStore { } +ParameterStoreBuildWrapperPlugin.init() + +// Wrap everything before this in withAWS { } +WithAwsPlugin.init() ... // AWS_ROLE_ARN is not defined - withAWS does nothing From aacb596644e9d247d5664d1f8aa2ed34322c33dc Mon Sep 17 00:00:00 2001 From: Keith Manning Date: Wed, 8 Jul 2020 17:07:17 -0400 Subject: [PATCH 4/7] Break second example apart --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index f3c6c879..efe8f5b6 100644 --- a/README.md +++ b/README.md @@ -175,6 +175,9 @@ ParameterStoreBuildWrapperPlugin.init() // Wrap everything before this in withAWS { } WithAwsPlugin.init() +``` + +``` ... // AWS_ROLE_ARN is not defined - withAWS does nothing From bbcc5b1ba18562fec4acd052e5b59df240aee9e2 Mon Sep 17 00:00:00 2001 From: Keith Manning Date: Wed, 8 Jul 2020 17:08:01 -0400 Subject: [PATCH 5/7] Fix PluginOrder heading --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index efe8f5b6..e9de2e4c 100644 --- a/README.md +++ b/README.md @@ -130,7 +130,7 @@ This library was intended to be customizable and extendable - if you don't find 6. Call your `init()` method in your Jenkinsfile before calling `build()` on your pipeline. 7. If your plugin could be useful to others, feel free to put in a Pull Request. -# Plugin Order +## Plugin Order Plugins often work by wrapping your stages in Jenkinfile DSL blocks. If multiple plugins wrap your stages simultaneously, the order in which they are wrapped can be very important. On the whole, terraform-pipeline strives to preserve and maintain the order you initialize the plugins, so that the corresponding Jenkinsfile DSL blocks execute predictably. From 2beff0d690778817dfad7be1db7a16c6224cbc58 Mon Sep 17 00:00:00 2001 From: Keith Manning Date: Wed, 8 Jul 2020 17:15:42 -0400 Subject: [PATCH 6/7] Update CHANGELOG --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index eaeb8602..fd5998f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,6 @@ # Unreleased +* [Issue #206](https://github.com/manheim/terraform-pipeline/issues/206) Explain the importance of plugin order * [Issue #219](https://github.com/manheim/terraform-pipeline/issues/219) Fix documentation - example code does not work * [Issue #234](https://github.com/manheim/terraform-pipeline/issues/234) Rename TerraformPlanResultsPRPlugin to be consistent * [Issue #193](https://github.com/manheim/terraform-pipeline/issues/193) Support passing branch plans to Github PRs From 32d056faf58206fe2001ba8c842836c319f38946 Mon Sep 17 00:00:00 2001 From: Keith Manning Date: Wed, 8 Jul 2020 17:25:05 -0400 Subject: [PATCH 7/7] Fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e9de2e4c..facfc2db 100644 --- a/README.md +++ b/README.md @@ -167,7 +167,7 @@ The above would generate roughly the following Jenkinsfile DSL: ... ``` -The order in which the plugins were initialized determined the order of the Jenkinsfile DSL. Had the plugins been initialized in the reverse order, the Jenkinsfile DSL would likewise be reversed, and would lead to an undesireable outcome. +The order in which the plugins were initialized determined the order of the Jenkinsfile DSL. Had the plugins been initialized in the reverse order, the Jenkinsfile DSL would likewise be reversed, and would lead to an undesirable outcome. ``` // Wrap everything before this in withAWSParameterStore { }