terraform-aws-fullstory-cloud-relay

This module creates a relay that allows you to route all captured Fullstory traffic from your users’ browser directly through your own domain. More information on the philosophy and script configuration can be found in this KB article.

Requirements

Name	Version
terraform	>= 1.0
aws	>= 4.59.0

Inputs

Name	Description	Type	Default	Required
acm_certificate_arn	(optional) The ARN of the ACM certificate to be used for the relay. If omitted, a value for route53_zone_name must be provided. Defaults to null.	string	null	no
cloudfront_origin_request_policy_name	(optional) A name to uniquely identify the cloudfront origin request policy for the relay. This is required to deploy multiple relay modules to the same AWS account, as such policies must be uniquely named. Example: fullstory-relay-origin-request-policy-production.	string	"fullstory-relay-origin-request-policy"	no
relay_fqdn	The fully qualified domain name for the relay. Example: fsrelay.your-company.com.	string	n/a	yes
route53_zone_name	(optional) The Route 53 zone name for placing the DNS CNAME record. If omitted, a value for acm_certificate_arn must be provided. Defaults to null.	string	null	no
target_fqdn	(optional) The fully qualified domain name that the relay targets. Defaults to fullstory.com.	string	"fullstory.com"	no

Outputs

Name	Description
relay_distribution_domain_name	The domain name of the relay CloudFront distribution.

Usage

With Route 53 Record Creation

This module will automatically create the DNS records if a value for route53_zone_name is provided in reference to an existing Route 53 zone within the same AWS account.

module "fullstory_relay" {
  source            = "fullstorydev/fullstory-cloud-relay/aws"
  relay_fqdn        = "fsrelay.your-company.com"
  route53_zone_name = "your-company.com."
}

⚠️ Note: CloudFront Distributions can take 10-15 minutes to become active after creation.

Without Route 53 Record Creation

By default, the module will not create a DNS record in Route 53 or certificate in ACM.

A certificate must be created and validated before the relay can be created. This can be done manually or via Terraform (example below).

resource "aws_acm_certificate" "fullstory_relay" {
  domain_name       = "fsrelay.your-company.com"
  validation_method = "DNS"
}

output "relay_cert_dns_validation" {
  description = "The information required to create a DNS validation record."
  value       = {
    for dvo in aws_acm_certificate.fullstory_relay.domain_validation_options : dvo.domain_name => {
      name   = dvo.resource_record_name
      record = dvo.resource_record_value
      type   = dvo.resource_record_type
    }
  }
}

Once the certificate is created, it must be validated before it can be used. The DNS validation information can be extracted from the Terraform state using the command below.

terraform output relay_cert_dns_validation

Create a DNS validation CNAME record that routes the relay_cert_dns_validation.<relay_fqdn>.name to the relay_cert_dns_validation.<relay_fqdn>.record value. Once the DNS record has been created, the certificate can take up to 15 minutes to become active. The status can be checked using the command below.

aws acm list-certificates --query "CertificateSummaryList[?DomainName=='<relay_fqdn>'].Status" 

Now that the certificate has been created and is active, the ARN can be passed into the module as seen below.

module "fullstory_relay" {
  source              = "fullstorydev/fullstory-cloud-relay/aws"
  relay_fqdn          = "fsrelay.your-company.com"
  acm_certificate_arn = aws_acm_certificate.fullstory_relay.arn
}

output "relay_distribution_domain_name" {
  value = module.fullstory_relay.relay_distribution_domain_name
}

Once the resources have been successfully created, the final step is to create the CNAME of the CloudFront distribution which can be extracted from the Terraform state using the command below.

terraform output relay_distribution_domain_name

Create a CNAME DNS record that routes the relay_fqdn to the relay_distribution_domain_name found in the previous command.

European Realm Target

module "fullstory_relay" {
  source      = "fullstorydev/fullstory-cloud-relay/aws"
  relay_fqdn  = "fsrelay.your-company.com"
  target_fqdn = "eu1.fullstory.com"
}

Validation

Once an instance of the Fullstory Relay has been successfully created, the health endpoint at https://<relay_fqdn>/healthz should return a 200 OK.

Resources

Name	Type
aws_acm_certificate.fullstory_relay	resource
aws_acm_certificate_validation.fullstory_relay	resource
aws_cloudfront_distribution.fullstory_relay	resource
aws_cloudfront_origin_request_policy.fullstory_relay	resource
aws_route53_record.fullstory_relay	resource
aws_route53_record.fullstory_relay_dns_validation	resource
aws_arn.fullstory_relay	data source
aws_cloudfront_cache_policy.caching_disabled	data source
aws_cloudfront_cache_policy.caching_optimized	data source
aws_cloudfront_response_headers_policy.cors	data source
aws_route53_zone.fullstory_relay	data source

Troubleshooting

This module includes a troubleshooting endpoint that can be used to debug any communications issues. The endpoint can be found out https://<relay_fqdn>/echo and returns the headers of the request.

Contributing

See CONTRIBUTING.md for best practices and instructions on setting up your dev environment.