/deploying-custom-domain-rest-api

name: deploying-custom-domain-rest-api
description: >
  Deploys a Regional REST API with a custom domain name, a Lambda backend function,
  and a request-based Lambda authorizer using AWS CLI. Covers ACM certificate
  provisioning, API Gateway REST API creation, Lambda function deployment, request
  authorizer setup, custom domain configuration, base path mapping, and Route 53
  DNS record creation. Trigger keywords: custom domain, REST API, Lambda, Route 53,
  API Gateway, regional endpoint, request authorizer, base path mapping.
version: 1

Custom Domain REST API with Lambda and Request Authorizer

Overview

This SOP deploys a REST API with a Regional custom domain name, a Lambda backend function, and a request-based Lambda authorizer. It handles ACM certificate provisioning, IAM role creation, Lambda function deployment, API Gateway REST API creation with a custom authorizer, custom domain configuration, base path mapping, and Route 53 DNS setup.

The architecture includes:

• An API Gateway REST API with an endpoint type of REGIONAL
• A request-based Lambda authorizer that validates headers, query string parameters, and stage variables
• A Lambda backend function at `GET /example`
• A custom domain name with TLS 1.2
• A base path mapping connecting the custom domain to the API stage
• A Route 53 A-alias record pointing the custom domain to the API Gateway Regional endpoint

Important: This SOP uses Regional endpoints. If the user requests a private endpoint, inform them that this skill covers Regional endpoints only. Private endpoints require VPC endpoint configuration.

Parameters

• custom_domain_name (required): Fully qualified domain name for the API (e.g., `api.example.com`)
• region (required): AWS Region for all resources. The ACM certificate must be in this same Region for Regional endpoints
• hosted_zone_id (required): Route 53 hosted zone ID for the domain
• acm_certificate_arn (optional): ARN of an existing ACM certificate covering the custom domain. If not provided, Step 2 creates one
• stage_name (optional, default: "dev"): API Gateway stage name

Constraints for parameter acquisition:

• You MUST ask for all required parameters upfront in a single prompt rather than one at a time
• You MUST support multiple input methods (direct input, file path, URL)
• You MUST confirm successful acquisition of all parameters before proceeding
• You MUST inform the user that this skill uses hardcoded demo authorization values (headerValue1, queryValue1, stageValue1) that are NOT suitable for production. For production, use AWS Secrets Manager or Systems Manager Parameter Store to manage authorization credentials. See: https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html
• You MUST validate that custom_domain_name is a valid FQDN

Steps

0. Verify Dependencies

Constraints:

• You MUST verify the following tools are available: aws-cli, python3, sed, node (v22+)
• You MUST inform the user about any missing tools with a clear message
• You MUST ask if the user wants to proceed despite missing tools
• You MUST respect the customer's decision to abort at any point
• You MUST explain to the customer what step is being executed, why, and which tool is being called

1. Retrieve AWS Account ID

This step MUST be performed before all other steps.

Constraints:

• You MUST retrieve the account ID with: `aws sts get-caller-identity --query 'Account' --output text`
• You MUST store the result as {account_id} and reuse it in all subsequent steps that reference {account_id}
• You MUST abort if credentials are not configured

2. Request ACM Certificate

Skip this step if acm_certificate_arn is already provided.

Constraints:

• You MUST request the certificate with: `aws acm request-certificate --domain-name {custom_domain_name} --validation-method DNS --region {region}`
• You MUST capture the CertificateArn from the response
• You MUST retrieve the DNS validation record with: `aws acm describe-certificate --certificate-arn {cert_arn} --query 'Certificate.DomainValidationOptions[0].ResourceRecord' --region {region}`
• You MUST create the validation CNAME in Route 53 with: `aws route53 change-resource-record-sets --hosted-zone-id {hosted_zone_id} --change-batch '{"Changes":[{"Action":"UPSERT","ResourceRecordSet":{"Name":"{validation_name}","Type":"CNAME","TTL":300,"ResourceRecords":[{"Value":"{validation_value}"}]}}]}'`
• You MUST wait for certificate validation with: `aws acm wait certificate-validated --certificate-arn {cert_arn} --region {region}`
• The wait command may take up to 30 minutes. If it times out, check status manually with: `aws acm describe-certificate --certificate-arn {cert_arn} --query 'Certificate.Status' --region {region}` and retry the wait if status is still PENDING_VALIDATION
• You MUST NOT proceed until the certificate status is ISSUED
• You MUST store the certificate ARN as acm_certificate_arn for use in Step 7

3. Create IAM Execution Roles

Constraints:

• You MUST create two IAM roles: one for the authorizer Lambda and one for the example function Lambda
• Both roles use the same trust policy from `scripts/lambda-trust-policy.json`. The trust policy includes an `aws:SourceAccount` condition scoped to the user's account ID
• You MUST create a working copy of the trust policy and replace the `ACCOUNT_ID` placeholder with the actual account ID from Step 1. Use: `sed 's/ACCOUNT_ID/{account_id}/' scripts/lambda-trust-policy.json > /tmp/lambda-trust-policy.json`
• You MUST create the authorizer role with: `aws iam create-role --role-name request-authorizer-role --assume-role-policy-document file:///tmp/lambda-trust-policy.json`
• You MUST attach the basic execution policy to the authorizer role with: `aws iam attach-role-policy --role-name request-authorizer-role --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole`
• You MUST create the example function role with: `aws iam create-role --role-name exam