When managing Okta using the Okta Terraform provider, administrators may need to upgrade the provider itself. An improper upgrade can lead to unintended or breaking changes in the Okta environment. This article provides the recommended step-by-step process for safely upgrading the provider, which includes testing all changes against a preview organization before deploying to production.

• Terraform

It is expected that, as the product evolves, declarative infrastructure as code tools, such as Terraform, will receive updates to their declarations over time. These updates can introduce new resources, modify existing ones, or deprecate attributes. Without a proper testing and validation process, applying a new provider version directly to a production environment could result in dangerous configuration drift.

The general approach to safely upgrading the Okta Terraform provider is similar to any safe deployment practice. All changes in the Terraform provider should be tested against a non-production environment before elevating them to production. For example, a typical process would look like this:

1. Review the Changelog
   • Before upgrading, always review the Okta Terraform Provider Changelog. Pay close attention to any entries that introduce new syntax. 
2. Isolate Changes
   • Create a new branch in the version control system (for example, Git) to manage the upgrade process. This isolates the upgrade and treats it as a unique deployment
3. Update Provider Version
   • In the Terraform configuration file (for example, versions.tf or main.tf), update the version constraint for the Okta provider to the desired new version. For example, to upgrade to the latest 6.x version, a config like the following will be needed:

     terraform {
       required_providers {
         okta = {
           source  = "okta/okta"
           version = "~> 6.0"
         }
       }
     }

4. Initialize the New Provider
   • Run the terraform init command with the -upgrade flag to download and install the new provider version specified in the configuration.

     terraform init -upgrade

5. Plan Against Preview Org
   • Configure the Terraform deployment to point to the Okta preview (sandbox) organization. Run the terraform plan command to generate an execution plan. This command shows what changes, if any, Terraform will make to the Okta resources based on the new provider version. 

6. Analyze the Plan 

• • Review the output of terraform plan. Look for:
    • Unexpected resource destroy or create actions.
    • Modifications (~) to sensitive resources like policies, rules, or application settings.
    • Any errors or warnings generated by the provider.

7. Resolve Terraform config changes
   • If the terraform plan indicated that there will be config drift, review and update the declarations accordingly.
8. Apply to Preview Org
   • If the execution plan is acceptable and matches expectations, apply the changes to the preview organization using terraform apply.
9. Validate in Preview Org
   • After the apply is complete, log in to the Okta preview org's Admin Console. Manually verify that the changes were applied correctly and that core functionality has not been negatively impacted.
10. Deploy to the higher environment
    • Once all the changes have been verified against the preview environment, follow the organization's standard deployment processes to deploy to higher-level environments.