DNS setup for custom domain names should not require extra code added

[askaribragimov]

Is your request related to a new offering from AWS?

No

Is your request related to a problem? Please describe.

While trying to be an out-of-the-box solution, this module leaves out configuring end-to-end certificates and DNS records for the API gateway.

Also, Hosted Zone ID data is a bit confusing and not explained well in the documentation.

Describe the solution you'd like.

After creating an API gateway with "custom DNS names on", e.g., when the module has parameters like

  # Custom domain
  create_api_domain_name      = true
  domain_name                 = local.apigw_full_dns_name
  domain_name_certificate_arn = module.acm.acm_certificate_arn

the setup is done in API Gateway but it is neither implemented nor explained how to make that DNS name actually work if you have the Route53 Hosted Zone that handles the desired subdomain.

In order for this part to work, I had to code explicitly the following addition following explanations from https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/apigatewayv2_domain_name and https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-regional-api-custom-domain-create.html. Parameters are dns_zone_name - my subdomain handled by Route 53 Hosted Zone, dns_zone_id - its ID , environment_name - just some ID, like "dev",

locals {
  apigw_full_dns_name = "${var.environment_name}.${var.dns_zone_name}"
}

# Creates certificate and validates it.
module "acm" {
  source  = "terraform-aws-modules/acm/aws"
  version = "~> 3.2.0"
  domain_name = local.apigw_full_dns_name
  zone_id     = var.dns_zone_id
  subject_alternative_names = [
    "*.${local.apigw_full_dns_name}",
  ]
  wait_for_validation = true
  tags = var.tags
}

# This creates a link between Route 53 and API Gateway "custom name"
# See https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-regional-api-custom-domain-create.html
# See https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/apigatewayv2_domain_name
resource "aws_route53_record" "apigw_route53_record" {
  name    = local.apigw_full_dns_name
  type    = "A"
  zone_id = var.dns_zone_id
  alias {
    name                   = module.api_gateway.apigatewayv2_domain_name_target_domain_name
    zone_id                = module.api_gateway.apigatewayv2_domain_name_hosted_zone_id
    evaluate_target_health = false
  }
}

The tricky part is that you have to use two Hosted Zones: one from the subdomain and one "magic" that is returned by the API GW module. I call it magic because while it is a valid Hosted Zone it does not appear in Route53.

The idea is to make the module complete by including aws_route53_record part already in the module. It just requires hosted zone params to be passed.

The certificate creation can be also explained in README at least because it is very handy to create the cert using some kind of automatic means to validate it, just like https://registry.terraform.io/modules/terraform-aws-modules/acm/aws/latest does. It appears the same team worked on that module so should be OK to integrate these.

[antonbabenko]

Hi!

The way we are constructing Terraform AWS modules means that they are 100% flexible and users should understand the AWS to get the job done. The modules do not hide internals of AWS API so much.

In all of the modules, we provide examples to show how modules can be used and integrated with other services such as in your case - API Gateway and Route53.

Here is the example - https://github.com/terraform-aws-modules/terraform-aws-apigateway-v2/blob/master/examples/complete-http/main.tf#L121-L131

We won't add extra resources which do not natively belong to an API Gateway service.

[github-actions[bot]]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues. If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.