You must use a Terraform-compatible Quilt CloudFormation template
(local.build_file_path). Ask your account manger for details.
You project structure should look something like the following:
quilt_stack
├── main.tf
└── my-company.yml
Use examples/main.tf as a starting point for your main.tf.
It is neither necessary nor recommended to modify any module in this repository. All supported customization is possible with arguments to
module.quilt.
You will run the various terraform commands from within this directory.
See quilt/variables.tf for detailed documentation on each argument. See network documentation for further details on subnet configuration.
| Argument | internal = true (private ALB for VPN) |
internal = false (internet-facing ALB) |
|---|---|---|
| intra_subnets | Isolated subnets (no NAT) for db & search |
" |
| private_subnets | For Quilt services | " |
| public_subnets | n/a | For IGW, ALB |
| user_subnets | For ALB (when create_new_vpc = false) |
n/a |
| user_security_group | For ALB access | n/a |
| api_endpoint | For API Gateway when create_new_vpc = false |
n/a |
This endpoint must be reachable by your VPN clients.
resource "aws_vpc_endpoint" "api_gateway_endpoint" {
vpc_id = ""
service_name = "com.amazonaws.${var.region}.execute-api"
vpc_endpoint_type = "Interface"
subnet_ids = module.vpc.private_subnet_ids
security_group_ids = ""
private_dns_enabled = true
}You may wish to set a specific AWS profile before executing terraform
commands.
export AWS_PROFILE=your-aws-profileWe discourage the use of
provider.profilein team environments where profile names may differ across users and machines.
Your primary consideration is the total data node disk size. If you multiply your average document size (likely a function of the number of deep-indexed documents and your depth limit) by the total number of documents that will give you "Source data" below.
Each shallow-indexed document requires a constant number of bytes on the order of 1kB.
Follow AWS's documentation on Sizing Search Domains and note the following simplified formula:
Source data * (1 + number of replicas) * 1.45= minimum storage requirement
For a production Quilt deployment the number of replicas will be 1, so multiplying "Source data" by 3 (2.9 rounded up) is a fair starting point. Be sure to account for growth in your Quilt buckets. "Live" resizing of existing domains is supported but requires time and may reduce quality of service during the blue/green update.
Below are known-good search sizes that you can set on the quilt module.
search_dedicated_master_enabled = false
search_zone_awareness_enabled = false
search_instance_count = 1
search_instance_type = "m5.large.elasticsearch"
search_volume_size = 512search_dedicated_master_enabled = true
search_zone_awareness_enabled = true
search_instance_count = 2
search_instance_type = "m5.xlarge.elasticsearch"
search_volume_size = 1024search_dedicated_master_enabled = true
search_zone_awareness_enabled = true
search_instance_count = 2
search_instance_type = "m5.xlarge.elasticsearch"
search_volume_size = 2*1024
search_volume_type = "gp3"search_dedicated_master_enabled = true
search_zone_awareness_enabled = true
search_instance_count = 2
search_instance_type = "m5.2xlarge.elasticsearch"
search_volume_size = 3*1024
search_volume_type = "gp3"
search_volume_iops = 16000search_dedicated_master_enabled = true
search_zone_awareness_enabled = true
search_instance_count = 2
search_instance_type = "m5.4xlarge.elasticsearch"
search_volume_size = 6*1024
search_volume_type = "gp3"
search_volume_iops = 18750search_dedicated_master_enabled = true
search_zone_awareness_enabled = true
search_instance_count = 2
search_instance_type = "m5.12xlarge.elasticsearch"
search_volume_size = 18*1024
search_volume_type = "gp3"
search_volume_iops = 40000
search_volume_throughput = 1187search_dedicated_master_enabled = true
search_zone_awareness_enabled = true
search_instance_count = 4
search_instance_type = "m5.12xlarge.elasticsearch"
search_volume_size = 18*1024
search_volume_type = "gp3"
search_volume_iops = 40000
search_volume_throughput = 1187As a rule, terraform apply is sufficient to both deploy and update Quilt.
Before calling apply read terraform plan carefully to ensure that it does
not inadvertently destroy and recreate the stack. The following modifications
are known to cause issues (see examples/main.tf for context).
- Modifying
local.name. - Modifying
local.build_file_path. - Modifying
quilt.template_file.
And for older versions of Terraform and customers whose usage predates the present module:
- Modifying
template_url=(in older versions of Terraform).
terraform initIf for instance you change the provider pinning you may need to -upgrade:
terraform init -upgradeterraform fmt
terraform validate
terraform plan -out tfplan
If the plan is what you want:
terraform apply tfplan
Sensitive values must be named in order to display on the command line:
terraform output admin_password
terraform state list
Or, to show a specific entity:
terraform state show 'thing.from.list'
terraform refresh
terraform destroy
- Start with a clean commit of the previous apply in your Quilt Terraform folder (nothing uncommitted).
- In your
main.tffile, do the following: - Initialize.
- Plan.
- Verify the plan.
- Apply.
- Commit the appropriate files.
*.tfterraform.lock.hcl- Your Quilt
build_file
You may wish to create a .gitignore file similar to the following:
.terraform
tfplan
We recommend that you use remote state so that no passwords are checked into version control.
Due to how Terraform evaluates (or fails to evaluate) arguments in a precondition
(e.g. user_security_group = aws_security_group.lb_security_group.id) you may
see the following error message. Provide a static string instead of a dynamic value.
│ 27: condition = !local.configuration_error
│ ├────────────────
│ │ local.configuration_error is true
│
│ This check failed, but has an invalid error message as described in the other accompanying messages.
Provide a static string instead (e.g. user_security_group = "123") and you should
receive a more informative message similar to the following:
│ In order to use an existing VPC (create_new_vpc == false) correct the following attributes:
│ ❌ api_endpoint (required if var.internal == true, else must be null)
│ ✅ create_new_vpc == false
│ ✅ intra_subnets (required)
│ ✅ private_subnets (required)
│ ❌ public_subnets (required if var.internal == false, else must be null)
│ ✅ user_security_group (required)
│ ❌ user_subnets (required if var.internal == true and var.create_new_vpc == false, else must be null)
│ ✅ vpc_id (required)
InvalidParameterCombination: Cannot upgrade postgres from 11.X to 15.Y
Later versions of the current module set database auto_minor_version_upgrade = false.
As a result some users may find their Quilt RDS instance on Postgres 11.19.
These users should first upgrade to 11.22 using the AWS Console and then apply
a recent version of the present module, which will upgrade Postgres to 15.5.
Users who have auto-minor-version-upgraded to 11.22 can apply the present module to automatically upgrade to 15.5 (without any manual steps).
Engine version changes are applied during the next maintenance window, therefore you may not see them immediately in AWS Console.
Error: updating Elasticsearch Domain (arn:aws:es:foo:bar/baz) config: ValidationException: A change/update is in progress. Please wait for it to complete before requesting another change.
If you encounter the above error we suggest that you use the latest version of the
current repo which no longer uses an auto_tune_options configuration block in
the search module. We further recommend that you only use
search instances that support Auto-Tune
as the AWS service may automatically enable Auto-Tune without cause and without warning,
leading to search domains that are difficult to upgrade.
Some users have overcome the above error by pinning the provider to 5.20.0 as shown below but this is not recommended given that 5.20.0 is an older version.
provider "aws" {
version = "= 5.20.0"
}