Run the relay on AWS (ECS Fargate)

The Terraform module in deploy/relay/terraform/aws-ecs runs the relay as an ECS Fargate service in your private subnets. On EKS, use the Helm chart instead.

What it creates:

  • An ECS service (and a cluster, unless you pass one) running one Fargate task, with a read-only root filesystem and all Linux capabilities dropped.
  • A security group with no inbound rules and outbound HTTPS (443) to anywhere, plus the target ports you list.
  • A CloudWatch log group, /ecs/guidely-relay.
  • An execution role that can read only the secrets you name. The task itself has no IAM role: the relay calls no AWS API.

Before you start

  • Private subnets with a route to a NAT gateway: the task pulls its image from ghcr.io, reads Secrets Manager, writes CloudWatch Logs and polls Guidely, all over HTTPS. (VPC endpoints for Secrets Manager and CloudWatch Logs work too; Guidely and ghcr.io still need NAT.)
  • A route from those subnets to your Prometheus, Loki, Tempo or Grafana, and inbound rules on their security groups that allow the relay's security group.
  • The relay token in Secrets Manager. Create secrets outside Terraform so their values stay out of its state:
aws secretsmanager create-secret --name guidely-relay/token --secret-string 'gly_rly_...'
aws secretsmanager create-secret --name guidely-relay/grafana-token --secret-string 'glsa_...'

Deploy

data "aws_secretsmanager_secret" "relay_token" { name = "guidely-relay/token" }
data "aws_secretsmanager_secret" "grafana_token" { name = "guidely-relay/grafana-token" }

module "guidely_relay" {
  source = "github.com/GuidelyTech/Guidely//deploy/relay/terraform/aws-ecs"

  vpc_id     = module.vpc.vpc_id
  subnet_ids = module.vpc.private_subnets

  relay_token_secret_arn = data.aws_secretsmanager_secret.relay_token.arn

  targets = [
    { name = "prom", kind = "prometheus", url = "http://prometheus.internal:9090" },
    { name = "logs", kind = "loki", url = "http://loki.internal:3100" },
    { name = "grafana", kind = "grafana", url = "https://grafana.internal" },
  ]
  target_secrets = { TARGET_GRAFANA_BEARER = data.aws_secretsmanager_secret.grafana_token.arn }
  environment    = { TARGET_LOGS_ORG_ID = "tenant-1" }

  target_egress_rules = [
    { from_port = 9090, cidr_blocks = ["10.0.0.0/16"] },
    { from_port = 3100, security_group_ids = [aws_security_group.loki.id] },
  ]
}

# Let the relay in on the targets' side.
resource "aws_vpc_security_group_ingress_rule" "loki_from_relay" {
  security_group_id            = aws_security_group.loki.id
  referenced_security_group_id = module.guidely_relay.security_group_id
  ip_protocol                  = "tcp"
  from_port                    = 3100
  to_port                      = 3100
}

target_secrets maps a TARGET_<NAME>_… variable to a Secrets Manager secret (or SSM parameter) ARN; append :KEY:: to the ARN to read one key of a JSON secret. Plain settings such as TARGET_<NAME>_ORG_ID go in environment. The module's README lists every input.

Check it

The module's check_command output runs guidely-relay check once as a one-off task in the same subnets, with the same secrets. Its table appears in the log group:

$(terraform output -raw check_command)
aws logs tail /ecs/guidely-relay --since 5m

Then look in Integrations → Grafana, Prometheus, Tempo, Loki: the relay shows as connected, with its targets.

Notes

  • Amazon Managed Service for Prometheus needs SigV4-signed requests, which the relay doesn't sign. Query it through Amazon Managed Grafana (a grafana target with a service account token), or put a SigV4 proxy such as aws-sigv4-proxy next to the relay and point the target at the proxy.
  • Graviton: set cpu_architecture = "ARM64"; the image is built for both.
  • Size: the default 0.25 vCPU and 512 MB is plenty for a few hundred queries a minute.
  • Logs can be searched with CloudWatch Logs Insights: fields @timestamp, msg, target, path, status, durationMs | filter msg = "job done".