AwsServerless

Service-level serverless component for Lambda-centric workloads.

Remarks

Naming:

• Root: type ${namespace}:aws:AwsServerless; capability serverless; logical-only identity args.identity; ${env}-${projectHash}-serverless-${sanitiseNamePart(args.identity)}; punctuation-only identities are rejected by the shared builder.
• Direct aws:iam/rolePolicy:RolePolicy children use [args.identity, args.functions.<key>]; direct aws:cloudwatch/metricAlarm:MetricAlarm children use [args.identity, args.functions.<key>, 'errors' | 'throttles']. Both groups run a full collision preflight before provider resources are created.
• Direct aws:route53/record:Record children use [args.identity]. REST and HTTP capabilities are mutually exclusive, so a single -custom-domain-alias-record child name is used. Record names are semantic DNS identifiers from route53AliasRecord.recordName ?? customDomain.domainName, forwarded unchanged; AWS owns DNS validation.
• Each args.functions map key is a camelCase alphanumeric purpose; it is passed through unchanged as the <functionKey> purpose of the composed resources. A single managed AwsCloudwatch log group may instead use args.observability.logGroup.name; this is a shared purpose input and is forwarded unchanged after rejecting surrounding whitespace.
• Provider-composed AwsIamRole, AwsLambda, AwsCloudwatch, AwsAcm, and AwsApiGateway own their component/resource naming. Their inputs retain their established provider-name bytes: function keys supply the Lambda/IAM/log-group purpose; ACM uses its domain input; API Gateway receives its own identity from the selected API capability. Serverless does not rewrite their child identities.
• Each args.layers.<key> composes an AwsLambda root with type ${namespace}:aws:AwsLambda, capability lambda-layer, and identity args.layers.<key>, producing ${env}-${projectHash}-lambda-layer-${sanitiseNamePart(args.layers.<key>)}. The composed facade owns its direct aws:lambda/layerVersion:LayerVersion child using tuple [args.layers.<key>].
• REST routes are keyed by raw <METHOD> <path> strings and HTTP routes by raw route keys. These keys are forwarded byte-for-byte to AwsApiGateway; the <functionKey> selects only the Lambda integration target. A REST route is a record such as { 'GET /health': { functionKey: 'api' } }; each HTTP route is a record keyed by its raw route key. HTTP authorizers are keyed maps such as { jwt: { type: 'JWT', ... } }. Both capabilities require their own logical-only identity, so independent API roots remain stable; each supplies its API input identity ${env}-${projectHash}-apigateway-${sanitiseNamePart(args.apiGatewayRest.identity | args.apiGatewayHttp.identity)}.
• CloudWatch alarms fold the alarm kind into the purpose (no extra hyphen segment) through buildAwsNameFromCamelCasePurpose('stackAndPurpose', ...): ${env}-${projectHash}-<functionKey>Errors and ${env}-${projectHash}-<functionKey>Throttles. CloudWatch permits 255-character names, so the final qualified purpose has a 242-character budget, while the composed IAM execution role limits the raw function key to 44 characters. Route53 alias records use their semantic DNS name.

Example

const service = new AwsServerless({
  identity: 'orders-api',
  functions: {
    api: {
      executionRolePolicy: {
        path: 'policies/lambda-execution-policy.json',
        variables: {
          parameterArn: 'arn:aws:ssm:eu-west-1:000000000000:parameter/orders/config',
        },
      },
      codePath: './dist/lambda',
      handler: 'index.handler',
      runtime: 'nodejs22.x',
    },
  },
  apiGatewayRest: {
    identity: 'orders-rest-api',
    customDomain: {
      domainName: 'api.orders.example.com',
      endpointType: 'REGIONAL',
      certificateSettings: {
        subjectAlternativeNames: ['orders.example.com'],
      },
      route53AliasRecord: {
        hostedZoneName: 'orders.example.com',
      },
    },
    routes: { 'GET /health': { functionKey: 'api' } },
  },
});

Constructors

new AwsServerless( args: AwsServerlessArgs, options?: ComponentResourceOptions, ): AwsServerless

Parameters

• args (AwsServerlessArgs) — Component inputs for Lambda core plus optional API, URL, and observability capabilities.
• options (ComponentResourceOptions, optional) — Optional settings controlling resource behaviour.

Returns

AwsServerless

Hierarchy

• ComponentResource
• AwsServerless

Properties

apiGateway: AwsApiGateway | undefined

Optional managed API Gateway component.

apiInvokeUrl: Output<string> | undefined

Optional API invoke URL for the configured API Gateway capability.

customDomainCertificate: AwsAcm | undefined

Optional ACM component created for API Gateway custom-domain certificate orchestration.

customDomainCertificateArn: Output<string> | undefined

Optional effective ACM certificate ARN used by API Gateway custom-domain configuration.

customDomainName: Output<string> | undefined

