Monitoring the state of a function with the Lambda API - AWS Lambda

Monitoring the state of a function with the Lambda API

When you create or update a function, Lambda provisions the compute and networking resources that enable it to run. In most cases, this process is very fast, and your function is ready to be invoked or modified right away.

If you configure your function to connect to a virtual private cloud (VPC), the process can take longer. When you first connect a function to a VPC, Lambda provisions network interfaces, which takes about a minute. To communicate the current state of your function, Lambda includes additional fields in the function configuration document that is returned by several Lambda API actions.

When you create a function, the function is initially in the Pending state. When the function is ready to be invoked, the state changes from Pending to Active. While the state is Pending, invocations and other API actions that operate on the function return an error. If you build automation around creating and updating functions, wait for the function to become active before performing additional actions that operate on the function.

You can use the Lambda API to get information about a function's state. State information is included in the FunctionConfiguration document returned by several API actions. To view the function's state with the AWS CLI, use the get-function-configuration command. 

$ aws lambda get-function-configuration --function-name my-function
{
    "FunctionName": "my-function",
    "FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
    "Runtime": "nodejs12.x",
    "Role": "arn:aws:iam::123456789012:role/lambda-role",
    "TracingConfig": {
        "Mode": "Active"
    },
    "State": "Pending",
    "StateReason": "The function is being created.",
    "StateReasonCode": "Creating",
    ...
}

The StateReason and StateReasonCode contain additional information about the state when it is not Active. The following operations fail while function creation is pending:

When you update a function's configuration, the update can trigger an asynchronous operation to provision resources. While this is in progress, you can invoke the function, but other operations on the function fail. Invocations that occur while the update is in progress run against the previous configuration. The function's state is Active, but its LastUpdateStatus is InProgress.

Example Function configuration – Connecting to a VPC

{
    "FunctionName": "my-function",
    "FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
    "Runtime": "nodejs12.x",
    "VpcConfig": {
        "SubnetIds": [
            "subnet-071f712345678e7c8",
            "subnet-07fd123456788a036",
            "subnet-0804f77612345cacf"
        ],
        "SecurityGroupIds": [
            "sg-085912345678492fb"
        ],
        "VpcId": "vpc-08e1234569e011e83"
    },
    "State": "Active",
    "LastUpdateStatus": "InProgress",
    ...
}

The following operations fail while an asynchronous update is in progress:

Other operations, including invocation, work while updates are in progress.

For example, when you connect your function to a virtual private cloud (VPC), Lambda provisions an elastic network interface for each subnet. This process can leave your function in a pending state for a minute or so. Lambda also reclaims network interfaces that are not in use, placing your function in an Inactive state. When the function is inactive, an invocation causes it to enter the Pending state while network access is restored. The invocation that triggers restoration, and further invocations while the operation is pending, fail with ResourceNotReadyException.

If Lambda encounters an error when restoring a function's network interface, the function goes back to the Inactive state. The next invocation can trigger another attempt. For some configuration errors, Lambda waits at least 5 minutes before attempting to create another network interface. These errors have the following LastUpdateStatusReasonCode values:

  • InsufficientRolePermission – Role doesn't exist or is missing permissions.

  • SubnetOutOfIPAddresses – All IP addresses in a subnet are in use.

For more information on how states work with VPC connectivity, see Configuring a Lambda function to access resources in a VPC.