mirror of
https://github.com/opentffoundation/opentf.git
synced 2025-12-21 10:47:34 -05:00
120 lines
4.6 KiB
Plaintext
120 lines
4.6 KiB
Plaintext
---
|
|
sidebar_position: 5
|
|
sidebar_label: Upgrading from OpenTofu 1.8.x/1.9.x/1.10.x
|
|
description: |-
|
|
Learn how to upgrade OpenTofu from version 1.8.x/1.9.x/1.10.x to 1.11.0.
|
|
---
|
|
|
|
# Upgrading from OpenTofu 1.8.x/1.9.x/1.10.x
|
|
|
|
OpenTofu 1.11.x is mostly compatible with previous OpenTofu versions. This migration guide will take you through the process of upgrading OpenTofu to version 1.11.0.
|
|
|
|
## Step 0: Prepare a disaster recovery plan
|
|
|
|
Although OpenTofu 1.11 is mostly compatible with previous versions, 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.7.x/1.8.x/1.9.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 2: Install OpenTofu 1.11.x
|
|
|
|
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 and receive the correct version:
|
|
|
|
```
|
|
$ tofu --version
|
|
OpenTofu v1.11.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 1.11.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.
|
|
|
|
:::note
|
|
|
|
If you are using the S3 backend - You will need to run `tofu init -reconfigure` to reinitialize the backend.
|
|
|
|
:::
|
|
|
|
## 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 OpenTofu 1.8.x/1.9.x/1.10.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 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 and reporting issues
|
|
|
|
If you have issues migrating to OpenTofu you can follow these steps to roll back to OpenTofu 1.8.x/1.9.x/1.10.x:
|
|
|
|
1. Create another backup of your state file.
|
|
2. Remove OpenTofu 1.11.x and verify that you are running OpenTofu 1.8.x/1.9.x/1.10.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 <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 OpenTofu 1.8.x/1.9.x/1.10.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.8.x/1.9.x/1.10.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/).
|