Class GuKinesisLambdaExperimentalExperimental

Pattern which creates all of the resources needed to invoke a lambda function whenever a record is put onto a Kinesis stream.

This pattern will create a new Kinesis stream by default. If you are migrating a stack from CloudFormation, you will need to opt-out of this behaviour. For information on overriding the default behaviour, see [[GuKinesisLambdaProps]].

The Kinesis stream is stateful, and is accessible via kinesisStream.

https://github.com/guardian/cdk/blob/main/docs/stateful-resources.md

This pattern is in early development. The API is likely to change in future releases.

Hierarchy (View Summary)

Constructors

Properties

_connections?: Connections

Actual connections object for this Lambda

May be unset, in which case this Lambda is not configured use in a VPC.

_functionUrlInvocationGrants: Record<string, Grant>

Mapping of fucntion URL invocation principals to grants. Used to de-dupe grantInvokeUrl() calls.

_invocationGrants: Record<string, Grant>

Mapping of invocation principals to grants. Used to de-dupe grantInvoke() calls.

_layers: ILayerVersion[]
_logRetention?: LogRetention
_skipPermissions?: boolean

Whether the user decides to skip adding permissions. The only use case is for cross-account, imported lambdas where the user commits to modifying the permisssions on the imported lambda outside CDK.

_warnIfCurrentVersionCalled: boolean

Flag to delay adding a warning message until current version is invoked.

alias?: Alias
app: string
architecture: Architecture

The architecture of this Lambda Function (this is an optional attribute and defaults to X86_64).

bucketNamePath: undefined | string
canCreatePermissions: true

Whether the addPermission() call adds any permissions

True for new Lambdas, false for version $LATEST and imported Lambdas from different accounts.

deadLetterQueue?: IQueue

The DLQ (as queue) associated with this Lambda Function (this is an optional attribute).

deadLetterTopic?: ITopic

The DLQ (as topic) associated with this Lambda Function (this is an optional attribute).

env: ResourceEnvironment

The environment this resource belongs to. For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

fileName: string
functionArn: string

ARN of this function

functionName: string

Name of this function

grantPrincipal: IPrincipal

The principal this Lambda Function is running as

kinesisStream: IStream
node: Node

The tree node.

permissionsNode: Node

The construct node where permissions are attached.

physicalName: string

Returns a string-encoded token that resolves to the physical name that should be passed to the CloudFormation resource.

This value will resolve to one of the following:

  • a concrete value (e.g. "my-awesome-bucket")
  • undefined, when a name should be generated by CloudFormation
  • a concrete name generated automatically during synthesis, in cross-environment scenarios.
role?: IRole

Execution role associated with this function

runtime: Runtime

The runtime configured for this lambda.

stack: Stack

The stack in which this resource is defined.

timeout?: Duration

The timeout configured for this lambda.

withoutArtifactUpload: boolean
withoutFilePrefix: boolean
_VER_PROPS: { [key: string]: boolean }

Accessors

  • get connections(): Connections
  • Experimental

    Access the Connections object

    Will fail if not a VPC-enabled Lambda Function

    Returns Connections

  • get currentVersion(): Version
  • Experimental

    Returns a lambda.Version which represents the current version of this Lambda function. A new version will be created every time the function's configuration changes.

    You can specify options for this version using the currentVersionOptions prop when initializing the lambda.Function.

    Returns Version

  • get isBoundToVpc(): boolean
  • Experimental

    Whether or not this Lambda function was bound to a VPC

    If this is is false, trying to access the connections object will fail.

    Returns boolean

  • get latestVersion(): IVersion
  • Experimental

    The $LATEST version of this function.

    Note that this is reference to a non-specific AWS Lambda version, which means the function this version refers to can return different results in different invocations.

    To obtain a reference to an explicit version which references the current function configuration, use lambdaFunction.currentVersion instead.

    Returns IVersion

  • get logGroup(): ILogGroup
  • Experimental

    The LogGroup where the Lambda function's logs are made available.

    If either logRetention is set or this property is called, a CloudFormation custom resource is added to the stack that pre-creates the log group as part of the stack deployment, if it already doesn't exist, and sets the correct log retention period (never expire, by default).

    Further, if the log group already exists and the logRetention is not set, the custom resource will reset the log retention to never expire even if it was configured with a different value.

    Returns ILogGroup

  • get resourceArnsForGrantInvoke(): string[]
  • Experimental

    The ARN(s) to put into the resource field of the generated IAM policy for grantInvoke()

    Returns string[]

