mirror of
https://github.com/opentofu/opentofu.git
synced 2025-02-25 18:45:20 -06:00
Migration guides (#1552)
Signed-off-by: Janos <86970079+janosdebugs@users.noreply.github.com>
This commit is contained in:
parent
52eb928e6a
commit
cdb10b12b0
@ -1,6 +1,6 @@
|
||||
---
|
||||
sidebar_label: Working with OpenTofu
|
||||
sidebar_position: 4
|
||||
sidebar_position: 6
|
||||
description: 'An overview of how individuals, teams, and organizations can use OpenTofu. '
|
||||
---
|
||||
|
||||
|
37
website/docs/intro/migration/index.mdx
Normal file
37
website/docs/intro/migration/index.mdx
Normal file
@ -0,0 +1,37 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
sidebar_label: Migrating to OpenTofu
|
||||
description: |-
|
||||
Learn how to migrate to OpenTofu from Terraform.
|
||||
---
|
||||
|
||||
import DocCardList from "@theme/DocCardList";
|
||||
|
||||
## Migrating to OpenTofu 1.7.x from Terraform
|
||||
|
||||
Please select the Terraform version you are migrating from:
|
||||
|
||||
<DocCardList
|
||||
items={[
|
||||
{
|
||||
type: "link",
|
||||
href: "terraform-1.8/",
|
||||
label: "Terraform 1.8",
|
||||
},
|
||||
{
|
||||
type: "link",
|
||||
href: "terraform-1.7/",
|
||||
label: "Terraform 1.7",
|
||||
},
|
||||
{
|
||||
type: "link",
|
||||
href: "terraform-1.6/",
|
||||
label: "Terraform 1.6",
|
||||
},
|
||||
{
|
||||
type: "link",
|
||||
href: "terraform-1.5-or-lower/",
|
||||
label: "Terraform 1.5 or lower",
|
||||
},
|
||||
]}
|
||||
/>
|
@ -1,119 +1,137 @@
|
||||
---
|
||||
sidebar_position: 99
|
||||
sidebar_label: Migrating to OpenTofu
|
||||
description: |-
|
||||
Learn how to migrate to OpenTofu from Terraform.
|
||||
---
|
||||
|
||||
# Migrating to OpenTofu from Terraform
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
import CodeBlock from '@theme/CodeBlock';
|
||||
|
||||
OpenTofu 1.6 is compatible with Terraform 1.6. 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.6 is very similar to Terraform 1.6, it is a non-trivial change affecting your infrastructure. Make
|
||||
sure you have an up to date and *tested* disaster recovery plan.
|
||||
|
||||
## Step 1: 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 2: Install OpenTofu
|
||||
|
||||
As a first step, please [follow the installation instructions for the OpenTofu CLI tool](install/index.mdx). Please test if
|
||||
you can successfully execute the `tofu` command:
|
||||
|
||||
```
|
||||
$ tofu --version
|
||||
OpenTofu v1.6.0
|
||||
on linux_amd64
|
||||
```
|
||||
|
||||
## Step 3: Back up your state file
|
||||
|
||||
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.
|
||||
|
||||
## Step 4: 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 5: 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 6: Test out a small change
|
||||
|
||||
Before you begin using OpenTofu for larger changes, test out `tofu apply` with a smaller, non-critical
|
||||
change.
|
||||
|
||||
## 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.
|
||||
2. Run `terraform init`.
|
||||
3. Run `terraform plan` and verify that no unexpected changes are in the plan.
|
||||
4. 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](/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/).
|
||||
---
|
||||
sidebar_position: 6
|
||||
sidebar_label: Migrating from Terraform 1.5.x or lower
|
||||
description: |-
|
||||
Learn how to migrate to OpenTofu 1.7.0 from Terraform 1.5.x or lower.
|
||||
---
|
||||
|
||||
# Migrating to OpenTofu from Terraform 1.5.x or lower
|
||||
|
||||
When migrating from Terraform 1.5.x or lower, please migrate to OpenTofu 1.6.2 first, then
|
||||
[upgrade your OpenTofu installation](../upgrading.mdx) to the latest version.
|
||||
|
||||
OpenTofu 1.6.2 is compatible with Terraform 1.5.x or lower. 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.6.2 is very similar to Terraform 1.5.7, 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.5.7. If you are on a Terraform version below 1.5.7, please upgrade
|
||||
to at least Terraform version 1.5.7 before proceeding with the migration by following the
|
||||
[Terraform upgrade guide](https://developer.hashicorp.com/terraform/language/v1.5.x/upgrade-guides). If you are on a
|
||||
higher Terraform version, please select the appropriate migration guide for your Terraform version.
|
||||
|
||||
## 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.6.2
|
||||
|
||||
As a first step, please [follow the installation instructions for the OpenTofu CLI tool](install/index.mdx). Make sure
|
||||
to install OpenTofu 1.6.2. Please test if you can successfully execute the `tofu` command and that it returns the
|
||||
correct version:
|
||||
|
||||
```
|
||||
$ tofu --version
|
||||
OpenTofu v1.6.2
|
||||
on linux_amd64
|
||||
```
|
||||
|
||||
## Step 4: Back up your state file
|
||||
|
||||
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.
|
||||
|
||||
## Step 5: 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 6: 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 7: 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 8: Test out a small change
|
||||
|
||||
Before you begin using OpenTofu for larger changes, test out `tofu apply` with a smaller, non-critical
|
||||
change.
|
||||
|
||||
## Step 9: Upgrade to the latest OpenTofu version
|
||||
|
||||
Now that the migration is complete, follow the [upgrade guide](../upgrading.mdx) 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.
|
||||
2. Run `terraform init`.
|
||||
3. Run `terraform plan` and verify that no unexpected changes are in the plan.
|
||||
4. Run `terraform apply` and verify that it runs properly with no changes.
|
||||
5. 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](/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/).
|
152
website/docs/intro/migration/terraform-1.6.mdx
Normal file
152
website/docs/intro/migration/terraform-1.6.mdx
Normal file
@ -0,0 +1,152 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
sidebar_label: Migrating from Terraform 1.6.x
|
||||
description: |-
|
||||
Learn how to migrate to OpenTofu from Terraform.
|
||||
---
|
||||
|
||||
# Migrating to OpenTofu from Terraform 1.6.x
|
||||
|
||||
When migrating from Terraform 1.6.x, please migrate to OpenTofu 1.6.2 first, then
|
||||
[upgrade your OpenTofu installation](../upgrading.mdx) to the latest version.
|
||||
|
||||
OpenTofu 1.6.2 is largely compatible with Terraform 1.6.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.6.2 is very similar to Terraform 1.6.6, 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.6.6. If you are on a Terraform version below 1.6.6, please upgrade
|
||||
to at least Terraform version 1.6.6 before proceeding with the migration by following the
|
||||
[Terraform upgrade guide](https://developer.hashicorp.com/terraform/language/v1.6.x/upgrade-guides). If you are on a
|
||||
higher Terraform version, please upgrade to the next minor version of Terraform and use the appropriate migration
|
||||
guide.
|
||||
|
||||
## 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.6.2
|
||||
|
||||
As a first step, please [follow the installation instructions for the OpenTofu CLI tool](install/index.mdx). Make sure
|
||||
to install OpenTofu 1.6.2. Please test if you can successfully execute the `tofu` command and that it returns the
|
||||
correct version:
|
||||
|
||||
```
|
||||
$ tofu --version
|
||||
OpenTofu v1.6.2
|
||||
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
|
||||
|
||||
### 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.
|
||||
|
||||
## 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](../upgrading.mdx) 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](/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/).
|
164
website/docs/intro/migration/terraform-1.7.mdx
Normal file
164
website/docs/intro/migration/terraform-1.7.mdx
Normal file
@ -0,0 +1,164 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
sidebar_label: Migrating from Terraform 1.7.x
|
||||
description: |-
|
||||
Learn how to migrate to OpenTofu from Terraform.
|
||||
---
|
||||
|
||||
# Migrating to OpenTofu from Terraform 1.7.x
|
||||
|
||||
When migrating from Terraform 1.7.x, please migrate to OpenTofu 1.7.0 first, then
|
||||
[upgrade your OpenTofu installation](../upgrading.mdx) to the latest version.
|
||||
|
||||
OpenTofu 1.7.0 is largely compatible with Terraform 1.7.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.7.0 is very similar to Terraform 1.7.5, 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.7.5. If you are on a Terraform version below 1.7.5, please upgrade
|
||||
to at least Terraform version 1.7.5 before proceeding with the migration by following the
|
||||
[Terraform upgrade guide](https://developer.hashicorp.com/terraform/language/v1.7.x/upgrade-guides). If you are on a
|
||||
higher Terraform version, please upgrade to the next minor version of Terraform and use the appropriate migration
|
||||
guide.
|
||||
|
||||
## 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.7.0
|
||||
|
||||
As a first step, please [follow the installation instructions for the OpenTofu CLI tool](install/index.mdx). Please test
|
||||
if you can successfully execute the `tofu` command:
|
||||
|
||||
```
|
||||
$ tofu --version
|
||||
OpenTofu v1.7.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
|
||||
|
||||
### 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.
|
||||
|
||||
### Testing changes
|
||||
|
||||
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)).
|
||||
|
||||
## 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](../upgrading.mdx) 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](/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/).
|
158
website/docs/intro/migration/terraform-1.8.mdx
Normal file
158
website/docs/intro/migration/terraform-1.8.mdx
Normal file
@ -0,0 +1,158 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
sidebar_label: Migrating from Terraform 1.8.x
|
||||
description: |-
|
||||
Learn how to migrate to OpenTofu from Terraform.
|
||||
---
|
||||
|
||||
# Migrating to OpenTofu from Terraform 1.8.x
|
||||
|
||||
When migrating from Terraform 1.8.x, please migrate to OpenTofu 1.7.0 first, then
|
||||
[upgrade your OpenTofu installation](../upgrading.mdx) to the latest version.
|
||||
|
||||
OpenTofu 1.7.0 is largely compatible with Terraform 1.8.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.7.0 is very similar to Terraform 1.8.2, 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.8.2. If you are on a Terraform version below 1.8.2, please upgrade
|
||||
to at least Terraform version 1.8.2 before proceeding with the migration by following the
|
||||
[Terraform upgrade guide](https://developer.hashicorp.com/terraform/language/v1.7.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.7.0
|
||||
|
||||
As a first step, please [follow the installation instructions for the OpenTofu CLI tool](install/index.mdx). Please test
|
||||
if you can successfully execute the `tofu` command:
|
||||
|
||||
```
|
||||
$ tofu --version
|
||||
OpenTofu v1.7.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
|
||||
|
||||
### 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.
|
||||
|
||||
### Testing changes
|
||||
|
||||
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)).
|
||||
|
||||
## 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.
|
||||
|
||||
## 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](/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/).
|
116
website/docs/intro/upgrading.mdx
Normal file
116
website/docs/intro/upgrading.mdx
Normal file
@ -0,0 +1,116 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
sidebar_label: Upgrading from OpenTofu 1.6.x
|
||||
description: |-
|
||||
Learn how to upgrade OpenTofu from version 1.6.x to 1.7.0.
|
||||
---
|
||||
|
||||
# Upgrading from OpenTofu 1.6.x
|
||||
|
||||
OpenTofu 1.7.x is fully compatible with OpenTofu 1.6.x. This migration guide will take you through the process of
|
||||
upgrading OpenTofu to version 1.7.0.
|
||||
|
||||
## Step 0: Prepare a disaster recovery plan
|
||||
|
||||
Although OpenTofu 1.7 is fully compatible with version 1.6, you should take the necessary precautions to prevent
|
||||
accidents. Make sure you have an up to date and *tested* disaster recovery plan.
|
||||
|
||||
## Step 1: Apply all changes with OpenTofu 1.6.x
|
||||
|
||||
Before proceeding, make sure that you apply all changes with `tofu apply`. Running `tofu plan` should result
|
||||
in no planned changes. While you can switch to OpenTofu with pending changes, it is not recommended.
|
||||
|
||||
```
|
||||
$ 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 3: Install OpenTofu 1.7.x
|
||||
|
||||
As a first step, please [follow the installation instructions for the OpenTofu CLI tool](install/index.mdx). Please test
|
||||
if you can successfully execute the `tofu` command and receive the correct version:
|
||||
|
||||
```
|
||||
$ tofu --version
|
||||
OpenTofu v1.7.0
|
||||
on linux_amd64
|
||||
```
|
||||
|
||||
## Step 4: Back up your state file
|
||||
|
||||
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.
|
||||
|
||||
## Step 5: Initialize OpenTofu 1.7.x
|
||||
|
||||
:::warning
|
||||
|
||||
Should any of the following steps fail, please do not proceed and follow the
|
||||
[rollback instructions below](#rolling-back-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 code resides. OpenTofu will download
|
||||
any providers and modules referenced in your configuration from the OpenTofu registry.
|
||||
|
||||
## Step 6: 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 OpenTofu 1.6.x 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 7: Test out a small change
|
||||
|
||||
Before you begin using OpenTofu for larger changes, test out `tofu apply` with a smaller, non-critical
|
||||
change.
|
||||
|
||||
## Rolling back and reporting issues
|
||||
|
||||
If you have issues migrating to OpenTofu you can follow these steps to roll back to OpenTofu 1.6.x:
|
||||
|
||||
1. Create another backup of your state file.
|
||||
2. Remove OpenTofu 1.7.x and verify that you are running OpenTofu 1.6.x.
|
||||
3. Run `tofu init`.
|
||||
4. Run `tofu plan` and verify that no unexpected changes are in the plan.
|
||||
5. 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](/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 OpenTofu 1.6.x and make sure your code works with that version. 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 OpenTofu 1.6.x and make sure your code works with that version. 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