@aws-cdk/custom-resources
- Version 1.204.0
- Published
- 459 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
Interfaces
Type Aliases
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 returnedReference
as a specific type or use the conveniencegetDataString
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.gs3: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
requiress3:PutLifecycleConfiguration
permissions, Lambda'sInvoke
requireslambda:InvokeFunction
permissions). UsefromStatements
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 thegrantXxx()
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 thelambda.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 theError
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 returnsfalse
. If the function still returnsfalse
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
. ThePhysicalResourceId
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 afterhandler
and then everyqueryInterval
seconds, and untiltimeout
has been reached or untilisComplete
returnstrue
.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, whenonCreate
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 oneto 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[](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>
- Updated .
Package analyzed in 1858 ms. - Missing or incorrect documentation? Open an issue for this package.