Intro
So, you decided to make the big leap and migrate your IaC framework from Terraform to OpenTofu.
In this short blog article, we’ll provide a step-by-step guide on how to do it; honestly, it’s much easier than you would imagine.
For all versions lower than 1.6, OpenTofu is a drop-in replacement for Terraform. It already becomes dependent on using various features as you progress through the versions. The technical side of the migration is quite trivial; instead of running the terraform command, all you have to do is run the tofu command.
Let’s start with what a migration looks like.
The Migration Procedure
- Let’s assume I have a directory with Terraform code that manages some resources in my staging account. Up until now, I used the ‘Terraform’ command to run this code. Before moving to OpenTofu, I want to make sure my code is still valid and I don’t have any drifts. So, the first step would be to run the ‘terraform init’ command to get things going.
- Now I’m going to run ‘
terraform apply‘ just to make sure that there are no drifts and that my code perfectly represent my running resources.
- Ok, the big moment has arrived. I’m going to switch my IaC engine to OpenTofu 🙂
In order for us to run this code with OpenTofu, the first step would be to run ‘tofu init -upgrade‘.
The reason for the ‘upgrade’ flag is to download the providers and the modules (if any) from the OpenTofu registry, not from the HashiCorp registry. - Ok, the next step would be to run ‘
tofu apply‘ to refresh my state file and to validate that there are no drifts.
Voilà! Migration done!
What to Watch out for
Another important consideration when performing the migration is ensuring your code doesn’t directly use the HashiCorp registry. What does that mean?
That means that your code shouldn’t use the fully qualified name of a module/provider from HashiCorp’s registry. For example:
Here, I’m using the AWS provider from the HashiCorp registry. Using this when running the OpenTofu command is against the BSL licensing (Note: this is not legal advice; I’m not a lawyer, and it’s my understanding from the license change).
Since I use a fully qualified name with registry.terraform.io, the provider will be downloaded from the HashiCorp registry.
Let’s see how it looks like if I’m running this code with the ‘tofu’ command:
How to fix it? It’s very simple: Don’t use fully qualified names. For example, in this example, instead of writing ‘registry.terraform.io/hashicorp/aws’, you should write ‘hashicorp/aws’.
To sum up, after completing the migration, be sure to check that your codebase does not reference Hashicorp’s registry.
Challenge at Scale
As always, the challenge comes in when you have big-scale environments or large terraform codebase to manage.
Migrating a single Terraform stack is pretty straightforward, but what if you have hundreds or thousands of stacks that you want to migrate?
What about inspecting your code to ensure it doesn’t reference HashiCorp’s registry using a fully qualified name?
You’ll probably need some automation to run on all of your Terraform stacks, perform the check, and provide a final report of what went well, what went wrong, and what’s your OpenTofu compatibility.
It’s more of a management challenge than a technical one.
Summary
As you can see, the migration procedure from Terraform to OpenTofu is pretty straightforward.
The real challenges occur when you have large and complex environments with hundreds or thousands of stacks.
If you’re thinking of shifting your IaC framework to Terraform, we would love to jump on a call and let you know how the ControlMonkey Terraform Automation platform can help you throughout the process.
