diff --git a/website/docs/intro/migration/terraform-1.7.mdx b/website/docs/intro/migration/terraform-1.7.mdx index f73db9e534..1e6ce2106b 100644 --- a/website/docs/intro/migration/terraform-1.7.mdx +++ b/website/docs/intro/migration/terraform-1.7.mdx @@ -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 diff --git a/website/docs/intro/migration/terraform-1.8.mdx b/website/docs/intro/migration/terraform-1.8.mdx index 3d38f08c94..96ba08d898 100644 --- a/website/docs/intro/migration/terraform-1.8.mdx +++ b/website/docs/intro/migration/terraform-1.8.mdx @@ -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 diff --git a/website/docs/intro/migration/terraform-1.9.mdx b/website/docs/intro/migration/terraform-1.9.mdx new file mode 100644 index 0000000000..e7fd97b0cc --- /dev/null +++ b/website/docs/intro/migration/terraform-1.9.mdx @@ -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 OpenTofu Slack 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/).