View a markdown version of this page

Managing Web Function revisions - AWS Lambda
Revision propertiesCreating a revisionListing revisionsDeleting a revisionConfiguring revision settings

Managing Web Function revisions

A revision is an immutable snapshot of your Web Function application code and configuration. To change your code or any revision setting, such as timeoutSeconds, maxConcurrencyPerEnvironment, or environmentVariables, you create a new revision. Whether the new revision receives traffic depends on each endpoint's auto-deployment mode. An endpoint in LatestRevision mode routes all traffic to the new revision after it becomes Active. An endpoint in Disabled mode keeps its current revision weights until you change them. Because revisions are immutable, you can roll back by routing traffic to an earlier revision. The earlier revision must remain Active, and its code, key, role, and other dependencies must remain available. For information about routing traffic between revisions, see Deployment patterns.

Revision properties

Each revision contains the following configuration:

Property Description Default Changeable
revisionId A unique ID that Lambda generates when you create the revision. – No (generated)
revisionArn The Amazon Resource Name (ARN) of the revision. – No (generated)
functionArn The ARN of the Web Function that the revision belongs to. – No (generated)
state The lifecycle state of the revision (Pending, Active, or Failed). For details, see Revision states. – No (managed by Lambda)
stateReason A description of why the revision is in its current state, for example the cause of a Failed state. – No (managed by Lambda)
errors A list of errors that Lambda found while creating or reading the revision. Each error names the affected attribute and includes an error code and a message. Absent when the revision has no errors. – No (managed by Lambda)
createdAt The timestamp when the revision was created. – No (generated)
description An optional description for the revision that you provide when you create it. None No (immutable)
buildConfig The code and runtime for the revision. Contains the codeConfig and runtimeConfig settings described in the following rows. – No (immutable)
codeConfig The location of the deployment package. Contains the s3Object setting described in the following rows. Part of buildConfig. – No (immutable)
s3Object The Amazon S3 location of the deployment package. Contains the bucket, key, and versionId settings described in the following rows. For details, see Deploying Web Function code from Amazon S3. Part of codeConfig. – No (immutable)
bucket The name of the Amazon S3 bucket that contains the deployment package. The bucket must have S3 versioning enabled. Part of s3Object. – No (immutable)
key The Amazon S3 object key of the deployment package. Part of s3Object. – No (immutable)
versionId The version ID of the Amazon S3 object. Optional. If you omit it, Lambda uses the latest version of the object at creation time. Either way, Lambda pins the revision to a specific object version. Part of s3Object. Latest version No (immutable)
runtimeConfig The runtime configuration. Contains the runtime setting described in the following row. Part of buildConfig. – No (immutable)
runtime The runtime identifier (for example, nodejs24.x). For supported runtimes, see Lambda Web Function runtimes. Although the runtime identifier is fixed for the revision, the runtime itself is not frozen. Lambda automatically applies security patches and bug fixes to the runtime, so the identifier (for example, nodejs24.x) always resolves to the latest patched version. For details, see Automatic runtime patching. Part of runtimeConfig. – No (immutable)
serviceConfig The runtime settings for the revision. Contains the executionRoleArn, timeoutSeconds, maxConcurrencyPerEnvironment, environmentVariables, and telemetryConfig settings described in the following rows. – No (immutable)
executionRoleArn The ARN of the IAM role that the Web Function assumes at runtime. The role grants permissions to access AWS services and resources. Required. For details, see Execution role. Part of serviceConfig. – No (immutable)
timeoutSeconds The maximum time in seconds that a single HTTP request can run. Valid values: 3–900. Part of serviceConfig. 30 No (immutable)
maxConcurrencyPerEnvironment The maximum number of concurrent HTTP requests per execution environment. Valid values: 1–128. Part of serviceConfig. 64 No (immutable)
environmentVariables Key-value pairs available to your application at runtime. Set per-revision and immutable after creation. Part of serviceConfig. None No (immutable)
telemetryConfig Telemetry settings for the revision. Contains the loggingConfig setting described in the following rows. If you omit telemetryConfig, Lambda still sends your application logs to the default log group. Part of serviceConfig. None No (immutable)
loggingConfig The logging configuration for the revision. Contains the logGroup, applicationLogLevel, and systemLogLevel settings described in the following rows. For details, see Logging controls. Part of telemetryConfig. None No (immutable)
logGroup The Amazon CloudWatch Logs log group that receives your logs. Log group names that start with aws/ are reserved and rejected. For details, see Using a custom log group. Part of loggingConfig. /aws/lambda/web/function-name No (immutable)
applicationLogLevel The minimum severity of your application's logs that Lambda sends to Amazon CloudWatch Logs. Valid values: TRACE, DEBUG, INFO, WARN, ERROR, and FATAL. Part of loggingConfig. INFO No (immutable)
systemLogLevel The minimum severity of Lambda-generated system logs that Lambda sends to Amazon CloudWatch Logs. Valid values: DEBUG, INFO, and WARN. Part of loggingConfig. INFO No (immutable)
kmsKeyArn The ARN of the customer managed key used to encrypt code and environment variables. Optional. If a MultiRegion or PerRegion endpoint routes traffic to the revision, use a multi-Region key with a replica in each of the endpoint's Regions. For details, see Encryption at rest for Web Functions. None No (immutable)

