@aws-cdk/custom-resources

  • Version 1.156.1
  • Published
  • 465 kB
  • 8 dependencies
  • Apache-2.0 license

Install

npm i @aws-cdk/custom-resources
yarn add @aws-cdk/custom-resources
pnpm add @aws-cdk/custom-resources

Overview

Constructs for implementing CDK custom resources

Index

Classes

class AwsCustomResource

class AwsCustomResource extends CoreConstruct implements iam.IGrantable {}
  • Defines a custom resource that is materialized using specific AWS API calls. These calls are created using a singleton Lambda function.

    Use this to bridge any gap that might exist in the CloudFormation Coverage. You can specify exactly which calls are invoked for the 'CREATE', 'UPDATE' and 'DELETE' life cycle events.

constructor

constructor(scope: Construct, id: string, props: AwsCustomResourceProps);

    property grantPrincipal

    readonly grantPrincipal: iam.IPrincipal;

      method getResponseField

      getResponseField: (dataPath: string) => string;
      • Returns response data for the AWS SDK call as string.

        Example for S3 / listBucket : 'Buckets.0.Name'

        Note that you cannot use this method if ignoreErrorCodesMatching is configured for any of the SDK calls. This is because in such a case, the response data might not exist, and will cause a CloudFormation deploy time error.

        Parameter dataPath

        the path to the data

      method getResponseFieldReference

      getResponseFieldReference: (dataPath: string) => cdk.Reference;
      • Returns response data for the AWS SDK call.

        Example for S3 / listBucket : 'Buckets.0.Name'

        Use Token.asXxx to encode the returned Reference as a specific type or use the convenience getDataString for string attributes.

        Note that you cannot use this method if ignoreErrorCodesMatching is configured for any of the SDK calls. This is because in such a case, the response data might not exist, and will cause a CloudFormation deploy time error.

        Parameter dataPath

        the path to the data

      class AwsCustomResourcePolicy

      class AwsCustomResourcePolicy {}
      • The IAM Policy that will be applied to the different calls.

      property ANY_RESOURCE

      static readonly ANY_RESOURCE: string[];
      • Use this constant to configure access to any resource.

      property resources

      readonly resources?: string[];

        property statements

        readonly statements: iam.PolicyStatement[];

          method fromSdkCalls

          static fromSdkCalls: (options: SdkCallsPolicyOptions) => AwsCustomResourcePolicy;
          • Generate IAM Policy Statements from the configured SDK calls.

            Each SDK call with be translated to an IAM Policy Statement in the form of: call.service:call.action (e.g s3:PutObject).

            This policy generator assumes the IAM policy name has the same name as the API call. This is true in 99% of cases, but there are exceptions (for example, S3's PutBucketLifecycleConfiguration requires s3:PutLifecycleConfiguration permissions, Lambda's Invoke requires lambda:InvokeFunction permissions). Use fromStatements if you want to do a call that requires different IAM action names.

            Parameter options

            options for the policy generation

          method fromStatements

          static fromStatements: (
          statements: iam.PolicyStatement[]
          ) => AwsCustomResourcePolicy;
          • Explicit IAM Policy Statements.

            Parameter statements

            the statements to propagate to the SDK calls.

          class PhysicalResourceId

          class PhysicalResourceId {}
          • Physical ID of the custom resource.

          property id

          readonly id?: string;

            property responsePath

            readonly responsePath?: string;

              method fromResponse

              static fromResponse: (responsePath: string) => PhysicalResourceId;
              • Extract the physical resource id from the path (dot notation) to the data in the API call response.

              method of

              static of: (id: string) => PhysicalResourceId;
              • Explicit physical resource id.

              class PhysicalResourceIdReference

              class PhysicalResourceIdReference implements cdk.IResolvable {}
              • Reference to the physical resource id that can be passed to the AWS operation as a parameter.

              property creationStack

              readonly creationStack: string[];

                method resolve

                resolve: (_: cdk.IResolveContext) => any;

                  method toJSON

                  toJSON: () => string;
                  • toJSON serialization to replace PhysicalResourceIdReference with a magic string.

                  method toString

                  toString: () => string;

                    class Provider

                    class Provider extends CoreConstruct implements ICustomResourceProvider {}
                    • Defines an AWS CloudFormation custom resource provider.

                    constructor

                    constructor(scope: Construct, id: string, props: ProviderProps);

                      property isCompleteHandler

                      readonly isCompleteHandler?: lambda.IFunction;
                      • The user-defined AWS Lambda function which is invoked asynchronously in order to determine if the operation is complete.

                      property onEventHandler

                      readonly onEventHandler: lambda.IFunction;
                      • The user-defined AWS Lambda function which is invoked for all resource lifecycle operations (CREATE/UPDATE/DELETE).

                      property serviceToken

                      readonly serviceToken: string;
                      • The service token to use in order to define custom resources that are backed by this provider.

                      method bind

                      bind: (_scope: CoreConstruct) => CustomResourceProviderConfig;
                      • Called by CustomResource which uses this provider.

                        Deprecated

                        use provider.serviceToken instead

                      Interfaces

                      interface AwsCustomResourceProps

                      interface AwsCustomResourceProps {}
                      • Properties for AwsCustomResource.

                        Note that at least onCreate, onUpdate or onDelete must be specified.

                      property functionName

                      readonly functionName?: string;
                      • A name for the singleton Lambda function implementing this custom resource. The function name will remain the same after the first AwsCustomResource is created in a stack.

                        - AWS CloudFormation generates a unique physical ID and uses that ID for the function's name. For more information, see Name Type.

                      property installLatestAwsSdk

                      readonly installLatestAwsSdk?: boolean;
                      • Whether to install the latest AWS SDK v2. Allows to use the latest API calls documented at https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/index.html.

                        The installation takes around 60 seconds.

                        true

                      property logRetention

                      readonly logRetention?: logs.RetentionDays;
                      • The number of days log events of the singleton Lambda function implementing this custom resource are kept in CloudWatch Logs.

                        logs.RetentionDays.INFINITE

                      property onCreate

                      readonly onCreate?: AwsSdkCall;
                      • The AWS SDK call to make when the resource is created.

                        - the call when the resource is updated

                      property onDelete

                      readonly onDelete?: AwsSdkCall;
                      • The AWS SDK call to make when the resource is deleted

                        - no call

                      property onUpdate

                      readonly onUpdate?: AwsSdkCall;
                      • The AWS SDK call to make when the resource is updated

                        - no call

                      property policy

                      readonly policy: AwsCustomResourcePolicy;
                      • The policy that will be added to the execution role of the Lambda function implementing this custom resource provider.

                        The custom resource also implements iam.IGrantable, making it possible to use the grantXxx() methods.

                        As this custom resource uses a singleton Lambda function, it's important to note the that function's role will eventually accumulate the permissions/grants from all resources.

                        See Also

                        • Policy.fromStatements

                        • Policy.fromSdkCalls

                      property resourceType

                      readonly resourceType?: string;
                      • Cloudformation Resource type.

                        - Custom::AWS

                      property role

                      readonly role?: iam.IRole;
                      • The execution role for the singleton Lambda function implementing this custom resource provider. This role will apply to all AwsCustomResource instances in the stack. The role must be assumable by the lambda.amazonaws.com service principal.

                        - a new role is created

                      property timeout

                      readonly timeout?: cdk.Duration;
                      • The timeout for the singleton Lambda function implementing this custom resource.

                        Duration.minutes(2)

                      interface AwsSdkCall

                      interface AwsSdkCall {}
                      • An AWS SDK call.

                      property action

                      readonly action: string;
                      • The service action to call

                        See Also

                        • https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/index.html

                      property apiVersion

                      readonly apiVersion?: string;
                      • API version to use for the service

                        See Also

                        • https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/locking-api-versions.html - use latest available API version

                      property assumedRoleArn

                      readonly assumedRoleArn?: string;
                      • Used for running the SDK calls in underlying lambda with a different role Can be used primarily for cross-account requests to for example connect hostedzone with a shared vpc

                        Example for Route53 / associateVPCWithHostedZone

                        - run without assuming role

                      property ignoreErrorCodesMatching

                      readonly ignoreErrorCodesMatching?: string;
                      • The regex pattern to use to catch API errors. The code property of the Error object will be tested against this pattern. If there is a match an error will not be thrown.

                        - do not catch errors

                      property outputPath

                      readonly outputPath?: string;
                      • Restrict the data returned by the custom resource to a specific path in the API response. Use this to limit the data returned by the custom resource if working with API calls that could potentially result in custom response objects exceeding the hard limit of 4096 bytes.

                        Example for ECS / updateService: 'service.deploymentConfiguration.maximumPercent'

                        - return all data

                        Deprecated

                        use outputPaths instead

                      property outputPaths

                      readonly outputPaths?: string[];
                      • Restrict the data returned by the custom resource to specific paths in the API response. Use this to limit the data returned by the custom resource if working with API calls that could potentially result in custom response objects exceeding the hard limit of 4096 bytes.

                        Example for ECS / updateService: ['service.deploymentConfiguration.maximumPercent']

                        - return all data

                      property parameters

                      readonly parameters?: any;
                      • The parameters for the service action

                        - no parameters

                        See Also

                        • https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/index.html

                      property physicalResourceId

                      readonly physicalResourceId?: PhysicalResourceId;
                      • The physical resource id of the custom resource for this call. Mandatory for onCreate or onUpdate calls.

                        - no physical resource id

                      property region

                      readonly region?: string;
                      • The region to send service requests to. **Note: Cross-region operations are generally considered an anti-pattern.** **Consider first deploying a stack in that region.**

                        - the region where this custom resource is deployed

                      property service

                      readonly service: string;
                      • The service to call

                        See Also

                        • https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/index.html

                      interface ProviderProps

                      interface ProviderProps {}
                      • Initialization properties for the Provider construct.

                      property isCompleteHandler

                      readonly isCompleteHandler?: lambda.IFunction;
                      • The AWS Lambda function to invoke in order to determine if the operation is complete.

                        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.

                        - provider is synchronous. This means that the onEvent handler is expected to finish all lifecycle operations within the initial invocation.

                      property logRetention

                      readonly logRetention?: logs.RetentionDays;
                      • 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.

                        logs.RetentionDays.INFINITE

                      property onEventHandler

                      readonly onEventHandler: lambda.IFunction;
                      • 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.

                      property providerFunctionName

                      readonly providerFunctionName?: string;
                      • Provider Lambda name.

                        The provider lambda function name.

                        - CloudFormation default name from unique physical ID

                      property queryInterval

                      readonly queryInterval?: Duration;
                      • 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.

                        Duration.seconds(5)

                      property role

                      readonly role?: iam.IRole;
                      • AWS Lambda execution role.

                        The role that will be assumed by the AWS Lambda. Must be assumable by the 'lambda.amazonaws.com' service principal.

                        - A default role will be created.

                      property securityGroups

                      readonly securityGroups?: ec2.ISecurityGroup[];
                      • Security groups to attach to the provider functions.

                        Only used if 'vpc' is supplied

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

                      property totalTimeout

                      readonly totalTimeout?: Duration;
                      • Total timeout for the entire operation.

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

                        Duration.minutes(30)

                      property vpc

                      readonly vpc?: ec2.IVpc;
                      • The vpc to provision the lambda functions in.

                        - functions are not provisioned inside a vpc.

                      property vpcSubnets

                      readonly vpcSubnets?: ec2.SubnetSelection;
                      • Which subnets from the VPC to place the lambda functions in.

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

                        - the Vpc default strategy if not specified

                      interface SdkCallsPolicyOptions

                      interface SdkCallsPolicyOptions {}
                      • Options for the auto-generation of policies based on the configured SDK calls.

                      property resources

                      readonly resources: string[];
                      • The resources that the calls will have access to.

                        It is best to use specific resource ARN's when possible. However, you can also use AwsCustomResourcePolicy.ANY_RESOURCE to allow access to all resources. For example, when onCreate is used to create a resource which you don't know the physical name of in advance.

                        Note that will apply to ALL SDK calls.

                      Type Aliases

                      type AwsSdkMetadata

                      type AwsSdkMetadata = {
                      [key: string]: any;
                      };
                      • AWS SDK service metadata.

                      Package Files (3)

                      Dependencies (8)

                      Dev Dependencies (17)

                      Peer Dependencies (8)

                      Badge

                      To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                      You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@aws-cdk/custom-resources.

                      • Markdown
                        [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@aws-cdk/custom-resources)
                      • HTML
                        <a href="https://www.jsdocs.io/package/@aws-cdk/custom-resources"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>