Optional REST custom-domain name.

customDomainRecordFqdn: Output<string> | undefined

Optional Route53 alias record FQDN for the REST custom domain.

customDomainTargetDomainName: Output<string> | undefined

Optional API Gateway custom-domain target DNS name.

customDomainTargetZoneId: Output<string> | undefined

Optional API Gateway custom-domain target hosted-zone ID.

errorsAlarm: MetricAlarm | undefined

Optional baseline Lambda errors alarm.

errorsAlarms: Record<string, aws.cloudwatch.MetricAlarm | undefined>

Optional baseline Lambda errors alarms keyed by function key.

executionRole: Role

Managed execution role used by the Lambda function.

executionRoles: Record<string, aws.iam.Role>

Managed execution roles keyed by function key.

function: Function

Managed Lambda function resource.

functionArn: Output<string>

Lambda function ARN.

functionArns: Record<string, pulumi.Output<string>>

Lambda function ARNs keyed by function key.

functionName: Output<string>

Effective Lambda function name.

functionNames: Record<string, pulumi.Output<string>>

Effective Lambda function names keyed by function key.

functions: Record<string, aws.lambda.Function>

Managed Lambda function resources keyed by function key.

functionUrl: Output<string> | undefined

Optional Lambda Function URL endpoint.

functionUrlResource: FunctionUrl | undefined

Optional managed Lambda Function URL resource.

functionUrlResources: Record<string, aws.lambda.FunctionUrl | undefined>

Optional managed Lambda Function URL resources keyed by function key.

functionUrls: Record<string, pulumi.Output<string> | undefined>

Optional Lambda Function URL endpoints keyed by function key.

lambda: AwsLambda

Managed Lambda component.

lambdaLayers: Record<string, AwsLambda>

Managed Lambda components keyed by layer key.

lambdas: Record<string, AwsLambda>

Managed Lambda components keyed by function key.

layers: Record<string, aws.lambda.LayerVersion>

Managed Lambda layer versions keyed by layer key.

layerVersionArns: Record<string, pulumi.Output<string>>

Managed versioned Lambda layer ARNs keyed by layer key.

logGroup: AwsCloudwatch | undefined

Optional CloudWatch log-group component managed by AwsServerless. External per-function references are not returned here.

logGroupName: Output<string> | undefined

Optional effective CloudWatch log-group name.

logGroupNames: Record<string, pulumi.Output<string> | undefined>

Optional effective CloudWatch log-group names keyed by function key.

logGroups: Record<string, AwsCloudwatch | undefined>

Optional CloudWatch log-group components managed by AwsServerless, keyed by function key. External per-function references are not returned here.

restApiInvokeUrl: Output<string> | undefined

Optional REST API invoke URL.

roleArn: Output<string>

Effective execution role ARN.

roleArns: Record<string, pulumi.Output<string>>

Effective execution role ARNs keyed by function key.

throttlesAlarm: MetricAlarm | undefined

Optional baseline Lambda throttles alarm.

throttlesAlarms: Record<string, aws.cloudwatch.MetricAlarm | undefined>

Optional baseline Lambda throttles alarms keyed by function key.

urn: Output<string>

Inherited from urn

The stable logical URN used to distinctly address a resource, both before and after deployments.

Methods

getData(): Promise<any>

Inherited from getData

Retrieves the data produces by initialize. The data is immediately available in a derived class's constructor after the super(...) call to ComponentResource.

Returns

• Promise<any>

getProvider(moduleMember: string): ProviderResource | undefined

Inherited from getProvider

Returns the provider for the given module member, if one exists.

Parameters

• moduleMember (string)

Returns

• ProviderResource | undefined

initialize( args: Inputs, opts?: ComponentResourceOptions, name?: string, type?: string, ): Promise<any>

Inherited from initialize

Can be overridden by a subclass to asynchronously initialize data for this component automatically when constructed. The data will be available immediately for subclass constructors to use. To access the data use getData.

Parameters

• args (Inputs)
• opts (ComponentResourceOptions, optional)
• name (string, optional)
• type (string, optional)

Returns

• Promise<any>

registerOutputs( outputs?: Inputs | Promise<Inputs> | Output<Inputs>, ): void

Inherited from registerOutputs

Registers synthetic outputs that a component has initialized, usually by allocating other child sub-resources and propagating their resulting property values.

Component resources can call this at the end of their constructor to indicate that they are done creating child resources. This is not strictly necessary as this will automatically be called after the initialize method completes.

Parameters

• outputs (Inputs | Promise<Inputs> | Output<Inputs>, optional)

Returns

• void

Static Methods

isInstance(obj: any): obj is ComponentResource<any>

Inherited from isInstance

Returns true if the given object is a CustomResource. This is designed to work even when multiple copies of the Pulumi SDK have been loaded into the same process.

Parameters

• obj (any)

Returns

• obj is ComponentResource<any>