From 09403c73281d298b63b9731b48a72513c51a542b Mon Sep 17 00:00:00 2001
From: AbstractionFactory
 <179820029+abstractionfactory@users.noreply.github.com>
Date: Fri, 10 Jan 2025 11:40:17 +0100
Subject: [PATCH] Docs prep for 1.10 (#2357)

Signed-off-by: AbstractionFactory <179820029+abstractionfactory@users.noreply.github.com>
---
 website/docs/index.mdx           |   2 +-
 website/docs/intro/upgrading.mdx |  44 +++----
 website/docs/intro/whats-new.mdx | 216 +++++--------------------------
 3 files changed, 53 insertions(+), 209 deletions(-)

diff --git a/website/docs/index.mdx b/website/docs/index.mdx
index d5a19e322d..5276077542 100644
--- a/website/docs/index.mdx
+++ b/website/docs/index.mdx
@@ -10,7 +10,7 @@ import DocVersionBadge from "@theme/DocVersionBadge";
 
 ### OpenTofu Documentation <DocVersionBadge />
 
-Welcome to OpenTofu 1.8! This version brings you a host of new features like early evaluation, provider mocking in tests and more. If you are coming from a previous OpenTofu or Terraform version you can [read the details about the new features here &raquo;](intro/whats-new.mdx)
+Welcome to OpenTofu 1.10! This version brings a lot of new features and improvements to OpenTofu. If you are coming from a previous OpenTofu or Terraform version you can [read the details about the new features here &raquo;](intro/whats-new.mdx)
 
 <DocCardList
     items={[
diff --git a/website/docs/intro/upgrading.mdx b/website/docs/intro/upgrading.mdx
index 2311b3539d..ef54b0a149 100644
--- a/website/docs/intro/upgrading.mdx
+++ b/website/docs/intro/upgrading.mdx
@@ -1,29 +1,29 @@
 ---
 sidebar_position: 5
-sidebar_label: Upgrading from OpenTofu 1.6.x/1.7.x
+sidebar_label: Upgrading from OpenTofu 1.7.x/1.8.x/1.9.x
 description: |-
-    Learn how to upgrade OpenTofu from version 1.6.x/1.7.x to 1.8.0.
+    Learn how to upgrade OpenTofu from version 1.7.x/1.8.x/1.9.x to 1.10.0.
 ---
 
-# Upgrading from OpenTofu 1.6.x/1.7.x
+# Upgrading from OpenTofu 1.7.x/1.8.x/1.9.x
 
-OpenTofu 1.8.x is mostly compatible with OpenTofu 1.6.x and 1.7.x (other than one minor breaking change in the S3 backend). This migration guide will take you through the process of
-upgrading OpenTofu to version 1.8.0.
+OpenTofu 1.8.x is mostly compatible with previous OpenTofu versions (other than one minor breaking change in the S3 backend). This migration guide will take you through the process of upgrading OpenTofu to version 1.8.0.
 
 ## Step 0: Prepare a disaster recovery plan
 
-Although OpenTofu 1.8 is mostly compatible with version 1.6 and 1.7, you should take the necessary precautions to prevent
-accidents. Make sure you have an up to date and *tested* disaster recovery plan.
+Although OpenTofu 1.10 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: If using an S3 backend - Remove any use of `use_legacy_workflow` from S3 backend configurations
 
-If you are using the S3 backend, with `use_legacy_workflow` set, you'd have to remove it. This field has been deprecated in version 1.7.0, and has been changed to default to `false`.
-The legacy workflow of authentication is no longer supported. Please start using the new authentication method, which is more consistent with other AWS tools
+If you are using the S3 backend, with `use_legacy_workflow` set, you'd have to remove it. This field has been deprecated in version 1.7.0, and has been changed to default to `false`. The legacy workflow of authentication is no longer supported. Please start using the new authentication method, which is more consistent with other AWS tools
 
-## Step 2: Apply all changes with OpenTofu 1.6.x/1.7.x
+## Step 2: If you are using `ghcr.io/opentofu/opentofu` as a base image
 
-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.
+If you are using `ghcr.io/opentofu/opentofu` as a base image for your containers, you will need to move away from this setup. Please follow the instructions on the container installation page to build your own base image.
+
+## Step 3: 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
@@ -36,18 +36,18 @@ OpenTofu has compared your real infrastructure against your
 configuration and found no differences, so no changes are needed.
 ```
 
-## Step 3: Install OpenTofu 1.8.x
+## Step 4: Install OpenTofu 1.10.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.8.0
+OpenTofu v1.10.0
 on linux_amd64
 ```
 
-## Step 4: Back up your state file
+## Step 5: 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.
@@ -55,7 +55,7 @@ a local state file, you can simply make a copy of your `terraform.tfstate` file
 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.8.x
+## Step 6: Initialize OpenTofu 1.10.x
 
 :::warning
 
@@ -75,7 +75,7 @@ If you are using the S3 backend - You will need to run `tofu init -reconfigure`
 
 :::
 
-## Step 6: Inspect the plan
+## 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 OpenTofu 1.6.x/1.7.x and troubleshoot your migration. (See the Troubleshooting
@@ -92,17 +92,17 @@ 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
+## 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.
 
 ## 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.7.x:
+If you have issues migrating to OpenTofu you can follow these steps to roll back to OpenTofu 1.7.x/1.8.x/1.9.x:
 
 1. Create another backup of your state file.
-2. Remove OpenTofu 1.8.x and verify that you are running OpenTofu 1.6.x/1.7.x.
+2. Remove OpenTofu 1.19.x and verify that you are running OpenTofu 1.7.x/1.8.x/1.9.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.
@@ -117,11 +117,11 @@ If you encounter any issues during the migration to OpenTofu, you can join the <
 ### 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/1.7.x and make sure your code works with that version. If your code works, please
+Please roll back to OpenTofu 1.7.x/1.8.x/1.9.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/1.7.x and make sure your code works with that version. If your code works, please
+Please roll back to OpenTofu 1.7.x/1.8.x/1.9.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/).
diff --git a/website/docs/intro/whats-new.mdx b/website/docs/intro/whats-new.mdx
index c2578f1c5a..615ead642e 100644
--- a/website/docs/intro/whats-new.mdx
+++ b/website/docs/intro/whats-new.mdx
@@ -1,209 +1,53 @@
 ---
 sidebar_position: 2
-sidebar_label: What's new in version 1.7?
+sidebar_label: What's new in version 1.10?
 description: |-
-  Learn all about the new features in OpenTofu 1.7.
+  Learn all about the new features in OpenTofu 1.10.
 ---
 
-# What's new in OpenTofu 1.7?
+# What's new in OpenTofu 1.10?
 
-This page will run you through the most important changes in OpenTofu 1.7:
+This page will run you through the most important changes in OpenTofu 1.10:
 
-- [State encryption](#state-encryption)
-- [Provider-defined functions](#provider-defined-functions)
-- [Removed block](#removed-block)
-- [Loopable import blocks](#loopable-import-blocks)
-- [Built-in function changes](#built-in-function-changes)
-- [CLI changes](#cli-changes)
-- [Testing feature changes](#testing-feature-changes)
+- [New features](#new-features)
+  - [New built-in functions](#new-built-in-functions)
+- [Improvements to existing features](#improvements-to-existing-features)
+  - [External programs as encryption key providers (experimental)](#external-programs-as-encryption-key-providers-experimental)
+  - [Smaller improvements](#smaller-improvements)
+- [Deprecations](#deprecations)
+  - [Using `ghcr.io/opentofu/opentofu` as a base image](#using-ghcrioopentofuopentofu-as-a-base-image)
+- [Bugfixes](#bugfixes)
 
-## State encryption
+## New features
 
-State encryption is one of the flagship features of this release. We have prepared a [full documentation](../language/state/encryption.mdx) for this feature.
+### New built-in functions
 
-Before you test this feature, please **make a backup** of your state file. You can then add the following block to enable state encryption:
+New builtin provider functions added ([#2306](https://github.com/opentofu/opentofu/pull/2306)) :
 
-```hcl
-terraform {
-  encryption {
-    key_provider "pbkdf2" "my_passphrase" {
-      ## Enter a passphrase here:
-      passphrase = ""
-    }
+- `provider::terraform::decode_tfvars` - Decode a TFVars file content into an object.
+- `provider::terraform::encode_tfvars` - Encode an object into a string with the same format as a TFVars file.
+- `provider::terraform::encode_expr` - Encode an arbitrary expression into a string with valid OpenTofu syntax.
 
-    method "aes_gcm" "my_method" {
-      keys = key_provider.pbkdf2.my_passphrase
-    }
+## Improvements to existing features
 
-    ## Remove this after the migration:
-    method "unencrypted" "migration" {
-    }
+### External programs as encryption key providers (experimental)
 
-    state {
-      method = method.aes_gcm.my_method
+State encryption now supports using external programs as key providers. Additionally, the PBKDF2 key provider now supports chaining via the `chain` parameter. For details, [see the related documentation](../language/state/encryption.mdx#external-experimental)
 
-      ## Remove the fallback block after migration:
-      fallback{
-        method = method.unencrypted.migration
-      }
-      ## Enable this after migration:
-      #enforced = true
-    }
-  }
-}
-```
+This functionality is experimental and may be changed in future OpenTofu versions.
 
-You can migrate back using the following syntax:
+### Smaller improvements
 
-```hcl
-terraform {
-  encryption {
-    key_provider "pbkdf2" "my_passphrase" {
-      ## Enter a passphrase here:
-      passphrase = ""
-    }
+* OpenTofu will now recommend using `-exclude` instead of `-target`, when possible, in the error messages about unknown values in `count` and `for_each` arguments, thereby providing a more definitive workaround. ([#2154](https://github.com/opentofu/opentofu/pull/2154))
 
-    method "aes_gcm" "my_method" {
-      keys = key_provider.pbkdf2.my_passphrase
-    }
+## Deprecations
 
-    method "unencrypted" "migration" {
-    }
+### Using `ghcr.io/opentofu/opentofu` as a base image
 
-    state {
-      method  = method.unencrypted.migration
-      enforced = false
-      fallback{
-        method = method.aes_gcm.my_method
-      }
-    }
-  }
-}
-```
+Using the `ghcr.io/opentofu/opentofu` image as a base image for custom images is deprecated and doesn't work as of OpenTofu 1.10. The reason behind this change is security: while we regularly update OpenTofu itself when security-relevant updates arise, providing a base image would require an update roughly once a week, which we are currently not equipped to do.
 
-If you have access to an AWS, GCP account, or an OpenBao/MPL-licensed HashiCorp Vault installation, you can also [test these key providers](../language/state/encryption.mdx#key-providers).
+However, we have added instructions on building your own base image in the [containerized installation instructions](./install/docker.mdx#building-your-own-image).
 
-## Provider-defined functions
+## Bugfixes
 
-The new Terraform Plugin SDK added support for [provider-defined functions](../language/functions/index.mdx#provider-defined-functions) that you can use directly in OpenTofu. This is a significant improvement over using data sources as provider-defined functions don't increase the size of your state file and require less code to write.
-
-If you want to test provider-defined functions, you can use the [corefunc](https://library.tf/providers/northwood-labs/corefunc/latest) provider by [Ryan Parman](https://github.com/skyzyx):
-
-```hcl
-terraform {
-  required_providers {
-    corefunc = {
-      source = "northwood-labs/corefunc"
-      version = "1.4.0"
-    }
-  }
-}
-
-provider "corefunc" {
-}
-
-output "test" {
-  value = provider::corefunc::str_snake("Hello world!")
-  # Prints: hello_world
-}
-```
-
-What's more, we added an OpenTofu-only feature to let providers dynamically define custom functions based on your configuration. This enhancement allows you to fully integrate other programming languages as [shown in our live stream](https://www.youtube.com/watch?v=6OXBv0MYalY). You can try out this functionality with our experimental [Lua](https://github.com/opentofu/terraform-provider-lua) and [Go](https://github.com/opentofu/terraform-provider-go) providers.
-
-## Removed block
-
-The removed block lets you remove a resource from the state file but keep it on the infrastructure. We have prepared a [full documentation](../language/resources/syntax.mdx#removing-resources) for this feature. You can test it by creating a resource first:
-
-```hcl
-resource "local_file" "test" {
-  content = "Hello world!"
-  filename = "test.txt"
-}
-```
-
-After applying, you can replace the resource with a removed block:
-
-```hcl
-removed {
-  from = local_file.test
-}
-```
-
-After the next apply, you will see that the `local_file.test` resource no longer exists in your state file, but the `test.txt` file should still exist on your disk. You can now remove the removed block safely.
-
-## Loopable import blocks
-
-We made several improvements to the declarative import blocks, most prominently you can now use the `for_each` instruction on the block. We have prepared a [full documentation](../language/import/index.mdx#importing-multiple-resources) for this feature.
-
-In previous OpenTofu versions, you could already use the `import` block to declaratively import resources, for example:
-
-```hcl
-resource "random_id" "test_id" {
-  byte_length = 8
-}
-
-import {
-  to = random_id.test_id
-  id = "Y2FpOGV1Mkk"
-}
-
-output "id" {
-  value = random_id.test_id.b64_url
-}
-```
-
-In this new version you can now also declaratively import resources in a loop:
-
-```hcl
-variable "server_ids" {
-  type = list(string)
-}
-
-resource "random_id" "test_id" {
-  byte_length = 8
-  count = 2
-}
-
-import {
-  to = random_id.test_id[tonumber(each.key)]
-  id = each.value
-  for_each = {
-    for idx, item in var.server_ids: idx => item
-  }
-}
-
-output "id" {
-  value = random_id.test_id.*.b64_url
-}
-```
-
-The example above will let you specify some random IDs from a variable, and let others be automatically generated.
-
-## Built-in function changes
-
-This release also contains several new functions and changes to existing functions:
-
-- New function: [templatestring](../language/functions/templatestring.mdx)
-- New function: [base64gunzip](../language/functions/base64gunzip.mdx)
-- New function: [cidrcontains](../language/functions/cidrcontains.mdx)
-- New function: [urldecode](../language/functions/urldecode.mdx)
-- New function: [issensitive](../language/functions/issensitive.mdx)
-- [nonsensitive](../language/functions/nonsensitive.mdx) no longer returns an error when the applied values are not sensitive.
-- [templatefile](../language/functions/templatefile.mdx) now supports recursion up to a depth of 1024.
-
-## CLI changes
-
-There are also several changes to the CLI:
-
-- `tofu init` now supports the `-json` flag for JSON output.
-- `tofu plan` now has a `-concise` flag to shorten the plan output.
-- `tofu console` now works on Solaris and AIX.
-- The CLI now supports the XDG directory specification.
-- Aliases for:
-    - `state list` &rarr; `state ls`
-    - `state mv` &rarr; `state move`
-    - `state rm` &rarr; `state remove`
-
-## Testing feature changes
-
-- Tofu now reads the `.tfvars` file from the tests folder.
+- Fixed an issue where an invalid provider name in the `provider_meta` block would crash OpenTofu rather than report an error ([#2347](https://github.com/opentofu/opentofu/pull/2347))
\ No newline at end of file