All revision properties are immutable after creation. To change any configuration, create a new revision with the updated values.

Creating a revision

Lambda creates a revision when you call CreateWebFunctionRevision. You provide the code location and configuration in the request. A new revision doesn't copy settings from an existing revision. Specify every setting that you want to keep, including environment variables. Settings that you omit use their defaults. To start from the current values, run get-web-function-revision and reuse its buildConfig and serviceConfig with your changes. The new revision starts in the Pending state while Lambda downloads your code and prepares a code artifact from it. When preparation completes, the revision transitions to Active. If an error occurs during preparation, the revision transitions to Failed and cannot serve traffic. For details about each state, see Revision states.

Before you create a revision, upload your .zip deployment package to a versioned Amazon S3 bucket, and get the ARN of an execution role that Lambda can assume. For details, see Deploying Web Function code from Amazon S3 and Execution role.

To create a revision with updated code (AWS CLI)

  1. Run the following command to create a new revision. Replace the S3 bucket, key, role ARN, and configuration values with your own.

    aws lambda-web create-web-function-revision \
    --function-name my-web-app \
    --build-config '{
      "codeConfig": {
        "s3Object": {
          "bucket": "my-bucket",
          "key": "my-app-v2.zip"
        }
      },
      "runtimeConfig": { "runtime": "nodejs24.x" }
    }' \
    --service-config '{
      "executionRoleArn": "arn:aws:iam::111122223333:role/my-web-function-role"
    }'

    The command uses the following objects. For each setting and its default, see Revision properties.

    • buildConfig contains codeConfig, the Amazon S3 bucket and key of your deployment package, and runtimeConfig, the runtime (for example, nodejs24.x). Both are required.

    • serviceConfig contains the required executionRoleArn, the ARN of the execution role that your Web Function assumes when it runs. It can also contain timeoutSeconds, maxConcurrencyPerEnvironment, environmentVariables, and telemetryConfig.

    The command returns details about the new revision, including its revisionId. The revision starts in the Pending state.

  2. To confirm that the revision is Active, run the following command. Replace my-web-app with your function name and rev-a1b2c with the revisionId from the response.

    aws lambda-web get-web-function-revision \
    --function-name my-web-app \
    --revision-id rev-a1b2c

    The revision is ready when state is Active. If state is Failed, stateReason describes the cause. For details, see Revision states.

    Right after you create a revision, its state is usually Pending. To wait until it's Active, run aws lambda-web wait web-function-revision-active with the same options.

