mirror of
https://github.com/opentofu/opentofu.git
synced 2025-02-25 18:45:20 -06:00
Updated migration guides (#2224)
Signed-off-by: AbstractionFactory <179820029+abstractionfactory@users.noreply.github.com> Co-authored-by: Oleksandr Levchenkov <ollevche@gmail.com>
This commit is contained in:
AbstractionFactory
GitHub
parent
a117f86b98
commit
091f68d173
@ -84,8 +84,7 @@ The OpenTofu `removed` block works differently from the Terraform variant. Pleas
|
||||
|
||||
If you are using the `terraform test` feature, you will need to perform the following changes:
|
||||
|
||||
1. If you are `mock_provider`, restructure your tests to work without this feature (see [OpenTofu issue #1155](https://github.com/opentofu/opentofu/issues/1155)).
|
||||
2. If you are using `override_resource`, `override_data`, or `override_module`, restructure your tests to work without these features (see [OpenTofu issue #1204](https://github.com/opentofu/opentofu/issues/1204)).
|
||||
1. If you are using `override_resource` or `override_data` nested in a `mock_provider` restructure your tests to work without these features (see [OpenTofu issue #1204](https://github.com/opentofu/opentofu/issues/1204)).
|
||||
|
||||
## Step 6: Initialize OpenTofu
|
||||
|
||||
|
||||
@ -66,6 +66,16 @@ Additionally, make sure you back up or version your code as the migration will r
|
||||
|
||||
For a successful migration, you will need to perform the following code changes
|
||||
|
||||
### Functions
|
||||
|
||||
The following functions are not supported in OpenTofu:
|
||||
|
||||
- `encode_tfvars`
|
||||
- `decode_tfvars`
|
||||
- `encode_expr`
|
||||
|
||||
If you rely on these functions, please refactor your code to work without them.
|
||||
|
||||
### S3 backend
|
||||
|
||||
If you are using the S3 backend, please change your code as follows:
|
||||
@ -83,8 +93,7 @@ The OpenTofu `removed` block works differently from the Terraform variant. Pleas
|
||||
|
||||
If you are using the `terraform test` feature, you will need to perform the following changes:
|
||||
|
||||
1. If you are using `mock_provider`, restructure your tests to work without this feature (see [OpenTofu issue #1155](https://github.com/opentofu/opentofu/issues/1155)).
|
||||
2. If you are using `override_resource`, `override_data`, or `override_module`, restructure your tests to work without these features (see [OpenTofu issue #1204](https://github.com/opentofu/opentofu/issues/1204)).
|
||||
1. If you are using `override_resource` or `override_data` nested in a `mock_provider` restructure your tests to work without these features (see [OpenTofu issue #1204](https://github.com/opentofu/opentofu/issues/1204)).
|
||||
|
||||
## Step 6: Initialize OpenTofu
|
||||
|
||||
|
||||
178
website/docs/intro/migration/terraform-1.9.mdx
Normal file
178
website/docs/intro/migration/terraform-1.9.mdx
Normal file
@ -0,0 +1,178 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
sidebar_label: Migrating from Terraform 1.9.x
|
||||
description: |-
|
||||
Learn how to migrate to OpenTofu from Terraform.
|
||||
---
|
||||
|
||||
# Migrating to OpenTofu from Terraform 1.9.x
|
||||
|
||||
When migrating from Terraform 1.9.x, please migrate to OpenTofu 1.9.0 first, then
|
||||
[upgrade your OpenTofu installation](/docs/intro/upgrading/) to the latest version.
|
||||
|
||||
OpenTofu 1.9.0 is largely compatible with Terraform 1.9.x with a few minor changes needed. This migration guide will
|
||||
take you through the process of switching from Terraform to OpenTofu.
|
||||
|
||||
## Step 0: Prepare a disaster recovery plan
|
||||
|
||||
Although OpenTofu 1.9.0 is very similar to Terraform 1.9.8, make sure you have an up to date and *tested* disaster
|
||||
recovery plan.
|
||||
|
||||
## Step 1: Upgrading Terraform
|
||||
|
||||
This migration guide is only valid for Terraform 1.9.8. If you are on a Terraform version below 1.9.8, please upgrade
|
||||
to at least Terraform version 1.9.8 before proceeding with the migration by following the
|
||||
[Terraform upgrade guide](https://developer.hashicorp.com/terraform/language/v1.9.x/upgrade-guides). If you are on a
|
||||
higher Terraform version, please wait until an appropriate migration guide becomes available.
|
||||
|
||||
## Step 2: Apply all changes with Terraform
|
||||
|
||||
Before proceeding, make sure that you apply all changes with `terraform apply`. Running `terraform plan` should result
|
||||
in no planned changes. While you can switch to OpenTofu with pending changes, it is not recommended.
|
||||
|
||||
```
|
||||
$ terraform plan
|
||||
|
||||
...
|
||||
|
||||
No changes. Your infrastructure matches the configuration.
|
||||
|
||||
Terraform has compared your real infrastructure against your
|
||||
configuration and found no differences, so no changes are needed.
|
||||
```
|
||||
|
||||
## Step 3: Install OpenTofu 1.9.0
|
||||
|
||||
As a first step, please [follow the installation instructions for the OpenTofu CLI tool](intro/install/index.mdx). Please test
|
||||
if you can successfully execute the `tofu` command:
|
||||
|
||||
```
|
||||
$ tofu --version
|
||||
OpenTofu v1.9.0
|
||||
on linux_amd64
|
||||
```
|
||||
|
||||
## Step 4: Back up your state file and code
|
||||
|
||||
Before you begin using the `tofu` binary on your Terraform code, make sure to back up your state file. If you are using
|
||||
a local state file, you can simply make a copy of your `terraform.tfstate` file in your project directory.
|
||||
|
||||
If you are using a remote backend such as an S3 bucket, make sure that you follow the backup procedures for the
|
||||
backend and that you exercise the restore procedure at least once.
|
||||
|
||||
Additionally, make sure you back up or version your code as the migration will require some code changes.
|
||||
|
||||
## Step 5: Code changes
|
||||
|
||||
For a successful migration, you will need to perform the following code changes
|
||||
|
||||
### Functions
|
||||
|
||||
The following functions are not supported in OpenTofu:
|
||||
|
||||
- `encode_tfvars`
|
||||
- `decode_tfvars`
|
||||
- `encode_expr`
|
||||
|
||||
If you rely on these functions, please refactor your code to work without them.
|
||||
|
||||
### S3 backend
|
||||
|
||||
If you are using the S3 backend, please change your code as follows:
|
||||
|
||||
1. If you are using the `skip_s3_checksum` option on the S3 backend, remove this option as OpenTofu does not need it.
|
||||
2. If you are using the `endpoints` → `sso` option or the `AWS_ENDPOINT_URL` environment variable, remove this option and verify if your code still works as intended after the migration.
|
||||
|
||||
### Removed block
|
||||
|
||||
The OpenTofu `removed` block works differently from the Terraform variant. Please [review the documentation](../../language/resources/syntax.mdx#removing-resources) and make the following changes:
|
||||
|
||||
1. Remove the `lifecycle` block. If you used the `lifecycle` → `destroy = true` setting, remove the entire `removed` block. Verify that the code still works as intended after the migration.
|
||||
2. If you are using destroy-time provisioners with `removed` blocks, please restructure your code to work without them.
|
||||
|
||||
### Input variable validation
|
||||
|
||||
If your input variable validation refers to other variables or objects, restructure your code
|
||||
to work around the necessity for these. (See issue [#1336](https://github.com/opentofu/opentofu/issues/1336).)
|
||||
|
||||
### Testing changes
|
||||
|
||||
If you are using the `terraform test` feature, you will need to perform the following changes:
|
||||
|
||||
1. If you are using `override_resource` or `override_data` nested in a `mock_provider` restructure your tests to work without these features (see [OpenTofu issue #1204](https://github.com/opentofu/opentofu/issues/1204)).
|
||||
|
||||
## Step 6: Initialize OpenTofu
|
||||
|
||||
:::warning
|
||||
|
||||
Should any of the following steps fail, please do not proceed and follow the
|
||||
[rollback instructions below](#rolling-back-to-terraform-and-reporting-issues) instead.
|
||||
If you suspect the failure may be the result of a bug in OpenTofu,
|
||||
[please help us by opening an issue](https://github.com/opentofu/opentofu/issues).
|
||||
|
||||
:::
|
||||
|
||||
Now you are ready to migrate. Run `tofu init` in the directory where your Terraform code resides. OpenTofu will download
|
||||
any providers and modules referenced in your configuration from the OpenTofu registry.
|
||||
|
||||
## Step 7: Inspect the plan
|
||||
|
||||
Once initialized, run `tofu plan` and ensure that there are no pending changes similar to step 1 above. If there are
|
||||
unexpected changes in the plan, roll back to Terraform and troubleshoot your migration. (See the Troubleshooting section
|
||||
below.)
|
||||
|
||||
```
|
||||
$ tofu plan
|
||||
|
||||
...
|
||||
|
||||
No changes. Your infrastructure matches the configuration.
|
||||
|
||||
OpenTofu has compared your real infrastructure against your
|
||||
configuration and found no differences, so no changes are needed.
|
||||
```
|
||||
|
||||
## Step 8: Apply
|
||||
|
||||
Even though there should be no changes in your infrastructure, you should run `tofu apply` to ensure that OpenTofu
|
||||
updates the state file.
|
||||
|
||||
## Step 9: Test out a small change
|
||||
|
||||
Before you begin using OpenTofu for larger changes, test out `tofu apply` with a smaller, non-critical
|
||||
change.
|
||||
|
||||
## Step 10: Upgrade to the latest OpenTofu version
|
||||
|
||||
Now that the migration is complete, follow the [upgrade guide](/docs/intro/upgrading/) for OpenTofu to upgrade to the
|
||||
latest version.
|
||||
|
||||
## Rolling back to Terraform and reporting issues
|
||||
|
||||
If you have issues migrating to OpenTofu you can follow these steps to roll back to Terraform:
|
||||
|
||||
1. Create another backup of your state file and code.
|
||||
2. Remove any code changes you have made.
|
||||
3. Run `terraform init`.
|
||||
4. Run `terraform plan` and verify that no unexpected changes are in the plan.
|
||||
5. Run `terraform apply` and verify that it runs properly with no changes.
|
||||
6. Test the rollback with a small, non-critical change.
|
||||
|
||||
If you encountered a bug, [please report it on GitHub](https://github.com/opentofu/opentofu/issues).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you encounter any issues during the migration to OpenTofu, you can join the <a href="/slack/">OpenTofu Slack</a> or ask on
|
||||
[GitHub Discussions](https://github.com/orgs/opentofu/discussions).
|
||||
|
||||
### Error: Failed to query available provider packages
|
||||
|
||||
This error happens when a provider you specified in your configuration is not available in the OpenTofu registry.
|
||||
Please roll back to Terraform and make sure your code works with Terraform. If your code works, please
|
||||
[submit an issue to include the provider in the registry](https://github.com/opentofu/registry/issues/).
|
||||
|
||||
### Error: Module not found
|
||||
|
||||
This error happens when a module you specified in your configuration is not available in the OpenTofu registry.
|
||||
Please roll back to Terraform and make sure your code works with Terraform. If your code works, please
|
||||
[submit an issue to include the module in the registry](https://github.com/opentofu/registry/issues/).
|
||||
Loading…
Reference in New Issue
Block a user