Terraform provider: make version mandatory and immutable

[hugoShaka]

This is a breaking change, merge this once we know we won't do any new v14 release.

To mitigate gravitational/teleport#36773 we will enforce the resource version to be set starting with Teleport 15. This will ensure no surprise upgrade happens.

The documentation PR is here: gravitational/teleport#36774

Note: protos from the docs PR were used to generate the schema in order to have the nice version messages and render a proper reference.

[tigrato]

Worth mentioning that when dealing with roles, it can impact access rules when upgrading the provider across major versions

[webvictim]

I don't want to sound like a broken record but IMO we do also need some central reference for what role versions can be used, what is current, what the difference is between them, etc. We'll probably get a lot of questions about "what role version should I use" otherwise (more than we usually get)

[hugoShaka]

I wrote the tests, and I have bad news: we built a system with hysteresis 😭 .

A role upgraded to v6 from v5, and a role created directly with v6 with the same spec won't have the same rules.

Resources have their defaults set on initial creation, then never again. If you create a resource v5, you will have the v5 defaults, even after you upgrade to v6.

There's an interaction between Teleport resources without clear field ownership and how Terraform measures the existing state to do drift detection. Teleport edits the spec server-side, losing the original user intention. Then TF imports this amended resource back in its state, importing all the defaults and keeping them ad vitam.

The conclusion is that upgrading a resource between versions is not safe. As re-creating it from scratch will not lead to the same result. This also explains why very few people complained about their role being broken after upgrading to Teleport 13.

[marcoandredinis]

I think we need to add specific tests for this

We should also have a docs page or an anchor to a doc that explains the change that users must do

[hugoShaka]

I updated the PR: now, the version cannot be changed without deleting/re-creating the resource. We also have more extensive tests for version updates and missing versions.

@tigrato @marcoandredinis can you take another look?

[tigrato]

We will need to somehow get a workaround for this otherwise for users that want to use Kubernetes resources other than pod, it will involve deleting several roles so the conversion can happen.
For now it will be fine but prepare for some support load since some kubernetes resources are a v7 only feature

[hugoShaka]

We will need to somehow get a workaround for this otherwise for users that want to use Kubernetes resources other than pod, it will involve deleting several roles so the conversion can happen. For now it will be fine but prepare for some support load since some kubernetes resources are a v7 only feature

You're right. I will document how to upgrade a resource (create a new role v7, use it everywhere, remove rolev5). I also need to document best practices to dynamically use the correct role name and have Terraform correctly infer dependencies.