An "API parity update" means that a provider, like the Okta Terraform Provider, is updated to catch up on new features or changes recently added to Okta. These are part of releases, and might appear as labels in the Okta Terraform GitHub Issues Hint; look for (api-parity).
When an "API parity update" is pushed as part of an Okta Terraform provider release, chances are the Terraform state file did not capture that update as intended. In rare cases, the state file may still contain old parameters, attributes, and values that do not match what Okta now expects, leading to unexpected errors.
This happens when the Terraform state .tfstate and the "Okta API Spec" gets out of sync due to updating the Okta Terraform provider. However, it is not caused by the Okta Terraform provider itself, but rather by how Terraform stores parameters in the state file and uses them during the Terraform "plan".
An example error from Terraform:
Error: Provider returned invalid result object after apply
NOTE: After the apply operation, the provider still indicated an unknown value for okta_app_signon_policy.sample_sign_on_policy. All values must be known after apply, so this is always a bug in the provider and should be reported in the provider's own repository. Terraform will still save the other known object values in the state.
- Okta Terraform Provider > v4.15.0/Latest
- Okta Classic Engine to Okta Identity Engine (OIE) Migration
- Terraform version > v1.x.x
- Terraform Enterprise
- Terraform got interrupted: If a terraform
applyor terraformstatecommand was stopped halfway (maybe the terminal crashed or Command+C was pressed), the state file might be incomplete or malformed. - Manually edited the state file: If the state file was adjusted and something went wrong, Terraform might not be able to read it properly.
- Okta OIE migration did not go smoothly: When migrating from Classic to OIE, a configuration may not have been successfully updated, and Terraform might still be targeting Classic APIs during resource apply.
- Okta Terraform Provider Update: A new Okta Terraform provider release introduced changes.
NOTE: Any interruptions that corrupt the state file can cause issues. The key is to ensure that the.tfstate files are consistent with what Okta expects for the resources used.
Try with -replace the Terraform resources that cause the errors entirely, and let Terraform state files be fixed to resolve them.
In this example, the is a resource okta_app_signon_policy named sample-sign-on-policy and it would look something like this in the Terraform file:
resource "okta_app_signon_policy" "sample-sign-on-policy"
{
name = "My App Sign-On Policy"
description = "Authentication Policy to be used on my app."
}NOTE: The above is, for example, purposes only; replace okta_app_signon_policy with the actual <resource name> or any other affected resources in the Okta Terraform provider, the steps will remain the same.
-
Update the Provider to the Latest Version.
-
- Ensure the Okta Terraform provider is up to date.
terraform init -upgrade
- Ensure the Okta Terraform provider is up to date.
- Plan the Replacement for Affected Resources.
-
- For example, if the
sample-sign-on-policyterraform apply, please use theterraform plancommand with the-replaceflag to preview the changes before applying them:terraform plan -replace=okta_app_signon_policy.sample-sign-on-policy
- For example, if the
NOTE: This command displays the attributes affected by the replacement so they can be reviewed before making changes.
- Apply the Replacement.
-
- If the preview looks good, apply the changes using:
terraform apply -replace=okta_app_signon_policy.sample-sign-on-pol
- If the preview looks good, apply the changes using:
NOTE: This will destroy and recreate the specified sample-sign-on-policy policy, replacing it with a new instance. Also, this process updates the API attributes, if any, in the Terraform state and adds or removes attributes in line with the Okta API updates.
- Alternative: Using taint for Older Terraform Versions.
-
- If the Terraform version does not support
-replace, or an older version is used, use thetaintcommand instead. However, Okta strongly recommends using-replaceas the preferred approach as per the Terraform docs.
- If the Terraform version does not support
