Write a deployment guide (how to move from tradition to modular TF)

[zayhanlon]

Pass technical draft to Jarod and JD Strong for final review and publishing

[zwinnerman-fleetdm]

Migrating from Dogfood Terraform to Module Terraform

Zachary Winnerman

We are happy to have received all the feedback we got from the new Terraform module for Fleet! Its been really great! One thing we consistently got though was confusion on how to migrate from current Dogfood code to the Terraform module. Due to the large variety of situations, there's still not a hard and fast "this is how to do it" that we can give, but I'll present two methods that should work in most situations.

Snapshot method (easiest, with downtime)

By far the easiest method is to just take a snapshot of the existing databse, and then pass that into the module when you apply. This will cause downtime since it will recreate all resources, but based on feedback from customers this is acceptable in most situations. Here is a step by step guide on how to migrate using this method:

1. Comb through the Terraform code, removing all code that came from Dogfood and keeping code that your team added. Do not apply until step 6
2. Add in the module code from the example here: https://github.com/fleetdm/fleet/tree/main/terraform/example
3. Rewrite the changes your team made so that its compatible with the module (hint: you can use terraform validate to ensure it will work)
4. Take a database snapshot: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_CreateSnapshot.html
5. Make an edit to the module block so that you pass the snapshot arn into the module. It should be the snapshot_identifier field of the rds_config variable.
6. Now run terraform apply -target module.main.module.vpc. Change the target to match what you named the module if you changed the name.
7. Now run terraform apply to apply the rest of the changes
8. Check out our library of addons to Fleet here: https://github.com/fleetdm/fleet/tree/main/terraform/addons
9. Add any addons that you want
10. Terraform apply after adding the addons. You might need to target the addon with something like terraform apply -target module.<addon> first so that IAM policies are created. Terraform can get confused if the policies are not available at plan time.

Resource based migration method (hardest, minimal to no downtime)

This is a harder method, but can result in less or even no downtime. In short, terraform added a new feature that lets users rename resources: https://developer.hashicorp.com/terraform/language/modules/develop/refactoring We can use this feature to rename most or even all resources, resulting in less downtime. Below is the code we have written to migrate the "heavy" resources to the module:

moved {
  from = module.vpc
  to   = module.main.module.vpc
}

moved {
  from = module.aurora_mysql
  to = module.main.module.byo-vpc.module.rds
}

moved {
  from = aws_elasticache_replication_group.default
  to = module.main.module.byo-vpc.module.redis.aws_elasticache_replication_group.default
}

This doesn't target all resources, and will still result in downtime, but it should be a lot lower. Here is a step by step guide to help you through this method:

1. Follow the snapshot method until step 3.
2. Add in the provided code anywhere in the code base.
3. Run terraform apply -target module.main.module.vpc.
4. Run terraform plan, carefully examining the provided plan. Do not actually run the apply yet.
5. Find and note down any resources being destroyed that you do not want destroyed.
6. Write a block like above that migrates it to the module format. Some resources might be in an addon module. In this case, add the addon into your code and go to step 4 again.
7. Go back to step 4, repeat until everything is correct for your needs.
8. Continue the snapshot method starting from step 7

[zwinnerman-fleetdm]

https://docs.google.com/document/d/1dOJ3bcIu-NQ1lpwSRdOKXdHGfPCX3dQ9NUE8MZbI7Yk/edit#heading=h.wm9rd41m69v

[zayhanlon]

Requested an update from JD and Nate Holliday on this doc

[zwinnerman-fleetdm]

its out of my hands, closing

[fleet-release]

Cloud city's haze glows,
Secured fleets, modular now.
Ease of deployment flows.