Introducing Custom Workflows

The Custom Workflow tool elevates your Terraform workflow by offering a custom binary as an alternative to one of the Terraform versions supported out of the box by Spacelift. It also gives you the option of customizing the workflow’s options. 

Here are some of the reasons you might require a custom binary instead of the official Terraform one:

• OpenTofu support – Started as a fork, OpenTofu is a drop-in replacement for Terraform, that is open-source, community-driven, and managed by the Linux Foundation.

• Feature-wise – The official version of Terraform may lack features that can be easily added to a custom binary. This can be very useful when you have a particular use case that isn’t supported by the standard Terraform binary. 

• Compatibility issues – Some enterprises may have compatibility issues, such as the need to use a deprecated state backend between Terraform and a specific environment, system, or tooling. Using a custom binary can be tailored to ensure compatibility.

• Security – Even though Terraform undergoes many security audits, an organization may have specific security needs or protocols such as state and plan encryption that require other solutions

• Performance optimization – There may be cases where you need performance optimizations (e.g. https://github.com/opentofu/opentofu/pull/579) that aren’t available in the official binary.

Customizing your Terraform’s workflow options gives you flexibility. At Spacelift, we believe in flexibility — and that’s why you have full control over what happens inside your workflow. Even though Spacelift’s default workflow for Terraform satisfies most use cases, there are some that may require some special tweaks, and we understand that.

In Spacelift, the custom tool to your workflow can be provided by either installing the binary in a pre-init hook or using a custom runner image.

Every stage in Spacelift’s Terraform workflow has designated commands to execute specific tasks. For instance, there are commands tailored for generating a Terraform plan and others for retrieving the current state of the infrastructure. While Spacelift offers a default set of built-in commands that users can utilize, there’s also flexibility to introduce and employ custom commands if the need arises. To specify these custom commands, you must create and configure a file named .spacelift/workflow.yml.

For this workflow file, you must provide the following commands:

• init
• workspaceSelect
• workspaceNew
• plan
• showState
• showPlan
• getOutputs
• apply
• destroy

Let’s build an example workflow file for OpenTofu.

The values of all of these commands can be customized to fit your workflow.

There are three ways to specify a Custom Workflow file:

• Adding the workflow.yml file in a context as a mounted file
• Adding the workflow.yml file in the environment of the stack as a mounted file
• Directly inside of the git repository

To easily reuse the configuration for multiple stacks, a context is the way to go. Still, for testing out a binary, it is easier to do it directly in the stack environment. Storing it in the git repository has advantages, too, such as leveraging versioning and maintaining the workflow tool directly alongside your code.

For this example, I will use a context, as I want to easily reuse the workflow for multiple stacks. Go to your Spacelift account and select Contexts → Create Context.

Next, click on Create New Context, and your context will be created.

Now, let’s edit the context and add a Mounted file as shown below:

You can create the file either by using the built-in editor or by uploading the file. For simplicity, I will use the built-in editor and reuse the content from the first step.

Next, click on Plain to save the mounted file as plain text (secrets are non-editable, you can only replace the content entirely, and we may want to make edits in the future).

Let’s create a stack and use this context. You will create it as you would normally do – adding a name, selecting the space, and selecting the repository you want to use (I am using this repo).

Although this is not a requirement for this feature to work, I will be using OpenTofu’s registry and for that, I configured the required provider as shown below:

In this Configure Backend step, there is a new option called Workflow tool. This should be set to Custom as below:

Next, in the Define Behavior tab, you have two options for installing OpenTofu:

• Use a Runner image with OpenTofu installed. 
• Install it as part of an Init hook.

Let’s install it in a before init hook:

Next, go to the stack’s settings and attach the context:

Now, we are ready to run the stack.

As you can see in the above screenshot, I am using OpenTofu’s registry to get the random provider, and a tofu init is running for the workspace initialization. After that, OpenTofu is running a tofu plan to show what resources will be created.

With Custom Workflows and OpenTofu, you can also migrate seamlessly from Terraform. Simply modify your existing stack to use the OpenTofu backend and run a plan to see that nothing will change.

OpenTofu was used just as an example to demonstrate the power of using the Custom Workflow tool. Out-of-the-box support for OpenTofu will also be available as soon as the first official release is published.

Custom Workflows are only available right now for Terraform Workflows, due to the upcoming release of OpenTofu, but they will be coming soon to some other backends as well, starting with Kubernetes, so stay tuned.

Custom Workflows offer the ability to use a custom binary instead of one of the Terraform versions supported by Spacelift. This feature lets you take advantage of any convenient in-house implementations you have done and also allows you to use different commands other than the ones supported by the default Spacelift workflow.

If you want to learn more about Spacelift, create a free account today or book a demo with one of our engineers.