Merge pull request #355 from duckpuppy/add_terraform_import

[Issue #280] Add TerraformImportCommand and TerraformImportPlugin

Author: kmanning

CHANGELOG.md

@@ -0,0 +1,31 @@
+## [TerraformImportPlugin](../src/TerraformImportPlugin.groovy)
+
+Enable this plugin to change pipeline functionality. This plugin will import a
+resource into state, and adds two new job parameters.
+
+* `IMPORT_RESOURCE`: This is the resource identifier to import into state.
+* `IMPORT_TARGET_PATH`: This is the Terraform state path into which the
+  resource should be imported.
+* `IMPORT_ENVIRONMENT`: This should be set to the terraform-pipeline
+  environment stage that should perform the import.
+
+```
+// Jenkinsfile
+@Library(['[email protected]']) _
+
+Jenkinsfile.init(this, env)
+
+// This enables the "import" functionality
+TerraformImportPlugin.init()
+
+def validate = new TerraformValidateStage()
+
+def qa = new TerraformEnvironmentStage('qa')
+def uat = new TerraformEnvironmentStage('uat')
+def prod = new TerraformEnvironmentStage('prod')
+
+validate.then(qa)
+        .then(uat)
+        .then(prod)
+        .build()
+```

docs/TerraformImportPlugin.md

@@ -0,0 +1,102 @@
+class TerraformImportCommand implements TerraformCommand, Resettable {
+    private String environment
+    private static String resource
+    private static String targetPath
+    private static plugins = []
+    private appliedPlugins = []
+
+    TerraformImportCommand(String environment) {
+        this.environment = environment
+    }
+
+    public String toString() {
+        applyPlugins()
+        if (resource) {
+            if (targetPath) {
+                def pieces = []
+                pieces << 'terraform'
+                pieces << 'import'
+                pieces << targetPath
+                pieces << resource
+
+                return pieces.join(' ')
+            }
+            else {
+                return "echo \"No target path set, skipping 'terraform import'."
+            }
+        }
+
+        return "echo \"No resource set, skipping 'terraform import'."
+    }
+
+    public TerraformImportCommand withResource(String resource) {
+        this.resource = resource
+        return this
+    }
+
+    public String getTargetPath() {
+        return this.targetPath
+    }
+
+    public TerraformImportCommand withTargetPath(String targetPath) {
+        this.targetPath = targetPath
+        return this
+    }
+
+    public String getResource() {
+        return this.resource
+    }
+
+    public static void reset() {
+        this.resource = ''
+        this.targetPath = ''
+        this.resetPlugins()
+    }
+
+    /**
+     * Assures that all plugins are applied, and are applied at most once. It
+     * can be safely called multiple times.
+     */
+    public applyPlugins() {
+        def remainingPlugins = plugins - appliedPlugins
+
+        for (TerraformImportCommandPlugin plugin in remainingPlugins) {
+            plugin.apply(this)
+            appliedPlugins << plugin
+        }
+    }
+
+    /**
+     * Accepts a plugin of the appropriate type and adds it to the list of plugins.
+     *
+     * @param plugin The plugin to add
+     */
+    public static void addPlugin(TerraformImportCommandPlugin plugin) {
+        plugins << plugin
+    }
+
+    public static void setPlugins(plugins) {
+        this.plugins = plugins
+    }
+
+    public static getPlugins() {
+        return plugins
+    }
+
+    /**
+     * Reset plugins will reset the plugin list to a default set of plugins.
+     *
+     * @param defaultPlugins list of plugins to set, default: []
+     */
+    public static void resetPlugins(defaultPlugins = []) {
+        this.plugins = defaultPlugins.clone()
+    }
+
+    public static instanceFor(String environment) {
+        return new TerraformImportCommand(environment)
+    }
+
+    public String getEnvironment() {
+        return this.environment
+    }
+}

src/TerraformImportCommand.groovy

@@ -0,0 +1,3 @@
+interface TerraformImportCommandPlugin {
+    public void apply(TerraformImportCommand command)
+}

src/TerraformImportCommandPlugin.groovy

@@ -0,0 +1,55 @@
+import static TerraformEnvironmentStage.PLAN_COMMAND
+
+class TerraformImportPlugin implements TerraformEnvironmentStagePlugin, TerraformImportCommandPlugin {
+
+    public static void init() {
+        TerraformImportPlugin plugin = new TerraformImportPlugin()
+
+        BuildWithParametersPlugin.withStringParameter([
+            name: "IMPORT_RESOURCE",
+            description: "Run `terraform import` on the resource specified prior to planning and applying."
+        ])
+        BuildWithParametersPlugin.withStringParameter([
+            name: "IMPORT_TARGET_PATH",
+            description: "The path in the Terraform state to import the spcified resource to."
+        ])
+        BuildWithParametersPlugin.withStringParameter([
+            name: "IMPORT_ENVIRONMENT",
+            description: "The environment in which to run the import."
+        ])
+
+        TerraformEnvironmentStage.addPlugin(plugin)
+        TerraformImportCommand.addPlugin(plugin)
+    }
+
+    @Override
+    public void apply(TerraformEnvironmentStage stage) {
+        def resource = Jenkinsfile.instance.getEnv().IMPORT_RESOURCE
+        def targetPath = Jenkinsfile.instance.getEnv().IMPORT_TARGET_PATH
+        def environment = Jenkinsfile.instance.getEnv().IMPORT_ENVIRONMENT
+        if (resource && targetPath && stage.environment == environment) {
+            stage.decorate(PLAN_COMMAND, runTerraformImportCommand(stage.environment))
+        }
+    }
+
+    @Override
+    public void apply(TerraformImportCommand command) {
+        def resource = Jenkinsfile.instance.getEnv().IMPORT_RESOURCE
+        def targetPath = Jenkinsfile.instance.getEnv().IMPORT_TARGET_PATH
+        if (resource && targetPath) {
+            command.withResource(resource).withTargetPath(targetPath)
+        }
+    }
+
+    public Closure runTerraformImportCommand(String environment) {
+        def importCommand = TerraformImportCommand.instanceFor(environment)
+        return { closure ->
+            importCommand.applyPlugins()
+            if (importCommand.resource) {
+                echo "Running '${importCommand.toString()}'. TerraformImportPlugin is enabled."
+                sh importCommand.toString()
+            }
+            closure()
+        }
+    }
+}

src/TerraformImportPlugin.groovy

@@ -0,0 +1,100 @@
+import static org.hamcrest.Matchers.containsString
+import static org.hamcrest.Matchers.blankString
+import static org.hamcrest.MatcherAssert.assertThat
+import static org.mockito.Mockito.mock
+import static org.mockito.Mockito.times
+import static org.mockito.Mockito.verify
+
+import org.junit.jupiter.api.Nested
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.extension.ExtendWith
+
+@ExtendWith(ResetStaticStateExtension.class)
+class TerraformImportCommandTest {
+    @Nested
+    public class WithResource {
+        @Test
+        void defaultsToEmpty() {
+            def command = new TerraformImportCommand()
+
+            def actualCommand = command.toString()
+            assertThat(actualCommand, containsString("No resource set, skipping 'terraform import'."))
+        }
+
+        @Test
+        void doesntRunWithoutTargetPath() {
+            def command = new TerraformImportCommand().withResource("foo")
+
+            def actualCommand = command.toString()
+            assertThat(actualCommand, containsString("No target path set, skipping 'terraform import'."))
+        }
+
+        @Test
+        void runsCommandWhenTargetIsAlsoSet() {
+            def command = new TerraformImportCommand().withResource("foo").withTargetPath("target.foo")
+
+            def actualCommand = command.toString()
+            assertThat(actualCommand, containsString("terraform import target.foo foo"))
+        }
+    }
+
+    @Nested
+    public class WithTargetPath {
+        @Test
+        void defaultsToEmpty() {
+            def command = new TerraformImportCommand()
+
+            assertThat(command.targetPath, blankString())
+        }
+
+        @Test
+        void doesntRunWithoutResource() {
+            def command = new TerraformImportCommand().withTargetPath("target.foo")
+
+            def actualCommand = command.toString()
+            assertThat(actualCommand, containsString("No resource set, skipping 'terraform import'."))
+        }
+    }
+
+    @Nested
+    public class Plugins {
+        @Test
+        void areAppliedToTheCommand() {
+            TerraformImportCommandPlugin plugin = mock(TerraformImportCommandPlugin.class)
+            TerraformImportCommand.addPlugin(plugin)
+
+            TerraformImportCommand command = TerraformImportCommand.instanceFor("env")
+            command.toString()
+
+            verify(plugin).apply(command)
+        }
+
+        @Test
+        void areAppliedExactlyOnce() {
+            TerraformImportCommandPlugin plugin = mock(TerraformImportCommandPlugin.class)
+            TerraformImportCommand.addPlugin(plugin)
+
+            TerraformImportCommand command = TerraformImportCommand.instanceFor("env")
+
+            String firstCommand = command.toString()
+            String secondCommand = command.toString()
+
+            verify(plugin, times(1)).apply(command)
+        }
+
+        @Test
+        void areAppliedEvenAfterCommandAlreadyInstantiated() {
+            TerraformImportCommandPlugin firstPlugin = mock(TerraformImportCommandPlugin.class)
+            TerraformImportCommandPlugin secondPlugin = mock(TerraformImportCommandPlugin.class)
+
+            TerraformImportCommand.addPlugin(firstPlugin)
+            TerraformImportCommand command = TerraformImportCommand.instanceFor("env")
+
+            TerraformImportCommand.addPlugin(secondPlugin)
+
+            command.toString()
+
+            verify(secondPlugin, times(1)).apply(command)
+        }
+    }
+}