Lambda Web Function endpoints

An endpoint is a child resource of a Web Function that provides a network entry point for HTTP traffic. Each endpoint includes a unique domain name with TLS and an authentication type. It also has settings for geographic scope, scaling, throttling, and traffic routing. A Web Function can have up to 10 endpoints, each with independent configuration.

The following sections explain endpoint types, domain names, authentication, and replication. For information about scaling and throttling settings, see Scaling behavior for Lambda Web Functions. For information about auto-deployment modes and traffic routing, see Deployment patterns.

Endpoint types

The endpoint type determines how Lambda deploys your Web Function across AWS Regions and how traffic is routed to it. You choose the endpoint type when you create the endpoint. The endpoint type cannot be changed after creation.

HomeRegion

Runs your Web Function in a single AWS Region. Lambda serves requests from the Region where you created the endpoint. Lambda allocates a single regional domain name for the endpoint.

Use HomeRegion for applications that do not require multi-Region availability, or when you want to start with the simplest configuration.

MultiRegion

Runs your Web Function in multiple AWS Regions. You specify the target Regions when you create the endpoint. Lambda adds the home Region automatically. The endpoint must include at least one other Region. To route traffic to a revision, you set the endpoint's revision weights. Lambda then replicates your code and configuration to all specified Regions automatically. Lambda allocates a single global domain name. It uses latency-based routing to send each request to the Region that typically provides the lowest latency for the caller. Lambda doesn't perform health-based failover.

You manage the Web Function from a single home Region. Lambda handles replication to the other Regions. Clients connect to one domain name.

Use MultiRegion for global applications that need low latency for users in multiple geographic locations.

PerRegion

Runs your Web Function in multiple AWS Regions, with a separate regional domain name in each Region. You specify the target Regions when you create the endpoint. Lambda adds the home Region automatically. The endpoint must include at least one other Region. Lambda sets up the endpoint in each specified Region automatically. Each Region has its own independent domain name.

Unlike MultiRegion, Lambda does not perform automatic latency-based routing. You manage how traffic reaches each regional domain, for example with your own Route 53 routing policy or a CloudFront distribution.

Use PerRegion when you need control over routing decisions per Region, for example to implement geographic restrictions, custom failover logic, or Region-specific traffic policies.

The Regions and endpoint type cannot be updated after creation. To change these, create a new endpoint with the configuration that you want, migrate traffic to the new endpoint's domain name, and then delete the old endpoint.

For details about how Lambda replicates your Web Function across Regions and routes traffic, see Multi-Region deployment.

Domain name

Lambda allocates a unique domain name to each endpoint when you create it. Clients send HTTPS requests to this domain to invoke your Web Function. The domain supports HTTPS, and Lambda manages the TLS certificate for the domain. You don't create, renew, or manage certificates yourself.

The domain name format depends on the endpoint type:

• HomeRegion and PerRegion – Each Region has a domain in the format:

  domain-id.shard-id.lambda-web.region.on.aws

  Example: bcdfghjklmnpqrst.b7t.lambda-web.ap-northeast-3.on.aws

• MultiRegion – A single global domain in the format:

  domain-id.lambda-web.global.on.aws

  Example: bcdfghjklmn.lambda-web.global.on.aws

  Lambda uses latency-based routing to select a Region for each client.

You can retrieve the domain name from the GetWebFunctionEndpoint response or from the Lambda console after the endpoint reaches the Active state.

Note

Web Function endpoints don't support attaching a custom domain name directly. Clients that call the endpoint's domain must use the Lambda-allocated domain name. To serve traffic on your own domain, put an Amazon CloudFront distribution in front of the endpoint and use the Lambda-allocated domain name as the origin.

Authentication type

The authType setting controls whether Lambda authenticates incoming HTTP requests before passing them to your application. You can update this setting on an existing endpoint.

ApplicationManaged

Lambda does not authenticate incoming requests. All HTTP requests are forwarded directly to your application. You are responsible for handling authentication in your application code.

IamAuth

Lambda validates the signature of each request. Sign requests with AWS Signature Version 4 (SigV4) for HomeRegion and PerRegion domains, and with Signature Version 4a (SigV4a) for a MultiRegion global domain. Only callers with the lambda:InvokeWebFunctionEndpoint permission can invoke the endpoint.

For full details on authentication, including CloudFront integration and resource-based policies, see Lambda Web Function endpoint access control.

Auto-deployment mode