To create a revision with updated configuration (AWS CLI)

  1. To change configuration without changing code, specify the same code location with the new settings. The following example changes the timeout to 60 seconds and adds an environment variable.

    aws lambda-web create-web-function-revision \
    --function-name my-web-app \
    --build-config '{
      "codeConfig": {
        "s3Object": {
          "bucket": "my-bucket",
          "key": "my-app-v2.zip"
        }
      },
      "runtimeConfig": { "runtime": "nodejs24.x" }
    }' \
    --service-config '{
      "executionRoleArn": "arn:aws:iam::111122223333:role/my-web-function-role",
      "timeoutSeconds": 60,
      "maxConcurrencyPerEnvironment": 32,
      "environmentVariables": {
        "DATABASE_URL": "my-database-endpoint",
        "LOG_LEVEL": "info"
      }
    }'

  2. To confirm that the revision is Active, run the following command. Replace my-web-app with your function name and rev-a1b2c with the revisionId from the response.

    aws lambda-web get-web-function-revision \
    --function-name my-web-app \
    --revision-id rev-a1b2c

    The revision is ready when state is Active. If state is Failed, stateReason describes the cause. For details, see Revision states.

    Right after you create a revision, its state is usually Pending. To wait until it's Active, run aws lambda-web wait web-function-revision-active with the same options.

After creating the revision, how traffic reaches it depends on the endpoint's auto-deployment mode. For details, see Deployment patterns.

Listing revisions

To view all revisions for a Web Function, use the following command:

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

The response includes each revision's identifier, state, creation timestamp, and configuration summary. Use the revision identifier when updating endpoint revision weights or when deleting a revision.

Deleting a revision

You can delete a revision that is no longer needed. Deleting a revision permanently removes it. Your deployment package in Amazon S3 is not affected.

Important

You cannot delete a revision that any endpoint routes traffic to (a revision with a non-zero weight on any endpoint). Remove the revision from the revision weights of every endpoint before deleting it.

To delete a revision (AWS CLI)

  • Run the following command to delete a specific revision.

    aws lambda-web delete-web-function-revision \
    --function-name my-web-app \
    --revision-id rev-a1b2c

Revision limits and automatic cleanup

Lambda uses 50 revisions per Web Function as its automatic cleanup target. The target is not adjustable. In the Service Quotas console, it appears as Revisions per Web Function (web-function-revisions-per-function).

You don't need to delete old revisions to stay within the cleanup target. When a new revision becomes Active and the total revision count exceeds the cleanup target, Lambda automatically deletes the oldest revisions that are not in use. A revision is in use when any endpoint routes traffic to it, including when it's referenced anywhere in the regionalEndpoints property of a MultiRegion or PerRegion endpoint. Lambda doesn't automatically delete a revision that is in use or the revision that just became Active. Cleanup is asynchronous. The revision count might temporarily exceed 50 while older revisions are still in use or cleanup is in progress. A revision that you remove from all revision weights, such as a rollback target, can be deleted by cleanup.

You can also delete revisions manually at any time. For the procedure, see the preceding section.

Each revision's deployment package can be up to 512 MB (unzipped). Because you provide your deployment package in your own Amazon S3 bucket and Lambda references your code directly from the bucket, there is no separate code storage quota for Web Functions. For details, see Deploying Web Function code from Amazon S3.

Configuring revision settings

All configuration is set per-revision and is immutable after creation. To change any setting, create a new revision with the updated values. The following settings control execution behavior.

For the request timeout and environment variable settings, see Request timeout and Environment variables in Configuring Lambda Web Functions.

Concurrency per environment

The maxConcurrencyPerEnvironment setting controls how many HTTP requests a single execution environment handles at the same time. Valid values are 1–128. The default is 64.

For I/O-bound applications (many requests waiting on database or network calls), a higher value maximizes utilization. For CPU-bound applications, a lower value reduces contention. For more guidance, see Scaling behavior for Lambda Web Functions.