Upgrading a Stack to a Later Terraform Version

To successfully upgrade your stack, you must have the following:

• A MacOS, Linux, or Windows computer for running command line tools.

• Software to create and unpack .zip archives, such as 7-ZIP.

• IAM policies to manage stacks and jobs.

Following are supported upgrade paths by initial version.

This task uses the Console. For CLI and API instructions, see Getting a Stack's Details, Creating a Plan Job, and Creating an Apply Job.

1. Open the Stack details page for the stack you want to upgrade:

   1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.

   2. Under List scope, choose the Compartment that contains the stack.

   3. Select the name of the stack.

2. Confirm that this stack is using the expected Terraform version: In the Stack details page, under Stack information, review the Terraform version.

3. Check for pending changes to infrastructure:

   1. Select Plan.

      When the action finishes, the Job details page is displayed for the related job.

   2. In the Job details page, in the Logs tab, review the log for the completed plan action.

      The log contents indicate whether the stack is up to date or has pending changes.

      Example for a stack that is up to date (no pending changes):

      No changes. Infrastructure is up-to-date.

4. If the log contents indicate pending changes, then apply pending changes:

   1. Select Stack details to go back to the Stack details page.

   2. Select Apply.

      When the action finishes, the Job details page is displayed for the related job.

   3. Confirm that the apply action was successful: In the Job details page, in the Logs tab, review the log for the completed apply action.

When the stack infrastructure is up to date, you can proceed to the next task for downloading Terraform configuration and state files.

This task uses the command line and the Console. For CLI and API instructions for downloading a Terraform configuration and a Terraform state, see Getting a Stack's Terraform Configuration and Getting a Stack's State File.

1. On a computer that can run command line tools, create a folder to store the downloaded Terraform configuration and state.

   Example folder name: c:\StackUpgrade

2. Open the Stack Details page for the stack that you want to upgrade:

   1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.

   2. Under List scope, choose the Compartment that contains the stack that you want to upgrade.

   3. Select the name of the stack.

      The Stack details page displays.

3. Download the Terraform configuration: In the Stack information tab, to the right of Terraform configuration, select Download.

4. Download the Terraform state file: Go to More actions and select Download Terraform state.

When the Terraform configuration and state are downloaded, you can proceed to the next task for upgrading the Terraform configuration.

This task provides customized steps for upgrading a Terraform configuration used with Resource Manager.

1. On the same computer that you used to store the downloaded Terraform configuration and state files, download the .zip files needed to upgrade your Terraform configuration:

   • From https://releases.hashicorp.com/terraform, download the .zip file for your target Terraform version and operating system.

     For example, for Terraform 0.13 on Mac, download the Darwin version: https://releases.hashicorp.com/terraform/0.13.7/terraform_0.13.7_darwin_amd64.zip.

2. Extract the contents of each .zip file.

3. Update the provider configuration to add arguments such as user_ocid, fingerprint and private_key_path. You may have commented out these arguments previously.

   Example of commented-out arguments:

   provider "oci" {
     tenancy_ocid = var.tenancy_ocid
     /*
     user_ocid = var.user_ocid
     fingerprint = var.fingerprint
     private_key_path = var.private_key_path
     */
     region = var.region
   }

4. To follow code examples in the rest of this procedure, rename the extracted file as terraform_<major-version>.

   Example: terraform_13

5. To make the command (extracted file) accessible, store it in a directory that is present in your PATH directory.

6. Open a command prompt.

7. Change directory to the folder where you stored the downloaded stack information.

   Example:

   cd c:\StackUpgrade

8. To initialize Terraform, run the following command:

   terraform_<major-version> init

   Example:

   terraform_13 init

9. To upgrade the syntax of your Terraform configuration, run the command for the target Terraform version:

   Target Terraform Version	Command
   0.13	terraform_13 13upgrade
   0.14	terraform_14 14upgrade
   0.15 and later	None needed. If above upgrades were successfully applied during the process, then no special changes are needed for upgrading the configuration.

   The output indicates whether the upgrade was successful.

   If successful, go to step 12.

   If not successful, then make manual changes to your Terraform configuration files as directed.