The autoDeploymentMode setting controls whether Lambda automatically routes traffic to new revisions each time you deploy your application. You can update this setting on an existing endpoint.

If you omit autoDeploymentMode in an API request, it defaults to Disabled. The Lambda console and the aws lambda-web deploy command use LatestRevision for new HomeRegion endpoints. LatestRevision is supported only for HomeRegion endpoints, so MultiRegion and PerRegion endpoints always use Disabled. When using Disabled, specify revisionWeights that total 100.

LatestRevision

Lambda automatically routes 100% of traffic to the newest active revision. Use for development and staging environments. LatestRevision mode is available only for HomeRegion endpoints.

Disabled

Lambda does not change traffic routing when you create a new revision. You control routing manually with revision weights. Use for production environments. Disabled mode is available for all endpoint types. MultiRegion and PerRegion endpoints always use Disabled mode.

For details on deployment patterns, rollback, and mode switching behavior, see Deployment patterns.

Scaling and throttling

Each endpoint has scaling and throttling settings that control capacity. You can update these settings on an existing endpoint with update-web-function-endpoint. Omit --scaling-config or --throttle-config to keep its current value, or pass an empty object ('{}') to clear a previously set value. To remove a rate limit, pass an empty --throttle-config object. A rateLimit of 0 blocks all traffic.

• maxEnvironments – Optional. The maximum number of execution environments for the endpoint in each Region. When not set, the endpoint scales as needed within the account quotas.

• rateLimit – Maximum requests per second. This setting is optional. When it's not set, the endpoint is limited by the per-endpoint request rate quota of 10,000 RPS and by the account quotas. The rate limit applies to the endpoint as a whole, across all execution environments. It is not a per-environment limit. For MultiRegion and PerRegion endpoints, each Region enforces the limit independently. Excess requests receive HTTP 429.

For details on how these settings interact with revision-level concurrency and guidance on choosing values, see Scaling behavior for Lambda Web Functions.

Creating and managing endpoints

Creating an endpoint

To create a HomeRegion endpoint (AWS CLI)

• aws lambda-web create-web-function-endpoint \
      --function-name my-web-app \
      --endpoint-name my-endpoint \
      --endpoint-type HomeRegion \
      --auth-type ApplicationManaged \
      --auto-deployment-mode LatestRevision

To create a MultiRegion endpoint (AWS CLI)

• aws lambda-web create-web-function-endpoint \
      --function-name my-web-app \
      --endpoint-name my-global-endpoint \
      --endpoint-type MultiRegion \
      --regions us-east-1 eu-west-1 ap-northeast-1 \
      --auth-type ApplicationManaged \
      --revision-weights '[{"revisionId": "rev-a1b2c", "weight": 100}]'

  MultiRegion and PerRegion endpoints require revision weights, because LatestRevision auto-deployment is not available for them. For more information, see Deployment patterns.

Listing endpoints

aws lambda-web list-web-function-endpoints \
    --function-name my-web-app

The response includes each endpoint's name, type, domain name, state, and configuration.

Getting endpoint details

aws lambda-web get-web-function-endpoint \
    --function-name my-web-app \
    --endpoint-name my-endpoint

The response includes the endpoint's domain name, state, authentication type, auto-deployment mode, scaling settings, revision weights, and (for MultiRegion and PerRegion endpoints) each Region's state and update status in the regionalEndpoints field.

Updating an endpoint

You can update the following properties on an existing endpoint:

• description

• authType

• autoDeploymentMode

• revisionWeights

• scalingConfig

• throttleConfig

You cannot update the following properties. To change these, create a new endpoint with the configuration that you want, migrate traffic to the new endpoint's domain name, and then delete the old endpoint.

• endpointType (HomeRegion, MultiRegion, PerRegion)

• regions (the endpoint's target Regions)

Deleting an endpoint

aws lambda-web delete-web-function-endpoint \
    --function-name my-web-app \
    --endpoint-name my-endpoint

When you delete an endpoint, it enters the Deleting state. Lambda stops routing new requests to the endpoint and retires its domain name. For a PerRegion endpoint, Lambda retires the domain name in each Region. Lambda never assigns a deleted endpoint's domain names to another endpoint in any account. Lambda drains in-flight requests. It lets requests that are already in progress finish and rejects new requests to the endpoint's domain names. For MultiRegion and PerRegion endpoints, Lambda removes the endpoint from all Regions. After deletion is complete, Lambda permanently removes the endpoint.

Deleting an endpoint does not delete the Web Function or its revisions. Revisions remain available for use by other endpoints.