Upgrading a Stack to a Later Terraform Version
Upgrade a stack in Resource Manager to a later Terraform version.
These instructions don't apply to Resource Manager stacks created through Marketplace.
These steps are completed in the command line and the Console.
For information about Terraform versions supported by Resource Manager, see Supported Terraform Versions.
Before You Begin
To successfully upgrade your stack, you must have the following requirements:
-
A MacOS, Linux, or Windows computer for running command line tools
-
Software to create and unpack
.zip
archives, such as 7-ZIP
Automatic Upgrade
To support deprecation of older Terraform versions (earlier than 1.5.x), Resource Manager will try an automatic Terraform version upgrade. This automatic upgrade will be attempted whenever you run a successful apply job (job state is succeeded) on a stack that's configured for an older Terraform version.
The target version for the attempted upgrade depends on the stack's currently configured Terraform version. Intermediary automatic upgrades move the stack toward 1.5.x in one or more successful upgrade attempts. Using intermediary upgrades works around differences in HCL syntax, provider block definitions, and state file differences, as discussed in the manual upgrade instructions. The target version for an upgrade is selected as follows:
- The target version to upgrade 0.12.x is 0.13.x.
- The target version to upgrade 0.13.x is 0.14.x.
- The target version to upgrade 0.14.x, 1.0.x, 1.1.x, or 1.2.x is 1.5.x.
The upgrade attempt only occurs after an apply job succeeds (job state is succeeded).
- If the upgrade succeeds, then the stack's Terraform version and state file are upgraded to 1.5.x (or intermediary version). No further action is required.
- If the upgrade fails, then the stack's Terraform version is unchanged, and resources aren't affected. An upgrade failure message appears in the stack's details page. In this situation, get logs for the apply job (select Show terraform upgrade logs for information about the failure) and then update the Terraform configuration. The next successful apply job that you run on this stack will trigger the automatic upgrade process by Resource Manager.Note
Even if the upgrade fails, the job state is still succeeded.
Upgrade Paths
Following are supported upgrade paths by initial version.
Initial Terraform Version | Upgrade Path |
---|---|
0.12 | In sequence, upgrade to each supported version: 0.13, 0.14, 1.0 (recommended), 1.1, 1.2, 1.5. |
0.13 | In sequence, upgrade to each supported version: 0.14, 1.0 (recommended), 1.1, 1.2, 1.5. |
0.14 | In sequence, upgrade to each supported version: 1.0 (recommended), 1.1, 1.2, 1.5. |
1.0 | In sequence, upgrade to each supported version: 1.1, 1.2, 1.5. |
1.1 | In sequence, upgrade to each supported version: 1.2, 1.5. |
1.2 | Upgrade to 1.5. |
See Terraform's official upgrade guides:
Task 1: Confirm Up-to-Date Infrastructure
This task uses the Console. For CLI and API instructions for a step, see the associated link.
Task 2: Download the Configuration and State
If the stack's Terraform configuration is stored in a source code control system, such as GitLab, then check out and download the Terraform configuration from there.
If the stack's Terraform configuration is stored in a bucket, then download the Terraform configuration from there.
This task uses the Console. For CLI and API instructions for a step, see the associated link.
Task 3: Upgrade the Configuration
Task 4: Upgrade the Stack
Task 5: Import the State
Task 6: Check for Issues
This task uses the Console. For CLI and API instructions for a step, see the associated link.
Troubleshooting Logs During an Upgrade
Error: Failed to install providers
The log shows an error message similar to the following.
Error: Failed to install providers
Could not find required providers, but found possible alternatives:
hashicorp/gitlab -> gitlabhq/gitlab
If these suggestions look correct, upgrade your configuration with the following command:
terraform 0.13upgrade .
The configuration doesn't meet requirements for the specified Terraform version. Version 0.13.x and later don't use this syntax for providers. Example configuration causing this error:
provider "gitlab" {
token = "glpat-_abcd"
}
# Add a project owned by the user
resource "gitlab_project" "sample_project" {
name = "example"
}
Add a required_providers
block and explicitly mention the source information for the provider. For more information, see Requiring Providers. Example update:
terraform {
required_providers {
oci = {
source = "oracle/oci"
version = "5.46"
}
gitlab = {
source = "gitlabhq/gitlab"
version = "17.8.0"
}
}
}
Error: Invalid quoted type constraints
The log shows an error message similar to the following.
Error: Invalid quoted type constraints on variables.tf line 18, in variable "vcn_dns_label"
18: type = "string"
Terraform 0.11 and earlier required type constraints to be given in quotes,
but that form is now deprecated and will be removed in a future version of
Terraform. Remove the quotes around "string".
The configuration doesn't meet requirements for the specified Terraform version. Version 1.0.x and later don't use quotes for type declarations of variables. Example configuration causing this error:
variable "vcn_dns_label" {
type = "string"
default = "vcn"
}
Remove the quotes from type declarations of variables. Example update:
variable "vcn_dns_label" {
type = string
default = "vcn"
}
Error: Error in function call (map)
The log shows an error message similar to the following.
Error: Error in function call
on main.tf line 44, in resource "oci_core_subnet" "this":
44: display_name = lookup(map("a", "b", "c", "d"), "a", "default")
────────────────
while calling map(vals...)
Call to function "map" failed: the "map" function was deprecated in Terraform v0.12 and
is no longer available; use tomap({ ... }) syntax to write a literal map.
The configuration doesn't meet requirements for the specified Terraform version. Version 1.0.x and later don't use this syntax for maps. Example configuration causing this error:
resource "oci_core_subnet" "this" {
...
...
vcn_id = lookup(map("a", 1, "b", 2), "a", "default")
...
...
}
Correct the syntax for the map to use tomap()
. Example update:
resource "oci_core_subnet" "this" {
...
...
vcn_id = lookup(tomap({"a" = 1, "b" = 2}), "a", "default")
...
...
}
Error: Error in function call (list)
The log shows an error message similar to the following.
Error: Error in function call
on main.tf line 35, in resource "oci_core_subnet" "this"
35: count = length(list("phx-ad-1"", ""phx-ad-2"))
Call to function "list"" failed: the ""list" function was deprecated in
Terraform v0.12 and is no longer available; use tolist([ ... ]) syntax to
write a literal list.
The configuration doesn't meet requirements for the specified Terraform version. Version 1.0.x and later don't use this syntax for lists. Example configuration causing this error:
resource "oci_core_subnet" "this" {
count = length(list("phx-ad-1", "phx-ad-2"))
...
...
}
Correct the syntax for the list to use tolist()
. Example update:
resource "oci_core_subnet" "this" {
count = length(tolist(["phx-ad-1", "phx-ad-2"]))
...
...
}
Error: The ["*"] form of ignore_changes wildcard is deprecated
The log shows an error message similar to the following.
Getting providers from registry and/or custom terraform providers
resource "oci_core_subnet" "this"
44: ignore_changes = ["*"]
The ["*"] form of ignore_changes wildcard is was deprecated and is now
invalid. Use "ignore_changes = all" to ignore changes to all attributes.
The configuration doesn't meet requirements for the specified Terraform version. Version 1.0.x and later don't use this syntax for ignore_changes
wildcards. Example configuration causing this error:
resource "oci_core_subnet" "this" {
...
...
lifecycle {
ignore_changes = ["*"]
}
}
Use ignore_changes = all
instead. Example update:
resource "oci_core_subnet" "this" {
...
...
lifecycle {
ignore_changes = all
}
}
Issue: Deprecated HCL Syntax
The log indicates existence of deprecated HCL syntax.
The configuration doesn't meet requirements for the specified Terraform version.
Update the configuration to omit deprecated HCL syntax.