10. Create a .zip archive of your Terraform configuration files.

    Example .zip archive: c:\StackUpgrade\MyConfigUpgraded.zip

    Ensure that the archive omits the Terraform state file (terraform.tfstate) and the .terraform directory to satisfy the required file structure for Terraform configurations.

11. If a source code control system (such as GitHub) is used for the stack's Terraform configuration, then commit the upgraded Terraform configuration there.

    The most recent commit is used when you run jobs on the stack.

12. If an Object Storage bucket is used for the stack's Terraform configuration, then change the contents of that bucket to correspond with the upgraded Terraform configuration.

    Note
    
    Back up the current bucket before changing it to correspond to the upgraded Terraform configuration. Limit the bucket to files that are intended for use with Terraform.

    The most recent contents of the bucket are used when you run jobs on the stack.

When the Terraform configuration is successfully upgraded to the target Terraform version, then you can proceed to the next task for upgrading the stack.

This task uses the Console. For CLI and API instructions for updating a stack, see Updating a Stack.

1. Reopen the Stack details page for the stack you are upgrading:

   1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.

   2. Under List scope, choose the Compartment that contains the stack you are upgrading.

   3. Select the name of the stack.

2. Open the Edit stack dialog box: On the Stack details page for the stack, select Edit.

3. Upload the upgraded Terraform configuration to the stack: Drag and drop the .zip file onto the dialog's control or select Browse and navigate to the location of the .zip file.

   Example file path: c:\StackUpgrade\MyConfigUpgraded.zip

   The dialog box is populated with information contained in the Terraform configuration.

   Note
   
   Skip this uploading step if the stack's Terraform configuration is stored in a source code control system (such as GitHub) or in an Object Storage bucket, then the stack was configured to use the upgraded Terraform configuration in Task 3: Upgrade the Configuration when you committed the change to source code or uploaded the file to the bucket.)

4. Specify the target Terraform version: Change the Terraform version.

5. Select Next twice, then select Save changes.

The stack is now synchronized with the upgraded Terraform configuration and specified Terraform version. You can now proceed to the next task for importing the state file.

This task uses the Console. For CLI and API instructions, see Creating an Import Job.

1. Reopen the Stack details page for the stack you are upgrading:

   1. Open the navigation menu and click Developer Services. Under Resource Manager, click Stacks.

   2. Under List scope, choose the Compartment that contains the stack you are upgrading.

   3. Select the name of the stack.

2. Go to More actions and select Import state.

3. In the Import panel, add the downloaded Terraform state file (example file path: c:\StackUpgrade\terraform.tfstate): Either drag and drop the file onto the dialog's control, or select Browse and navigate to the file location.

4. Select Import.

   The import job is created. The new job is listed under Jobs.

   When the job finishes, the Job details page opens.

5. Confirm successful import: In the Logs section under Resources, review the logs.

After a successful import of the state file, proceed to the next task for checking for issues.

This task uses the Console. For CLI and API instructions, see Creating a Plan Job, Getting Logs for a Job, Getting Logs Content for a Job, and Updating a Stack.

1. In the Stack Details page for the newly upgraded stack, check for issues with the Terraform configuration or state file by running the plan action:

   1. Select Plan.

      When the action finishes, the Job details page is displayed for the related job.

   2. In the Job details page, in the Logs tab, review the log for the completed plan action.

      The log contents might list issues, such as old, deprecated HCL1 syntax.

2. Resolve any listed issues:

   1. On your computer, access and manually update the Terraform configuration.

   2. Upload the newly updated Terraform configuration to the stack:

      1. In the Stack details page, select Edit stack.

      2. Either drag and drop the Terraform configuration onto the dialog's control or select Browse and navigate to the file location.

         The dialog box is populated with information contained in the Terraform configuration.

      3. Select Next twice, then select Save changes.

3. Run the plan action again to confirm that the issues are no longer listed in the associated log contents.