Confusing cloudflare_access_* deprecation

[ei-grad]

Starting from version 4.40.0, Cloudflare's Terraform provider is raising warnings about the use of cloudflare_access_* resources, indicating they have been renamed to cloudflare_zero_trust_*. This unexpected change deviates from typical Terraform provider practices and places a significant burden on users. There are no visible discussions or clear guidance on how to manage this renaming, leaving users without direction on how to adapt without breaking existing infrastructure.

[github-actions]

Community Note

Voting for Prioritization

• Please vote on this issue by adding a 👍 reaction to the original post to help the community and maintainers prioritize this request.
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request.

Volunteering to Work on This Issue

• If you are interested in working on this issue, please leave a comment.
• If this would be your first contribution, please review the contribution guide.

[jacobbednarz]

i'm unsure what practices you're used to or expecting however, the introduction of these new resources is in line with Terraform's own conventions and recommendations - https://developer.hashicorp.com/terraform/plugin/framework/deprecations#provider-data-source-or-resource-rename and what is used on all the major providers.

we haven't provided explicit documentation for a few reasons:

1. the new resources are operating in a backwards compatible fashion and currently only show a warning if you're using the older version.
2. we do not require any action to be taken right now. if you want to, that's great, otherwise you incrementally swap over at your leisure on your path to v5 (when it is released).
3. once v5 is ready, there will be a longer form migration guide that will include the renames (note: as resources are not safe to perform inline replacement with, we won't be automatically migrating and you'll need to do it yourself)

as for how to migrate, we also don't prescribe that as Terraform offers multiple options and it up to the operator to determine the best course of migration for their situation. stateful resources vs ephemeral, risk profiles and availability needs all come into the decision and there isn't one best way for all customers to achieve it. at a high level, the options are a two phase cut over, state mv to the new configuration or state rm and reimport the resources.

[ei-grad]

I appreciate the response, but I wanted to clarify a few points based on my experience.

and what is used on all the major providers

In my five years of working with Terraform across AWS and GCP, I haven't encountered this kind of resource renaming behavior from other major providers.

state mv to the new configuration or state rm and reimport the resources

I believe this adds unnecessary complexity for users, which is why I referred to it as "deviating from typical Terraform provider practices."

The rename block migration approach here is leading to Error: Resource type mismatch.

we do not require any action to be taken right now

Here's a screenshot from Terraform Cloud showing how the deprecation warnings are impacting the user experience:

These warnings appear in bulk for users managing complex zero trust access configurations and multiple other resource types, making it difficult to avoid them for now.

once v5 is ready, there will be a longer form migration guide that will include the renames

That would indeed be helpful. Perhaps delaying the introduction of these warnings until the migration guide is available would lessen the burden for users during this transition.

[jacobbednarz]

In my five years of working with Terraform across AWS and GCP, I haven't encountered this kind of resource renaming behavior from other major providers.

this would be because neither of those providers have renamed products 🙂 they both have stable products names built into the planning and implementation of resources. AWS will literally kill off a product and relaunch it instead of renaming it. unfortunately, that hasn't been the case with cloudflare.

Perhaps delaying the introduction of these warnings until the migration guide is available would lessen the burden for users during this transition.

experience and feedback has shown us exactly the opposite of this. the migration guide will come with the release of v5, not before it so if we wait until v5 to introduce these changes anyone who attempts the upgrade either 1) has no path at launch time or 2) requires us to backport after the release which again, prevents people from upgrading when it is announced. this also means that anyone picking up the current provider green fields can use the old resources without any feedback that they are signing themselves up for a migration. with this feedback, they can make the choice up front.

[ei-grad]

neither of those providers have renamed products

Just to clarify—this isn’t entirely accurate. AWS, for example, renamed its SSO to IAM Identity Center but kept the related Terraform resource names unchanged. That said, I understand that Cloudflare's approach and pace may require its own policy, and ultimately, it’s up to your team to determine the best path forward.

Both AWS and Google providers have had minor renames in resources or data sources, typically to improve behavior while maintaining backward compatibility. The most user-friendly approach is when deprecation warnings are not introduced until a major version update. The most frustrating scenario for users, which has been encountered with other providers as well, is when "deprecation warnings" complicate the use of the current provider version, without a seamless way to upgrade to the next version.

[ei-grad]

Also, as of now, documentation pages like https://registry.terraform.io/providers/cloudflare/cloudflare/4.43.0/docs/resources/access_group do not display deprecation messages.