IntenseWebs/opentofu
3
0
Fork 0
mirror of https://github.com/opentofu/opentofu.git synced 2025-02-25 18:45:20 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docs prep for 1.10 (#2357)

Browse Source 
Signed-off-by: AbstractionFactory <179820029+abstractionfactory@users.noreply.github.com>
This commit is contained in:
AbstractionFactory 2025-01-10 11:40:17 +01:00 committed by GitHub
parent d0d35d2dcd
commit 09403c7328
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 53 additions and 209 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
website/docs/index.mdx
View File

@ -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={[

44
website/docs/intro/upgrading.mdx
View File

@ -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/).

216
website/docs/intro/whats-new.mdx
View File

@ -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))