Skip to content

.header.md

Latest commit

 

History

History
179 lines (132 loc) · 5.74 KB

.header.md

File metadata and controls

179 lines (132 loc) · 5.74 KB

This module provides a basic Fleet deployment on AWS with Terraform. It is the root module for the repo and creates the VPC, database, cache, ECS cluster, ALB, and Fleet service stack. If you want to bring part of that infrastructure yourself, use one of the nested submodules instead.

To quickly list available released module tags:

git tag | grep '^tf'

Module layout:

  • Root module
  • byo-vpc
  • byo-vpc/byo-db
  • byo-vpc/byo-db/byo-ecs

KMS Coverage

This root module now exposes optional customer-managed KMS key (CMK) support for every KMS-capable surface that this stack manages directly or passes through to child modules.

At the root module level this includes:

  • VPC flow log CloudWatch log groups
  • Aurora storage encryption
  • Aurora database password secret in Secrets Manager
  • Aurora observability encryption for Performance Insights / CloudWatch Database Insights
  • Aurora exported CloudWatch log groups
  • ElastiCache at-rest encryption
  • ElastiCache CloudWatch log groups for cloudwatch-logs delivery targets
  • ECS cluster exec log groups, Fleet app log groups, Fleet private-key secret, and other nested Fleet/ECS KMS features through child-module passthroughs

Behavior rules are consistent across features:

  • cmk_enabled = true means "use a customer-managed KMS key here."
  • Set cmk_enabled = false or omit it to keep using the service-managed key.
  • For KMS options that existed in published releases before this change, legacy enabled is deprecated but still accepted. Terraform plan/apply warns when it is used, and cmk_enabled takes precedence if both are set.
  • If CMK use is enabled and no key ARN is provided, the module creates a CMK and alias.
  • If a key ARN is provided, the module uses that key and does not create one.
  • For provided keys, required IAM is managed where this repo owns an IAM principal, but external key policies must already allow the relevant AWS service to use the key.

Aurora Database Insights

AWS has announced that the Performance Insights console reaches end of life on June 30, 2026. Aurora observability is moving toward CloudWatch Database Insights.

This module exposes Aurora observability through rds_config.observability:

  • database_insights_mode = null means Terraform does not force Standard vs Advanced mode.
  • database_insights_mode = "standard" explicitly keeps the cluster in Standard Database Insights mode.
  • database_insights_mode = "advanced" enables Advanced Database Insights and therefore requires:
    • performance_insights_enabled = true
    • monitoring_interval > 0
    • retention_period >= 465

The observability CMK applies through Aurora's underlying Performance Insights encryption plane, which Database Insights builds on.

Aurora Backtrack

This module also exposes Aurora MySQL backtracking through rds_config.backtrack_window.

  • Set it to a value between 0 and 259200 seconds.
  • Set 0 to disable backtracking explicitly.
  • Leave it null to keep the default upstream behavior.

Migration Notes

  • Existing environments remain unchanged unless you opt into new KMS or Database Insights settings.
  • For provided CMKs, ensure the key policy already allows the relevant AWS service.
  • Enabling KMS on existing CloudWatch log groups may require old log streams to be purged so all retained data is under the new key.

Use the repository-root helper script for CloudWatch Logs KMS cleanup:

# Dry run
DELETE_OLD_STREAMS=false ./scripts/cloudwatch_logs_kms_migration.sh <log-group-name> <region>

# Delete old streams
./scripts/cloudwatch_logs_kms_migration.sh <log-group-name> <region>

Example

module "fleet" {
  source = "github.com/fleetdm/fleet-terraform?depth=1&ref=tf-mod-root-v1.26.0"

  certificate_arn = module.acm.acm_certificate_arn

  vpc = {
    enable_flow_log                      = true
    create_flow_log_cloudwatch_log_group = true
    flow_log_cloudwatch_log_group_kms = {
      cmk_enabled = true
    }
  }

  rds_config = {
    storage_kms = {
      cmk_enabled = true
    }
    password_secret_kms = {
      cmk_enabled = true
    }
    observability = {
      database_insights_mode = "standard"
      kms = {
        cmk_enabled = true
      }
    }
  }

  redis_config = {
    at_rest_kms = {
      cmk_enabled = true
    }
  }
}

Migrating from existing Dogfood code

The below code describes how to migrate from existing Dogfood code.

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 focuses on the resources that are "heavy" or store data. The ALB cannot be moved the same way because Dogfood uses aws_alb while the module uses aws_lb.

Cache Engine: Redis vs Valkey

This module supports both Redis and Valkey as the ElastiCache engine.

Provider Requirements

When using this module, ensure your AWS provider version is >= 5.73.0.

Using Valkey

redis_config = {
  engine         = "valkey"
  engine_version = "7.2"
  family         = "valkey7"
  instance_type  = "cache.m5.large"
  cluster_size   = 3
}

Using Redis

redis_config = {
  engine         = "redis"
  engine_version = "7.1"
  family         = "redis7"
  instance_type  = "cache.m5.large"
  cluster_size   = 3
}

How to improve this module

If this module does not fit your needs, open a ticket or contact Fleet. Variable changes should stay nullable when no sensible default exists and should be reflected all the way up the stack.

How to update this readme

Edit .header.md, run terraform init, then run terraform-docs markdown . > README.md.