# Provider

Defines an AWS CloudFormation custom resource provider.

Extends: Construct › Provider
Implements: IConstruct, IDependable

- Source: [`custom-resources/lib/provider-framework/provider.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/custom-resources/lib/provider-framework/provider.ts#L195)
- Type last changed: v2.196.0 · 16 May 2025

## Example

```ts
// Create custom resource handler entrypoint
const handler = new lambda.Function(this , 'my-handler', {
  runtime: lambda.Runtime.NODEJS_20_X,
  handler: 'index.handler',
  code: lambda.Code.fromInline(`
  exports.handler = async (event, context) => {
    return {
      PhysicalResourceId: '1234',
      NoEcho: true,
      Data: {
        mySecret: 'secret-value',
        hello: 'world',
        ghToken: 'gho_xxxxxxx',
      },
    };
  };`),
});

// Provision a custom resource provider framework
const provider = new cr.Provider(this , 'my-provider', {
  onEventHandler: handler,
});

new CustomResource(this , 'my-cr', {
  serviceToken: provider.serviceToken,
});
```

## Initializer

```ts
new Provider(scope: Construct, id: string, props: ProviderProps)
```

## Construct Props

- `disableWaiterStateMachineLogging`: boolean = true — Whether logging for the waiter state machine is disabled.

- `frameworkCompleteAndTimeoutRole`: [IRole](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IRole.html) — Lambda execution role for provider framework's isComplete/onTimeout Lambda function.

  **Default:** A default role will be created.

  Note that this role
  must be assumed by the 'lambda.amazonaws.com' service principal. To prevent circular dependency problem
  in the provider framework, please ensure you specify a different IAM Role for 'frameworkCompleteAndTimeoutRole'
  from 'frameworkOnEventRole'.

  This property cannot be used with 'role' property

- `frameworkLambdaLoggingLevel`: [ApplicationLogLevel](/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.ApplicationLogLevel.html) — Log level of the provider framework lambda.

  **Default:** true - Logging is disabled by default

- `frameworkOnEventRole`: [IRole](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IRole.html) — Lambda execution role for provider framework's onEvent Lambda function.

  **Default:** A default role will be created.

  Note that this role must be assumed
  by the 'lambda.amazonaws.com' service principal.

  This property cannot be used with 'role' property

- `isCompleteHandler`: [IFunction](/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.IFunction.html) — The AWS Lambda function to invoke in order to determine if the operation is complete.

  **Default:** provider is synchronous. This means that the `onEvent` handler is expected to finish all lifecycle operations within the initial invocation.

  This function will be called immediately after `onEvent` and then
  periodically based on the configured query interval as long as it returns
  `false`. If the function still returns `false` and the alloted timeout has
  passed, the operation will fail.

- `logGroup`: [ILogGroupRef](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_logs.ILogGroupRef.html) — The Log Group used for logging of events emitted by the custom resource's lambda function.

  **Default:** a default log group created by AWS Lambda

  Providing a user-controlled log group was rolled out to commercial regions on 2023-11-16.
  If you are deploying to another type of region, please check regional availability first.

- `logRetention`: [RetentionDays](/cdk/api/v2/docs/aws-cdk-lib.aws_logs.RetentionDays.html) = logs.RetentionDays.INFINITE — The number of days framework log events are kept in CloudWatch Logs.

  When
  updating this property, unsetting it doesn't remove the log retention policy.
  To remove the retention policy, set the value to `INFINITE`.

  This is a legacy API and we strongly recommend you migrate to `logGroup` if you can.
  `logGroup` allows you to create a fully customizable log group and instruct the Lambda function to send logs to it.

- `onEventHandler`: [IFunction](/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.IFunction.html) (required) — The AWS Lambda function to invoke for all resource lifecycle operations (CREATE/UPDATE/DELETE).

  This function is responsible to begin the requested resource operation
  (CREATE/UPDATE/DELETE) and return any additional properties to add to the
  event, which will later be passed to `isComplete`. The `PhysicalResourceId`
  property must be included in the response.

- `providerFunctionEnvEncryption`: [IKeyRef](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_kms.IKeyRef.html) — AWS KMS key used to encrypt provider lambda's environment variables.

  **Default:** AWS Lambda creates and uses an AWS managed customer master key (CMK)

- `providerFunctionName`: string — Provider Lambda name.

  **Default:** CloudFormation default name from unique physical ID

  The provider lambda function name.

- `queryInterval`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) = Duration.seconds(5) — Time between calls to the `isComplete` handler which determines if the resource has been stabilized.

  The first `isComplete` will be called immediately after `handler` and then
  every `queryInterval` seconds, and until `timeout` has been reached or until
  `isComplete` returns `true`.

- `role`: [IRole](/cdk/api/v2/docs/aws-cdk-lib.aws_iam.IRole.html) — - Use frameworkOnEventRole, frameworkCompleteAndTimeoutRole

  **Default:** A default role will be created.

  The role is shared by provider framework's onEvent, isComplete lambda, and onTimeout Lambda functions.
  This role will be assumed by the AWS Lambda, so it must be assumable by the 'lambda.amazonaws.com'
  service principal.

- `securityGroups`: [ISecurityGroup](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.ISecurityGroup.html)[] — Security groups to attach to the provider functions.

  **Default:** If `vpc` is not supplied, no security groups are attached. Otherwise, a dedicated security group is created for each function.

  Only used if 'vpc' is supplied

- `totalTimeout`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) = Duration.minutes(30) — Total timeout for the entire operation.

  The maximum timeout is 1 hour (yes, it can exceed the AWS Lambda 15 minutes)

- `vpc`: [IVpc](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.IVpc.html) — The vpc to provision the lambda functions in.

  **Default:** functions are not provisioned inside a vpc.

- `vpcSubnets`: [SubnetSelection](/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.SubnetSelection.html) — Which subnets from the VPC to place the lambda functions in.

  **Default:** the Vpc default strategy if not specified

  Only used if 'vpc' is supplied. Note: internet access for Lambdas
  requires a NAT gateway, so picking Public subnets is not allowed.

- `waiterStateMachineLogOptions`: [LogOptions](/cdk/api/v2/docs/aws-cdk-lib.custom_resources.LogOptions.html) — Defines what execution history events of the waiter state machine are logged and where they are logged.

  **Default:** A default log group will be created if logging for the waiter state machine is enabled.

## Properties

- `isCompleteHandler`: [IFunction](/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.IFunction.html) — The user-defined AWS Lambda function which is invoked asynchronously in order to determine if the operation is complete.

- `node`: [Node](/cdk/api/v2/docs/constructs.Node.html) — The tree node.

- `onEventHandler`: [IFunction](/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.IFunction.html) — The user-defined AWS Lambda function which is invoked for all resource lifecycle operations (CREATE/UPDATE/DELETE).

- `PROPERTY_INJECTION_ID`: string (static) — Uniquely identifies this class.

- `serviceToken`: string — The service token to use in order to define custom resources that are backed by this provider.

## Methods

- `isConstruct(x: any): boolean` (static) — 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 object.

  **Returns:** true if `x` is an object created from a class which extends `Construct`.

- `toString(): string` — Returns a string representation of this construct.

- `with(...mixins: IMixin[]): IConstruct` — Applies one or more mixins to this construct.

  Mixins are applied in order. The list of constructs is captured at the
  start of the call, so constructs added by a mixin will not be visited.
  Use multiple `with()` calls if subsequent mixins should apply to added
  constructs.

  **Parameters**

  - `mixins` — The mixins to apply.

  **Returns:** This construct for chaining