Just a quick one - I’m currently working through some upgrades from version 0.13 to version 1.2.5.
I’m following the documentation by moving to 0.14.11 first. Once I’ve got to this point (usually it just involves me changing the required terraform version in the code, pretty much) I then run an init and a plan.
If this comes back clean with no changes, do I need to run an apply or can I just progress straight up to 1.2.5? I wasn’t 100% sure if running an apply would make some background format changes or similar to the state or whether the step to 0.14 inbetween was just intended to catch issues if they were presented during the plan.
The release notes do claim you need to go from 0.13 → 0.14 → 1.x, but I’m pretty sure, having studied the changelog, that actually there’s nothing in 0.14 that requires this.
I suspect it may have been left in from previous versions release notes without being revalidated, or just left in out of abundance of caution, without any real need.
Certainly, when I had to upgrade a bunch of workspaces from even older versions, I decided I was sufficiently convinced that I could jump directly from 0.13 → 1.x - and it worked just fine.
There were a number of subtle state related changes made for 0.14 which could eliminate certain edge cases after upgrading. While it may work most of the time, it is still advised to apply the 0.14 state before continuing.
So these changes just happen in the background and aren’t highlighted during the plan?
The kind of annoying thing for us in this is that our pipeline jobs are set to skip the apply if there are no resource changes highlighted by the plan. In this case it sounds like we need to set it up for the purposes of upgrading to run an apply anyway regardless?
Many of these changes have no way to show in a plan, often because they happen during the refresh of the individual resources. The upgrade path to v1.0 requires some manual checks and application, but was intended to be a one-time process for each version. Past v1.0 all state changes are made in a backwards compatible manner so that this manual upgrade process is no longer required.
Thanks for clarifying, all understood. I just wanted to get this clear before I started our upgrades so I wasn’t performing some of the steps if there wasn’t any benefit
Do you happen to remember any more details, just to indulge my curiosity? I did spend some time looking fairly carefully at the code for anything to justify the intermediate upgrade to 0.14, and I wonder what I missed.
It is a common issue - a common workaround is to add a null_resource instance to trigger the apply, and then remove it again in the next upgrade hop to 1.x.
It’s been quite a while since I worked on that, so I don’t have any specific examples off the top of my head. Things like the calculated dependencies or status of create_before_destroy may have changed in core, and need to be updated in the state, even though there weren’t any corresponding changes to the state structures themselves.
Like I said above, it’s going to work most of the time (probably nearly all the time), but without fully evaluating all possible combinations of state and versions I can’t say one could always skip that step. Saving the state which was already generated from a successful plan just avoids some possible problems.
As far as I recall, the main reason why we included the step of running terraform apply at least once with Terraform v0.14 is as a way to verify that the Terraform v0.13 upgrade work was really completed.
We did this because during the time period between the v0.13 release and the v1.0 releases we heard from some users who thought they had completed the v0.13 upgrade and skipped directly to v0.15 but then ran into some trouble because they hadn’t actually updated the latest state snapshot to remove all of the legacy features, but it was hard to recognize that while still using v0.13 because that release still had the automatic upgrade behaviors built into it and so would act as if the upgrade were complete, even if the upgrade were only really completed in memory and not in the persisted state snapshot.
Stopping for an extra step at v0.14 ensures that everything from the v0.13 process is complete before moving on, but there is an alternative procedure that can avoid that extra step in the happy path:
Do the v0.13 upgrade process using Terraform CLI v0.13.
Upgrade to the very latest v1.x release and try running terraform apply. If it succeeds then you’re done!
If the latest v1.x release didn’t work, downgrade back to v0.13 and run terraform apply before you upgrade again.
The upgrade guide is written conversatively because it’s used by people with various levels of experience with Terraform and various different risk tolerances. If you’re okay with taking this risk and you see it working fine after you upgrade to v1.x, then I think there’s no real harm in skipping directly from v0.13 to the latest v1.x optimistically and then walking back to the old releases only if you encounter some problems after upgrading.
