terraform-upgrades.md

OpenTofu upgrades

This document will explain how a OpenTofu upgrade can be implemented and triggered.

Note: OpenTofu replaced Terraform in the CSB starting with version 1.0.0. There may still be some references to Terraform in the codebase.

Broker Configuration

In order for OpenTofu upgrades to be carried over by the broker, this capability needs to be turned on. To do so, enable the relevant flags as documented in Feature Flags Configuration and restage the app.

The brokerpak manifest must also include a terraform_upgrade_path section and the new version of the OpenTofu binary. See below.

Brokerpak specification

Each brokerpak can instruct the broker to upgrade the OpenTofu version independently. The manifest needs to be updated to include a terraform_upgrade_path section and the new version of the OpenTofu binary. Optionally, the terraform_state_provider_replacements has to be provided. This is specially needed for the upgrade from older brokerpak versions. For more information on these manifest sections, see brokerpak-specification and OpenTofu Upgrade Path object

Note: OpenTofu does not recommend making OpenTofu language changes at the same time that performing an upgrade. Hence, ideally these changes should be included in a separate release of your brokerpak and all existing instances should be upgraded before installing a subsequent release.

Example Brokerpak manifest additions

...
terraform_upgrade_path:
- version: 1.6.0
- version: 1.6.2
terraform_binaries:
- name: tofu
  version: 1.6.0
  source: https://github.com/opentofu/opentofu/archive/refs/tags/v1.6.0.zip  
- name: tofu
  version: 1.6.2
  source: https://github.com/opentofu/opentofu/archive/refs/tags/v1.6.2.zip
  default: true
...

Note: terraform_upgrade_paths must be in ascending order and one entry in the terraform_binaries list must be marked default: true.

Triggering an upgrade

Upgrades are not performed automatically. For an upgrade to be initiated for a service instance, a request to update the instance without any parameters must be made or a cf upgrade-service <instance_name> has to be executed.

When an upgrade is available for an instance, all other operations are blocked until the upgrade is performed. Update, Bind and Unbind will return an error message indicating that an upgrade operation needs to be performed first.

Service instance upgrades will also upgrade existing bindings to those instances.