LambdaApiConfig

LambdaApiConfig is the reusable configuration for LambdaApi. It keeps defaults and named resource registries, and creates an isolated snapshot for each LambdaApi that reuses it.

Constructor

LambdaApiConfig(
    *,
    timeout: Optional[Duration] = None,
    memory_size: Optional[int] = None,
    vpc: Optional[ec2.IVpc] = None,
    vpc_subnets: Optional[ec2.SubnetSelection] = None,
    layers: Optional[Sequence[lambda_.ILayerVersion]] = None,
    security_groups: Optional[Sequence[ec2.ISecurityGroup]] = None,
    dynamodb_tables: Optional[Mapping[str, dynamodb.ITable]] = None,
    s3_buckets: Optional[Mapping[str, s3.IBucket]] = None,
    authorizers: Optional[Mapping[str, object]] = None,
    default_authorizer: Optional[str] = None,
    default_runtime: Optional[str] = None,
    default_role: Optional[iam.IRole] = None,
    common_environment: Optional[Mapping[str, str]] = None,
    role_registry: Optional[Mapping[str, iam.IRole]] = None,
    environment_registry: Optional[Mapping[str, Mapping[str, str]]] = None,
    layer_registry: Optional[Mapping[str, lambda_.ILayerVersion]] = None,
    security_group_registry: Optional[Mapping[str, ec2.ISecurityGroup]] = None,
    vpc_registry: Optional[Mapping[str, ec2.IVpc]] = None,
    dynamodb_table_registry: Optional[Mapping[str, dynamodb.ITable]] = None,
    s3_bucket_registry: Optional[Mapping[str, s3.IBucket]] = None,
    authorizer_registry: Optional[Mapping[str, object]] = None,
) -> None

All arguments default to None. default_runtime is a string alias; it accepts only python3.10 through python3.14. default_role is one IAM execution role. common_environment is the common map and can be defined only in the constructor. environment_registry is initialized in the constructor and can be extended with register_environment; it stores maps that merge over common values.

vpc and vpc_subnets are retained as one selection. layers and security_groups are common values. Constructor mappings are copied, while CDK objects keep their identity.

from lambda_api_decorators_cdk import LambdaApiConfig

config = LambdaApiConfig(
    default_runtime="python3.14",
    default_role=execution_role,
    common_environment={"SERVICE": "orders"},
    environment_registry={"stage": {"STAGE": "prod"}},
    role_registry={"api": execution_role},
    dynamodb_table_registry={"orders": orders_table},
)

An empty or whitespace-only key is rejected. A duplicate key raises ValueError. A missing reference raises KeyError naming the registry and key; incompatible authorizers additionally raise TypeError. Registering a DynamoDB table or S3 bucket only makes it resolvable: it grants no permissions. Permissions require @grant_dynamodb or @grant_s3.

There is no runtime_registry and no register_runtime. Reusing one config creates isolated mutable snapshots, so one LambdaApi build cannot add values to another snapshot.

Defaults and common values

set_default_runtime(runtime: Optional[lambda_.Runtime]) -> None
set_default_timeout(timeout: Optional[Duration]) -> None
set_default_memory_size(memory_size: Optional[int]) -> None
set_default_vpc(vpc: Optional[ec2.IVpc], vpc_subnets: Optional[ec2.SubnetSelection] = None) -> None
set_default_role(role: Optional[iam.IRole]) -> None
add_common_layer(layer: lambda_.ILayerVersion) -> None
add_common_security_group(security_group: ec2.ISecurityGroup) -> None

Common environment has no mutator: use common_environment= in the constructor. set_default_vpc preserves the VPC and subnet selection together. The default role selects one execution role for a Lambda; a Lambda never receives multiple execution roles.

Registry methods

Every register_* method rejects an empty key and duplicates with ValueError (and invalid key/value types with TypeError):

register_role(key: str, role: iam.IRole) -> None
register_environment(key: str, value: Mapping[str, str]) -> None
register_layer(key: str, layer: lambda_.ILayerVersion) -> None
register_security_group(key: str, security_group: ec2.ISecurityGroup) -> None
register_vpc(key: str, vpc: ec2.IVpc, vpc_subnets: Optional[ec2.SubnetSelection] = None) -> None
register_dynamodb_table(key: str, table: dynamodb.ITable) -> None
register_s3_bucket(key: str, bucket: s3.IBucket) -> None
register_authorizer(key: str, authorizer: object) -> None

register_vpc stores the (vpc, vpc_subnets) pair. register_authorizer accepts a CDK REST IAuthorizer or HTTP IHttpRouteAuthorizer. set_default_authorizer(key: Optional[str]) -> None selects or clears a previously registered authorizer; an unknown non-None key raises KeyError.

Precedence

Option	Default/common	Registry selection	Decorator	Effective value
Runtime	default_runtime	Built-in alias or custom runtime alias	@runtime("key")	Decorator alias, otherwise default
Role	default_role	role_registry	@role("key")	One selected role, otherwise default
Environment	common_environment	environment_registry	@environment("key")	Common map merged with selected map; selected keys win
VPC	vpc + vpc_subnets	vpc_registry	@vpc("key")	Selected VPC/subnet pair, otherwise default pair
Authorizer	default_authorizer	authorizer_registry	@authorizer("key") or @public	Selected authorizer, public, or default

Layers and security groups append selected registered objects to their common values. Timeout, memory size, name, and description are scalar values overridden by their decorators. Defaults that remain None are left for CDK to supply.

Override diagnostics

During one LambdaApi build, CDK emits at most one message per applicable category. The Authorization overrides, Execution role overrides, and VPC overrides tables contain stable, path-sorted METHOD/PATH rows and an EFFECTIVE value (VPC also shows SUBNETS). No table is emitted when that category has no overrides. There are deliberately no tables for runtime, timeout, memory, environment, layers, or security groups.

With no default authorizer, the builder emits one LAD_AUTH_PUBLIC_DEFAULT warning: routes without explicit authorization are public. With a default authorizer, that warning is absent; only explicit @public or a different @authorizer appears in the authorization table. If an explicit role with DynamoDB/S3 grants is shared by multiple handlers, one LAD_ROLE_SHARED_PERMISSIONS warning explains that the role accumulates the union of those permissions. Prefer independent roles when least privilege matters.