fleet/articles/fleet-terraform-byo-vpc-module.md

# Using the Fleet Terraform module with an existing VPC

The Fleet Terraform module is the recommended way to quickly get Fleet up and running in AWS. However, some organizations may already have an existing VPC that they would like leverage to deploy Fleet. This article shows what that would look like, leveraging the module at the bring-your-own VPC (BYO-VPC) level.

## Required resources

Starting at the BYO-VPC level has all of the same initial [requirements](https://fleetdm.com/docs/deploy/deploy-on-aws-with-terraform#bring-your-own-nothing) as the root (BYO-Nothing) Terraform module. We will need to include these in our example here as well for visibility:

```hcl

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

locals {
  fleet_domain_name = "fleet.<your_domain>.com"
}

module "acm" {
  source  = "terraform-aws-modules/acm/aws"
  version = "4.3.1"

  domain_name = local.fleet_domain_name
  zone_id     = aws_route53_zone.main.id

  wait_for_validation = true
}

resource "aws_route53_zone" "main" {
  name = local.fleet_domain_name
}

resource "aws_route53_record" "main" {
  zone_id = aws_route53_zone.main.id
  name    = local.fleet_domain_name
  type    = "A"

  alias {
    name                   = module.byo-vpc.byo-db.alb.lb_dns_name
    zone_id                = module.byo-vpc.byo-db.alb.lb_zone_id
    evaluate_target_health = true
  }
}
```

Additionally, we will have to have a VPC created. The [Terraform AWS VPC module](https://registry.terraform.io/modules/terraform-aws-modules/vpc/aws/3.18.1) is one of the easiest ways to get all the necessary pieces quickly, so we'll use this in the example.

```hcl

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "3.18.1"

  name = "fleet-vpc"
  cidr = "10.10.0.0/16"

  azs                                       = ["us-east-2a", "us-east-2b", "us-east-2c"]
  private_subnets                           = ["10.10.1.0/24", "10.10.2.0/24", "10.10.3.0/24"]
  public_subnets                            = ["10.10.11.0/24", "10.10.12.0/24", "10.10.13.0/24"]
  database_subnets                          = ["10.10.21.0/24", "10.10.22.0/24", "10.10.23.0/24"]
  elasticache_subnets                       = ["10.10.31.0/24", "10.10.32.0/24", "10.10.33.0/24"]
  create_database_subnet_group              = false
  create_database_subnet_route_table        = true
  create_elasticache_subnet_group           = true
  create_elasticache_subnet_route_table     = true
  enable_vpn_gateway                        = false
  one_nat_gateway_per_az                    = false
  single_nat_gateway                        = true
  enable_nat_gateway                        = true
  enable_flow_log                           = false
  create_flow_log_cloudwatch_log_group      = false
  create_flow_log_cloudwatch_iam_role       = false
  flow_log_max_aggregation_interval         = null
  flow_log_cloudwatch_log_group_name_prefix = null
  flow_log_cloudwatch_log_group_name_suffix = null
  vpc_flow_log_tags                         = {}
  enable_dns_hostnames                      = false
  enable_dns_support                        = true
}

```

Since it is likely that an organization wanting to leverage BYO-VPC did not use the above module, below is the resource info required from the existing VPC and the corresponding resource name from the module used below:

- The VPC ID: `module.vpc.vpc_id` 
- A private subnet for Fleet ECS containers: `module.vpc.private_subnets`
- A private subnet for RDS: `module.vpc.database_subnets`
- A private subnet for Redis: `module.vpc.elasticache_subnets`
- An elasticache subnet group for Redis (optional): `module.vpc.elasticache_subnet_group_name`
- A public subnet for the load balancer: `module.vpc.public_subnets`

While Fleet recommends that each private subnet be unique as a best practice, it is technically possible to place Fleet/ECS, RDS, and Redis all in the same private subnet. Just provide the same subnet ID in each of the respective locations below. If an elasticache subnet group is not already created for your VPC, it can be omitted and will be automatically generated by the downstream module.

## The BYO-VPC Module

Next, we'll want to configure the BYO-VPC module with at least a minimal configuration. While it is not necessary to specify a Fleet image version, it is strongly recommended. This way an organization is fully in control of the version of Fleet deployed regardless of updates to the Terraform module or Fleet releases. Below shows a minimal configuration that includes the Fleet image:

```hcl

locals {
  fleet_image = "fleetdm/fleet:v4.36.0"
}

module "byo-vpc" {
  source = "github.com/fleetdm/fleet//terraform/byo-vpc?ref=tf-mod-byo-vpc-v1.4.0"
  vpc_config = {
    vpc_id = module.vpc.vpc_id
    networking = {
      subnets = module.vpc.private_subnets
    }
  }
  rds_config = {
    subnets        = module.vpc.database_subnets
  }
  redis_config = {
    subnets                       = module.vpc.elasticache_subnets
    elasticache_subnet_group_name = module.vpc.elasticache_subnet_group_name
    availability_zones            = module.vpc.azs
  }
  alb_config = {
    subnets         = module.vpc.public_subnets
    certificate_arn = module.acm.acm_certificate_arn
  }
  fleet_config = {
    image = local.fleet_image
    extra_secrets = {
      // FLEET_LICENSE_KEY: "secret_manager_license_key_arn" 
    }
  }
}

``` 

Defining the `fleet_image` as a local allows it to be reused by other add-on modules that will require the running fleet version to be specified such as the external vulnerability processing add-on. For Fleet Premium users, the license can be included in an AWS Secretsmanager Secret and added in as the commented-out example above shows.


## Add-ons

Similar to using the root module, it is recommended to at least include the migration add-on module to make it easier to upgrade Fleet in the future and to get the initial migrations in place. This adds the following:


```hcl

module "migrations" {
  source                   = "github.com/fleetdm/fleet//terraform/addons/migrations?ref=tf-mod-addon-migrations-v1.0.0"
  ecs_cluster              = module.byo-vpc.byo-db.byo-ecs.service.cluster
  task_definition          = module.byo-vpc.byo-db.byo-ecs.task_definition.family
  task_definition_revision = module.byo-vpc.byo-db.byo-ecs.task_definition.revision
  subnets                  = module.byo-vpc.byo-db.byo-ecs.service.network_configuration[0].subnets
  security_groups          = module.byo-vpc.byo-db.byo-ecs.service.network_configuration[0].security_groups
}

```

All add-ons at the time of this writing are compatible with the BYO-VPC module. If examples reference resources, the BYO-Nothing/root module in the format of `module.main.byo-vpc...` simply omit `.main` from them so they look like the references above in the migrations example.

## Bringing It All Together

This is what a complete configuration would look like:

```hcl

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

locals {
  fleet_domain_name = "fleet.<your_domain>.com"
  fleet_image       = "fleetdm/fleet:v4.36.0"
}

module "acm" {
  source  = "terraform-aws-modules/acm/aws"
  version = "4.3.1"

  domain_name = local.fleet_domain_name
  zone_id     = aws_route53_zone.main.id

  wait_for_validation = true
}

resource "aws_route53_zone" "main" {
  name = local.fleet_domain_name
}

resource "aws_route53_record" "main" {
  zone_id = aws_route53_zone.main.id
  name    = local.fleet_domain_name
  type    = "A"

  alias {
    name                   = module.byo-vpc.byo-db.alb.lb_dns_name
    zone_id                = module.byo-vpc.byo-db.alb.lb_zone_id
    evaluate_target_health = true
  }
}

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "3.18.1"

  name = "fleet-vpc"
  cidr = "10.10.0.0/16"

  azs                                       = ["us-east-2a", "us-east-2b", "us-east-2c"]
  private_subnets                           = ["10.10.1.0/24", "10.10.2.0/24", "10.10.3.0/24"]
  public_subnets                            = ["10.10.11.0/24", "10.10.12.0/24", "10.10.13.0/24"]
  database_subnets                          = ["10.10.21.0/24", "10.10.22.0/24", "10.10.23.0/24"]
  elasticache_subnets                       = ["10.10.31.0/24", "10.10.32.0/24", "10.10.33.0/24"]
  create_database_subnet_group              = false
  create_database_subnet_route_table        = true
  create_elasticache_subnet_group           = true
  create_elasticache_subnet_route_table     = true
  enable_vpn_gateway                        = false
  one_nat_gateway_per_az                    = false
  single_nat_gateway                        = true
  enable_nat_gateway                        = true
  enable_flow_log                           = false
  create_flow_log_cloudwatch_log_group      = false
  create_flow_log_cloudwatch_iam_role       = false
  flow_log_max_aggregation_interval         = null
  flow_log_cloudwatch_log_group_name_prefix = null
  flow_log_cloudwatch_log_group_name_suffix = null
  vpc_flow_log_tags                         = {}
  enable_dns_hostnames                      = false
  enable_dns_support                        = true
}

module "byo-vpc" {
  source = "github.com/fleetdm/fleet//terraform/byo-vpc?ref=tf-mod-byo-vpc-v1.4.0"
  vpc_config = {
    vpc_id = module.vpc.vpc_id
    networking = {
      subnets = module.vpc.private_subnets
    }
  }
  rds_config = {
    subnets        = module.vpc.database_subnets
  }
  redis_config = {
    subnets                       = module.vpc.elasticache_subnets
    elasticache_subnet_group_name = module.vpc.elasticache_subnet_group_name
    availability_zones            = module.vpc.azs
  }
  alb_config = {
    subnets         = module.vpc.public_subnets
    certificate_arn = module.acm.acm_certificate_arn
  }
  fleet_config = {
    image = local.fleet_image
    extra_secrets = {
      // FLEET_LICENSE_KEY: "secret_manager_license_key_arn"
    }
  }
}

module "migrations" {
  source                   = "github.com/fleetdm/fleet//terraform/addons/migrations?ref=tf-mod-addon-migrations-v1.0.0"
  ecs_cluster              = module.byo-vpc.byo-db.byo-ecs.service.cluster
  task_definition          = module.byo-vpc.byo-db.byo-ecs.task_definition.family
  task_definition_revision = module.byo-vpc.byo-db.byo-ecs.task_definition.revision
  subnets                  = module.byo-vpc.byo-db.byo-ecs.service.network_configuration[0].subnets
  security_groups          = module.byo-vpc.byo-db.byo-ecs.service.network_configuration[0].security_groups
}

```


Since the VPC must exist before the BYO-VPC module can be applied and our BYO-VPC module has to create the the other resources before the migrations can be run, we will need to use targeted applies as below:

```bash
terraform init
terraform apply -target=module.vpc
terraform apply -target=module.byo-vpc
terraform apply

```

The BYO-VPC configuration can be fully customized similar to the [Terraform root module](https://github.com/fleetdm/fleet/tree/main/terraform).  See the [BYO-VPC reference](https://github.com/fleetdm/fleet/tree/main/terraform/byo-vpc) for a full list of variables.

<meta name="category" value="guides">
<meta name="authorFullName" value="Robert Fairburn">
<meta name="authorGitHubUsername" value="rfairburn">
<meta name="publishedOn" value="2023-09-01">
<meta name="articleTitle" value="Using the Fleet Terraform module with an existing VPC">