From 4be14d43ad678c13638bdfa912b18ade8b5d261b Mon Sep 17 00:00:00 2001
From: Janos <86970079+janosdebugs@users.noreply.github.com>
Date: Tue, 19 Dec 2023 09:01:56 +0100
Subject: [PATCH] Fixes #908: Migration guide (#1021)

Signed-off-by: Janos Bonic <86970079+janosdebugs@users.noreply.github.com>
Co-authored-by: Christian Mesh <christianmesh1@gmail.com>
---
 website/docs/intro/migration.mdx | 119 +++++++++++++++++++++++++++++++
 1 file changed, 119 insertions(+)
 create mode 100644 website/docs/intro/migration.mdx

diff --git a/website/docs/intro/migration.mdx b/website/docs/intro/migration.mdx
new file mode 100644
index 0000000000..c9392f39b3
--- /dev/null
+++ b/website/docs/intro/migration.mdx
@@ -0,0 +1,119 @@
+---
+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/). 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/).