Plugin Initialization Order Effects are Uncodumented

[dkolb]

Update

Updating this issue to a documentation issue and will open a PR Soon ™️ with updates to the relevant sections of README.md. Essentially we should just document that plugins are initialized in an "inside out" order where the last plugin initialized will have it's decorations wrapping all other plugin decorations. Specifically we should call out that TerraformEnvironmentStage.withGlobalEnv(String, String) should be the last thing you do so that your environment variables are available to all other variables.

Original Issue

// Jenkinsfile
@Library(['terraform-pipeline-modern', 'pingfederate-pipeline-customizations']) _

Jenkinsfile.init(this)
Jenkinsfile.declarative = true
Jenkinsfile.pipelineTemplate = this.PingFederatePipelineTemplateLowers
Jenkinsfile.defaultNodeName = 'tfenv'

TerraformEnvironmentStage.withGlobalEnv('AWS_ROLE_ARN', 'role::arn::here')

WithAwsPlugin.init()

This will result in withAWS being skipped due to the withEnv from the EnvironmentVariablePlugin's decorations being after withGlobalEnv.

Workarounds are to directly manipulate env at the top of your file:

env.PERF_AWS_ROLE_ARN = env.PROD_AWS_ROLE_ARN

I'm not sure if we should fix this or just update documentation on the withAWS plugin page.

[kmanning]

Hrm, I expected a question of this form to come up at some point.

The plugins are ordered, which means you SHOULD be able to solve nesting issues like this by simply reordering your calls.

Meaning, instead of doing this, which will nest the environment variables inside of the WithAwsPlugin:

TerraformEnvironmentStage.withGlobalEnv('AWS_ROLE_ARN', 'role::arn::here')

WithAwsPlugin.init()

You can simply flip your calls to nest it the other way:

WithAwsPlugin.init()

TerraformEnvironmentStage.withGlobalEnv('AWS_ROLE_ARN', 'role::arn::here')

Does this NOT work?

[kmanning]

So it dawned on me - EnvironmentVariablePlugin came later, and was never documented. I'm gonna add EnvironmentVariablePlugin to the list of plugins, then use it to describe exactly what you did above. Then the example that you're describing will use 2 plugins, and can be used to illustrate the importance of order when initializing plugins. PR on the way.