API Gateway Custom Domain Names

[brettstack]

SAM Input:

MyApiSimpleDomain:
  Type: AWS::Serverless::Api
  Properties:
    ...
    EndpointConfiguration: REGIONAL
    # Simple usecase - specify just the Domain Name and we create the rest using sane defaults.
    # A cert is created as well as a base path mapping from '/' to {MyApi.StageName}
    # The `EndpointConfiguration` of the API is used (or default to EDGE)
    Domain: example.com
    
    # The above expands into:
    # Domain:
    #   DomainName: example.com
    # 
    #   # TODO: Should ConfigureRoute53 be on by default? This is useful if
    #   # Route53 is your domain provider and you don't want to manage the domain
    #   # records through some other means (e.g console/manually; separate stack)
    #   Route53: true
    # 
    #   EndpointConfiguration: REGIONAL # {MyApiSimpleDomain.EndpointConfiguration}
    #   Certificate: !Ref MyApiSimpleDomainCertificate # Automatically created
    #   BasePath: /


MyApiAdvancedDomain:
  Type: AWS::Serverless::Api
  Properties:
    ...
    Domain:
      # Domain accepts either a string (DomainName), an Object, or an Array of Objects
      - DomainName: example.com # Required
      
        # Set this to false to create the Route53 (or your domain provider) records yourself
        Route53:
          EvaluateTargetHealth: true # Default to false

        # TODO: What happens when this isn't the same as the API's EndpointConfiguration?
        # Allowed values: REGIONAL, EDGE; defaults to MyApi.EndpointConfiguration
        EndpointConfiguration: REGIONAL
        
        # If `EndpointConfiguration` is REGIONAL, this needs to be an ACM cert created in the same region as the API
        # If `EndpointConfiguration` is EDGE, this needs to be an ACM cert created in IAD
        # SAM doesn't need to perform any additional validation here
        # Default: An ACM Certificate is created for you
        Certificate: arn:...

        # Advanced Certificate:
        Certificate:
          CertificateArn: !Ref MyCertificate
          ValidationMethod: DNS # Default: {Route53 == true ? DNS : EMAIL}; Allowed: EMAIL|DNS

        # Default: '/' which creates a BasePathMapping from the root of the domain
        # to this API's StageName
        BasePath: /api

        # Either BasePathMappings OR BasePath should be specified; if both are specified an error should be thrown.
        # Including here to advanced configuration
        BasePathMappings:
          - BasePath: /api # Default: '/'
            Api: !Ref MyApiAdvancedDomain # Default: !Ref MyApiAdvancedDomain; use case: mapping this domain to additional APIs
            Stage: '' # Default: {MyApi.Stage}
            # Setting `Stage` to '' sets up a mapping which allows clients to specify
            # the Stage in the path when making requests.
            # e.g http://example.com/api/Prod/users, http://example.com/api/Beta/users
          - BasePath: /other-api
            Api: !Ref MyOtherApi # Add a Domain mapping which points to a different API+Stage

CloudFormation Output:

Resources:
  ...
  # This is only created if `Domain.Certificate` isn't provided
  MyApiCertificate:
    Type: 'AWS::CertificateManager::Certificate'
    Properties:
      DomainName: example.com
  
  MyApiDomainName:
    Type: 'AWS::ApiGateway::DomainName'
    Properties:
      # If `Domain.EndpointConfiguration` is 'REGIONAL', set `RegionalCertificateArn` instead of `CertificateArn`
      # If `Domain.Certificate` is provided, the value gets passed through instead of creating `MyApiCertificate`
      CertificateArn: !Ref MyApiCertificate

      DomainName: example.com
  
  # Create one `BasePathMapping` Resource per `Domain.BasePathMappings`
  MyApiBasePathMapping:
    Type: 'AWS::ApiGateway::BasePathMapping'
    Properties:
      RestApiId: !Ref MyApi
      DomainName: !Ref MyApiDomainName
      BasePath: /
      Stage: Prod
  
  MyApi:
    Type: 'AWS::ApiGateway::RestApi'
    Properties:
      ...

  MyApiRoute53RecordSetGroup:
    Type: AWS::Route53::RecordSetGroup
    Properties:
      HostedZoneName: example.com.
      RecordSets:
        - Name: example.com.
          Type: A
          AliasTarget:
            EvaluateTargetHealth: false
            HostedZoneId: !GetAtt MyApiDomainName.DistributionHostedZoneId
            DNSName: !GetAtt MyApiDomainName.DistributionDomainName
            
            # For REGIONAL:
            # HostedZoneId: !GetAtt MyApiDomainName.RegionalHostedZoneId
            # DNSName: !GetAtt MyApiDomainName.RegionalDomainName

Related Issues

• BasePathMapping deployment error: Invalid stage identifier specified #192
• Support API Gateway Logging Metrics, Usage Plans, EndpointConfiguration, and CORS #248
• Custom Domain Name Base Path Mapping #119
• Custom Domain Names? #40

[hoegertn]

The Route53 record would be:

  MyRoute53Record:
    Type: 'AWS::Route53::RecordSet'
    Properties:
      HostedZoneName: example.com.
      Name: example.com.
      Type: A
      AliasTarget:
        HostedZoneId: !GetAtt MyApiDomainName.DistributionHostedZoneId
        DNSName: !GetAtt MyApiDomainName.DistributionDomainName