Methods

  • Internal

    Called when this resource is referenced across environments (account/region) to order to request that a physical name will be generated for this resource during synthesis, so the resource can be referenced through its absolute name/arn.

    Returns void

  • Internal

    Returns the construct tree node that corresponds to the lambda function. For use internally for constructs, when the tree is set up in non-standard ways. Ex: SingletonFunction.

    Returns Node

  • Internal

    Given the function arn, check if the account id matches this account

    Function ARNs look like this:

    arn:aws:lambda:region:account-id:function:function-name

    ..which means that in order to extract the account-id component from the ARN, we can split the ARN using ":" and select the component in index 4.

    Returns boolean

    true if account id of function matches the account specified on the stack, false otherwise.

  • Experimental

    Defines an alias for this function.

    The alias will automatically be updated to point to the latest version of the function as it is being updated during a deployment.

    declare const fn: lambda.Function;

    fn.addAlias('Live');

    // Is equivalent to

    new lambda.Alias(this, 'AliasLive', {
    aliasName: 'Live',
    version: fn.currentVersion,
    });

    Parameters

    • aliasName: string

      The name of the alias

    • Optionaloptions: AliasOptions

      Alias options

    Returns Alias

  • Experimental

    Adds an environment variable to this Lambda function. If this is a ref to a Lambda function, this operation results in a no-op.

    Parameters

    • key: string

      The environment variable key.

    • value: string

      The environment variable's value.

    • Optionaloptions: EnvironmentOptions

      Environment variable options.

    Returns this

  • Experimental

    Adds an event source to this function.

    Event sources are implemented in the aws-cdk-lib/aws-lambda-event-sources module.

    The following example adds an SQS Queue as an event source:

    import { SqsEventSource } from 'aws-cdk-lib/aws-lambda-event-sources';
    myFunction.addEventSource(new SqsEventSource(myQueue));

    Parameters

    • source: IEventSource

    Returns void

  • Experimental

    Adds an event source that maps to this AWS Lambda function.

    Parameters

    • id: string

      construct ID

    • options: EventSourceMappingOptions

      mapping options

    Returns EventSourceMapping

  • Experimental

    Adds a url to this lambda function.

    Parameters

    • Optionaloptions: FunctionUrlOptions

    Returns FunctionUrl

  • Experimental

    Adds one or more Lambda Layers to this Lambda function.

    Parameters

    • ...layers: ILayerVersion[]

      the layers to be added.

    Returns void

    if there are already 5 layers on this function, or the layer is incompatible with this function's runtime.

  • Experimental

    Adds a permission to the Lambda resource policy.

    Parameters

    • id: string

      The id for the permission construct

    • permission: Permission

      The permission to grant to this Lambda function.

    Returns void

    Permission for details.

  • Experimental

    Adds a statement to the IAM role assumed by the instance.

    Parameters

    • statement: PolicyStatement

    Returns void

  • Experimental

    Apply the given removal policy to this resource

    The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

    The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

    Parameters

    • policy: RemovalPolicy

    Returns void

  • Experimental

    Configures options for asynchronous invocation.

    Parameters

    • options: EventInvokeConfigOptions

    Returns void

  • Experimental

    A warning will be added to functions under the following conditions:

    • permissions that include lambda:InvokeFunction are added to the unqualified function.
    • function.currentVersion is invoked before or after the permission is created.

    This applies only to permissions on Lambda functions, not versions or aliases. This function is overridden as a noOp for QualifiedFunctionBase.

    Parameters

    • scope: Construct
    • action: string

    Returns void

  • Experimental

    Returns an environment-sensitive token that should be used for the resource's "ARN" attribute (e.g. bucket.bucketArn).

    Normally, this token will resolve to arnAttr, but if the resource is referenced across environments, arnComponents will be used to synthesize a concrete ARN with the resource's physical name. Make sure to reference this.physicalName in arnComponents.

    Parameters

    • arnAttr: string

      The CFN attribute which resolves to the ARN of the resource. Commonly it will be called "Arn" (e.g. resource.attrArn), but sometimes it's the CFN resource's ref.

    • arnComponents: ArnComponents

      The format of the ARN of this resource. You must reference this.physicalName somewhere within the ARN in order for cross-environment references to work.

    Returns string

  • Experimental

    Returns an environment-sensitive token that should be used for the resource's "name" attribute (e.g. bucket.bucketName).

    Normally, this token will resolve to nameAttr, but if the resource is referenced across environments, it will be resolved to this.physicalName, which will be a concrete name.

    Parameters

    • nameAttr: string

      The CFN attribute which resolves to the resource's name. Commonly this is the resource's ref.

    Returns string

  • Experimental

    Grant the given identity permissions to invoke this Lambda

    Parameters

    • grantee: IGrantable

    Returns Grant

  • Experimental

    Grant multiple principals the ability to invoke this Lambda via CompositePrincipal

    Parameters

    • compositePrincipal: CompositePrincipal

    Returns Grant[]

  • Experimental

    Grant the given identity permissions to invoke the $LATEST version or unqualified version of this Lambda

    Parameters

    • grantee: IGrantable

    Returns Grant

  • Experimental

    Grant the given identity permissions to invoke this Lambda Function URL

    Parameters

    • grantee: IGrantable

    Returns Grant

  • Experimental

    Grant the given identity permissions to invoke the given version of this Lambda

    Parameters

    • grantee: IGrantable
    • version: IVersion

    Returns Grant

  • Experimental

    Mix additional information into the hash of the Version object

    The Lambda Function construct does its best to automatically create a new Version when anything about the Function changes (its code, its layers, any of the other properties).

    However, you can sometimes source information from places that the CDK cannot look into, like the deploy-time values of SSM parameters. In those cases, the CDK would not force the creation of a new Version object when it actually should.

    This method can be used to invalidate the current Version object. Pass in any string into this method, and make sure the string changes when you know a new Version needs to be created.

    This method may be called more than once.

    Parameters

    • x: string

    Returns void

  • Experimental

    Return the given named metric for this Function

    Parameters

    • metricName: string
    • Optionalprops: MetricOptions

    Returns Metric

  • Experimental

    How long execution of this Lambda takes

    Average over 5 minutes

    Parameters

    • Optionalprops: MetricOptions

    Returns Metric

  • Experimental

    How many invocations of this Lambda fail

    Sum over 5 minutes

    Parameters

    • Optionalprops: MetricOptions

    Returns Metric

  • Experimental

    How often this Lambda is invoked

    Sum over 5 minutes

    Parameters

    • Optionalprops: MetricOptions

    Returns Metric

  • Experimental

    How often this Lambda is throttled

    Sum over 5 minutes

    Parameters

    • Optionalprops: MetricOptions

    Returns Metric

  • Experimental

    Returns a string representation of this construct.

    Returns string

  • Experimental

    Parameters

    • scope: Construct

    Returns void

  • Experimental

    Record whether specific properties in the AWS::Lambda::Function resource should also be associated to the Version resource. See 'currentVersion' section in the module README for more details.

    Parameters

    • propertyName: string

      The property to classify

    • locked: boolean

      whether the property should be associated to the version or not.

    Returns void

  • Experimental

    Import a lambda function into the CDK using its ARN.

    For Function.addPermissions() to work on this imported lambda, make sure that is in the same account and region as the stack you are importing it into.

    Parameters

    • scope: Construct
    • id: string
    • functionArn: string

    Returns IFunction

  • Experimental

    Creates a Lambda function object which represents a function not defined within this stack.

    For Function.addPermissions() to work on this imported lambda, set the sameEnvironment property to true if this imported lambda is in the same account and region as the stack you are importing it into.

    Parameters

    • scope: Construct

      The parent construct

    • id: string

      The name of the lambda construct

    • attrs: FunctionAttributes

      the attributes of the function to import

    Returns IFunction

  • Experimental

    Import a lambda function into the CDK using its name

    Parameters

    • scope: Construct
    • id: string
    • functionName: string

    Returns IFunction

  • Experimental

    Checks if x is a construct.

    Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

    Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

    Parameters

    • x: any

      Any object

    Returns x is Construct

    true if x is an object created from a class which extends Construct.

  • Experimental

    Returns true if the construct was created by CDK, and false otherwise

    Parameters

    • construct: IConstruct

    Returns boolean

  • Experimental

    Check whether the given construct is a Resource

    Parameters

    • construct: IConstruct

    Returns construct is Resource

  • Experimental

    Return the given named metric for this Lambda

    Parameters

    • metricName: string
    • Optionalprops: MetricOptions

    Returns Metric

  • Experimental

    Metric for the number of concurrent executions across all Lambdas

    Parameters

    • Optionalprops: MetricOptions

    Returns Metric

    max over 5 minutes
    
  • Experimental

    Metric for the Duration executing all Lambdas

    Parameters

    • Optionalprops: MetricOptions

    Returns Metric

    average over 5 minutes
    
  • Experimental

    Metric for the number of Errors executing all Lambdas

    Parameters

    • Optionalprops: MetricOptions

    Returns Metric

    sum over 5 minutes
    
  • Experimental

    Metric for the number of invocations of all Lambdas

    Parameters

    • Optionalprops: MetricOptions

    Returns Metric

    sum over 5 minutes
    
  • Experimental

    Metric for the number of throttled invocations of all Lambdas

    Parameters

    • Optionalprops: MetricOptions

    Returns Metric

    sum over 5 minutes
    
  • Experimental

    Metric for the number of unreserved concurrent executions across all Lambdas

    Parameters

    • Optionalprops: MetricOptions

    Returns Metric

    max over 5 minutes