fix: add necessary state move to upgrade doc

[marcusschiesser]

Description

Upgrade doc doesn't work as state of IAM role has been changed

Motivation and Context

This is discussed in https://github.com/terraform-aws-modules/terraform-aws-eks/issues/1744, but the doc doesn't mention this important step.

Breaking Changes

no

How Has This Been Tested?

tested with my local cluster

[bryantbiggs]

the upgrade doc already refers to the long discussion that shares the various steps users have made to upgrade from v17.x to v18.x including sharing the state rm/mv commands https://github.com/terraform-aws-modules/terraform-aws-eks/issues/1744#issuecomment-1027359982

I don't think its worthwhile to add this in directly because we then have to wade into a prescriptive guidance on state rm/mv commands - the best source of guidance will be for users to interpret what the Terraform plan tells them and seek out the docuemntation/links for any guidance on what they are trying to achieve

[marcusschiesser]

@bryantbiggs agree, it already refers to the long discussion. But as far as I understand it the given configuration example:

prefix_separator                   = ""
iam_role_name                      = $CLUSTER_NAME
cluster_security_group_name        = $CLUSTER_NAME
cluster_security_group_description = "EKS cluster security group."

assumes that the module is configured to create the IAM role and in this case moving the state is mandatory.

So this should either be somehow mentioned (my text is just a suggestion) or the configuration example should be left out.

[bryantbiggs]

@marcusschiesser let me dig back into this and see what concrete steps we can provide users for migrating from v17 -> v18

[github-actions[bot]]

This PR has been automatically marked as stale because it has been open 30 days with no activity. Remove stale label or comment or this PR will be closed in 10 days

[stevo-f3]

It would help a lot with migration efforts if there was one more terraform-aws-eks v17 release that'd be compatible with terraform >= 1.1. In terraform 1.1 moved block was supported https://www.terraform.io/language/modules/develop/refactoring#refactoring and that would help codify all the renames instead of expecting that to be done by hand.

Current latest v17 eks module release isn't even compatible with terraform 0.14, getting

Error: Output refers to sensitive values

  on .terraform/modules/foo.eks/outputs.tf line 35:
  35: output "config_map_aws_auth" {

Expressions used in outputs can only refer to sensitive values if the
sensitive attribute is true.

It would greatly help with eks module upgrade from v17 to v18 even if there was terraform-aws-eks v17 release compatible with terraform 0.14 at least, as that would allow for upgrade first to terraform 0.14 and with that eliminate huge noise from all the data reads in the plan coming from a terraform 0.13 bug fixed in 0.14 only https://github.com/hashicorp/terraform/issues/26100#issuecomment-696764651

@bryantbiggs @antonbabenko is there any chance of such updated eks module v17 release happening, compatible with terraform 0.14 if not 1.1?

[bryantbiggs]

@stevo-f3 no, there will be no further updates to v17.x

[stevo-f3]

Sad, will have to fork v17 before being able to upgrade to v18.

[stevo-f3]

@bryantbiggs would you consider, instead of documenting manual process, for v18 instead:

• increasing terraform required version to 1.1 (for moved support), and
• adding moved block for cluster role so that eks module users don't have to manually move the state, i.e. add

moved {
    from = aws_iam_role.cluster[0]
    to   = aws_iam_role.this[0]
}

which was moved/renamed in https://github.com/terraform-aws-modules/terraform-aws-eks/commit/ee9f0c646a45ca9baa6174a036d1e09bcccb87b1 and among others that rename causes aws_eks_cluster resource to be (unnecessarily) recreated. This doesn't affect existing v18 users, while makes v17 to v18 migration easier.

[bryantbiggs]

updating the min version to Terraform 1.1 is a breaking change

what i would recommend is to fork this module, embed any state moves through the moved block (note - will require at least 1.1 of Terraform), and perform your upgrade. After this, you can switch back to this version if you choose.

Changing the source of a module does not affect anything, but it would allow you to embed the state move via the moved block without this project having to take that hit for a major version bump.

We will be releasing v19 this week but that only raises the min required version of Terraform to 1.0 and will not be anywhere near as disruptive as the v17 -> v18 upgrade

[antonbabenko]

This PR is included in version 19.17.0 :tada:

[github-actions[bot]]

I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues. If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.