[timoschilling]

Feature request:

Domain:
  IPv6: true

Which creates an AWS::Route53::RecordSet with Type: A and one with Type: AAAA

[brettstack]

@hoegertn @timoschilling Thanks. We should probably use AWS::Route53::RecordSetGroup to allow for multiple RecordSets. If IPv6 is a Route53 level configuration only, we should rename ConfigureRoute53 to Route53 and allow either an Object accepting properties such as IPv6, or a boolean with sane defaults (default to IPv6: true?).

[brettstack]

I imagine most users want to have a single domain mapped to a single API. If that's the case, then leaving it as a single Domain is fine. However, if a significant number of users are likely to map multiple Domains to a single API+Stage, we should consider allowing a list of Domains. We can always launch initially with a single Domain and modify Domain to also accept an Array in the future. We just need to think this through to make sure we don't go through any one-way doors that would be backwards incompatible.

[brettstack]

@timoschilling Are you referring to the scenario where you specify REGIONAL, then create your own CloudFront Distribution using IPv6 and point Route53 at that CF Distro? IPv6 aside, we should aim to cover the common use case of self-managed CF Distros.

The main question to answer here is: does that only have ramifications for Domain Name/Route53 (e.g Route53 now needs to point at your CF Distro with your CF Distro pointing at your API endpoint) or does it affect other areas of your API? If it's just Route53, we can add add a HostedZoneId and DNSName property to the Route53 section which takes an ARN and then creates RecordSets based using those values if defined (and uses AAAA if IPv6 is defined). Alternatively we can allow setting CloudFrontDistribution and we set DNSName and HostedZoneId based on !GetAtt of CloudFrontDistribution but this isn't as flexible (e.g when the CF Distro was created external to this template and you can't get a reference to the resource)

[ericofusco]

How would the certificate validation work? Can we get the cloudformation output from Certificate resource and add to Route53 or using email is a better option to implement on this flow?

[deleugpn]

Would love domain on SAM. I'm also curious as to how certificate validation would be handled since that's the biggest issue with AWS at the moment because of how hard it is to automate.

[brettstack]

It's been a while since I've done cert creation via CFN. Does the stack stay in CREATING process until you approve the email regarding certificate creation? Email was the only method I was aware of for validation. Any solution needs to also work for other DNS providers.

[deleugpn]

AFAIK it does stay in creating for up to 24 hours.
There's a new validation method for DNS lookup but it requires calling describeStack to see what value should be created on Route 53, which I don't think it's feasible for CFN.

[brettstack]

Some additional (likely less common) scenarios:

1. Single Domain pointing at multiple APIs
2. Multiple Domains pointing at single API
3. Multiple Domains pointing at multiple APIs

Proposal summary: We can allow Domain to also accept an Array for specifying multiple Domains. To point a Domain at additional APIs, the user specifies Api in the BasePathMapping (by default, it uses !Ref ThisApi). The syntax is a little odd since you're referencing a separate API from a config nested under a different API, but I think acceptable given that this is probably less common than the 1:1 api:domain use case, and this syntax is better than the alternative which would be splitting Domain into a separate resource.

Note that we may choose not to support these cases on the initial release of Custom Domain Name support, but want to leave the syntax open to allow for it in the future.

# Single Domain pointing at multiple APIs
SingleDomainApi1:
  Type: AWS::Serverless::Api
  Properties:
    ...
    Domain:
      DomainName: example.com
      Route53:
        EvaluateTargetHealth: true
      EndpointConfiguration: REGIONAL
      Certificate: arn:...
      BasePathMappings:
        - BasePath: /api
          Stage: ''
        - BasePath: /api
          Stage: ''

          # Feels odd because this will add a mapping of the Domain
          # (which we're configuring under Api1) to point to Api2
          # This is probably the simplest implementation in terms
          # of development, and while a little odd, is the smallest
          # amount of additional work required by end user
          Api: !Ref SingleDomainApi2

SingleDomainApi2:
  Type: AWS::Serverless::Api
  Properties:
    ...

# Multiple Domains pointing at single API
MultipleDomainsApi:
  Type: AWS::Serverless::Api
  Properties:
    ...
    # Domain: [example.com, foobar.example.com]
    Domain:
      - DomainName: example.com
        Route53:
          EvaluateTargetHealth: true
        EndpointConfiguration: REGIONAL
        Certificate: arn:...
        BasePathMappings:
          - BasePath: /api
            Stage: ''
      - DomainName: foo.example.com
        ...

# Multiple Domains pointing at multiple APIs
MultiDomainMultiApi1:
  Type: AWS::Serverless::Api
  Properties:
    ...
    Domain:
      - DomainName: example.com
        Route53:
          EvaluateTargetHealth: true
        EndpointConfiguration: REGIONAL
        Certificate: arn:...
        BasePathMappings:
          - BasePath: /api
            Stage: ''
          - BasePath: /api
            Stage: ''
            Api: !Ref MultiDomainMultiApi2
      - DomainName: foo.example.com
        ... # Specify multiple BasePathMappings similar to above

  MultiDomainMultiApi2:
    Type: AWS::Serverless::Api
    Properties:
      ...