Module upgrade docs from 3.x to 4.x

[nitrocode]

Is your request related to a new offering from AWS?

No

Is your request related to a problem? Please describe.

I'm finding it overwhelming to upgrade from 3.x to 4.x

Describe the solution you'd like.

• Upgrade or migration docs
• A migration.hcl using moved and other terraform blocks to ease the transition

Describe alternatives you've considered.

Attempting this myself but it's quite complicated and I don't want to risk breaking something

Additional context

[bryantbiggs]

Atlantis deployment created by this module doesn't hold state (is not "stateful"). The recommendation is to remove/destroy 3.x version and redeploy with 4.x version. This is what folks suggested and are doing

[nitrocode]

Even if it's not stateful, you'd still need to map the deprecated inputs to new inputs.

Here is what I've come up with so far.

diff between 3.x and 4.x

data "aws_route53_zone" "default" {
  name = "jiobit.com"
}

module "atlantis" {
  source  = "terraform-aws-modules/atlantis/aws"
- version = "~> 3"
+ version = "~> 4"

- cidr = "10.20.0.0/16"

- alb_ingress_cidr_blocks = ["0.0.0.0/32"]

- azs = ["us-west-2b", "us-west-2c"]

- private_subnet_ids = ["subnet-snip-private"]
+ service_subnets = ["subnet-snip-private"]

- public_subnet_ids = ["subnet-snip-public-1", "subnet-snip-public-2"]
+ alb_subnets = ["subnet-snip-public-1", "subnet-snip-public-2"]

- route53_zone_name = "snip.com"
+ route53_zone_id = data.aws_route53_zone.default.id

- atlantis_github_user       = "snip_org"
- atlantis_github_user_token = jsondecode(data.aws_secretsmanager_secret_version.github.secret_string)["GITHUB_USER_TOKEN"]
- atlantis_repo_allowlist    = ["github.com/snip/infrastructure"]

- atlantis_github_webhook_secret = jsondecode(data.aws_secretsmanager_secret_version.github.secret_string)["GITHUB_WEBHOOK_SECRET"]

- ecs_task_memory = "2048"

+ atlantis = {
+   environment = [
+     {
+       name  = "ATLANTIS_GH_USER"
+       value = "snip_org"
+     },
+     {
+       name  = "ATLANTIS_REPO_ALLOWLIST"
+       value = "github.com/snip/infrastructure"
+     },
+     {
+       name  = "ATLANTIS_REPO_CONFIG_JSON"
+       value = jsonencode(yamldecode(file("${path.module}/server-atlantis.yaml")))
+     },
+   ]
+   secrets = [
+     {
+       name      = "ATLANTIS_GH_TOKEN"
+       valueFrom = format("%s:GITHUB_USER_TOKEN::", data.aws_secretsmanager_secret.github.id)
+     },
+     {
+       name      = "ATLANTIS_GH_WEBHOOK_SECRET"
+       valueFrom = format("%s:GITHUB_WEBHOOK_SECRET::", data.aws_secretsmanager_secret.github.id)
+     },
+     {
+       name      = "TF_VAR_datadog_api_key"
+       valueFrom = data.aws_secretsmanager_secret.datadog_api_key.id
+     },
+     {
+       name      = "TF_VAR_datadog_app_key"
+       valueFrom = data.aws_secretsmanager_secret.datadog_app_key.id
+     },
+   ]
+
+   task_exec_iam_role_policies = {
+     custom                         = aws_iam_policy.access.arn
+     SecretsManagerReadWrite        = "arn:aws:iam::aws:policy/SecretsManagerReadWrite"
+   }
+
+   memory = "2048"
+
+   cpu = "256"
+ }

- custom_environment_variables = [
-   {
-     name : "ATLANTIS_REPO_CONFIG_JSON",
-     value : jsonencode(yamldecode(file("${path.module}/server-atlantis.yaml"))),
-   }
- ]

- custom_environment_secrets = [
-   {
-     name : "TF_VAR_datadog_api_key",
-     valueFrom : data.aws_secretsmanager_secret.datadog_api_key.id
-   },
-   {
-     name : "TF_VAR_datadog_app_key",
-     valueFrom : data.aws_secretsmanager_secret.datadog_app_key.id
-   },
- ]

- policies_arn = [
-   aws_iam_policy.access.arn,
-   "arn:aws:iam::aws:policy/SecretsManagerReadWrite",
- ]
}

Now I see the following

Plan: 32 to add, 2 to change, 32 to destroy.

If I use a migrations.tf with moved blocks, I see

migrations.tf

moved {
  from = module.atlantis.aws_cloudwatch_log_group.atlantis
  to   = module.atlantis.module.ecs_cluster.aws_cloudwatch_log_group.this[0]
  # to = module.atlantis.module.ecs_service.module.container_definition["atlantis"].aws_cloudwatch_log_group.this[0]
}

moved {
  from = module.atlantis.aws_ecs_service.atlantis
  to   = module.atlantis.module.ecs_service.aws_ecs_service.this[0]
}

moved {
  from = module.atlantis.aws_ecs_task_definition.atlantis
  to   = module.atlantis.module.ecs_service.aws_ecs_task_definition.this[0]
}

moved {
  from = module.atlantis.aws_iam_role.ecs_task_execution
  to   = module.atlantis.module.ecs_service.aws_iam_role.task_exec[0]
}

moved {
  from = module.atlantis.aws_iam_role_policy_attachment.ecs_task_execution["arn:aws:iam::aws:policy/SecretsManagerReadWrite"]
  to   = module.atlantis.module.ecs_service.aws_iam_role_policy_attachment.task_exec_additional["SecretsManagerReadWrite"]
}

moved {
  from = module.atlantis.aws_route53_record.atlantis[0]
  to   = module.atlantis.module.alb.aws_route53_record.this["A"]
}

moved {
  from = module.atlantis.module.alb.aws_lb_listener.frontend_https[0]
  to   = module.atlantis.module.alb.aws_lb_listener.this["https"]
}

moved {
  from = module.atlantis.module.alb.aws_lb_listener.frontend_http_tcp[0]
  to   = module.atlantis.module.alb.aws_lb_listener.this["http-https-redirect"]
}

moved {
  from = module.atlantis.module.alb.aws_lb_target_group.main[0]
  to   = module.atlantis.module.alb.aws_lb_target_group.this["atlantis"]
}

moved {
  from = module.atlantis.module.ecs.aws_ecs_cluster.this[0]
  to   = module.atlantis.module.ecs_cluster.aws_ecs_cluster.this[0]
}

Plan: 23 to add, 7 to change, 26 to destroy.

The goal is to upgrade to 4.x and no-op most resources to minimize breaking the pipeline. I'd like to also avoid recreating resources like cloudwatch log groups.

It would be nice in future major versions to have something like this for a more seamless upgrade. The migrations can also be codified in the module itself.