AwsApiCustomResource - A better AwsCustomResource

[michanto]

AwsCustomResource makes it possible to construct a custom resource simply by specifying a AwsSdkCall - any AWS SDK operation in any service. This makes it possible for users to onboard any AWS service to CloudFormation themselves. It's a great way to create custom resources – if the API you are using can fit into that model. Other call patterns, such as Lambda, REST, ApiGateway, StepFunctions, and custom call patterns are not well supported.

AwsApiCustomResource makes it possible to use other call patterns and support a wider set of AWS calls than can currently be used with AwsCustomResource. This enables end users to onboard their own or others services, APIs and Lambdas to CloudFormation in a piecemeal fashion, without having to develop a CloudFormation service provider.

export interface AwsApiCall extends AwsSdkCall { 
   /**
    * Fills in the outputPaths automatically based on requested attributes (those retrieved
    * by getResponeField/Reference). This automatically limits the response to just what
    * is used.  If the user specified outputPaths, then the requested outputPaths will be
    * added to the given list.
    */
   readonly boolean includeRequestedOutputPaths 

  /** 
   * Specifies a field in the API response that should be deserlized, such as 
   * Payload when calling lambda:Invoke, or Body when calling s3:GetObject. 
   * The response data will only contain fields from the deserialized object.
   */ 
  readonly responseBufferField?: string 

  /** Specifies which return field has the status for isComplete calls.  */ 
  readonly statusField?: string
  /** Specifies which return field has the failure cause (if any). */
  readonly causeField?: string 

  /** Specifies succeeded values for statusField */ 
  readonly successStatusValues?: string[] 
  /** Specifies failed values for statusField */ 
  readonly failedStatusValues?: string[] 
  /** Specifies running/in progress values for statusField */ 
  readonly runningStatusValues?: string[] 

  /** 
   * Default attribute values to use when the underlying API fails to return expected 
   * response fields.  This allows the user to call getResponseField/Reference
   * when specifying ignoreErrorCodesMatching. 
   */ 
  readonly defaultDataValues?: Record<string, string> 
} 

/** 
 * Properties for AwsApiCustomResource. 
 */ 
export interface AwsApiCustomResourceProps extends AwsCustomResourceProps { 
  /** Properties from AwsCustomResource are replaced by these */ 
  readonly onCreate?: AwsApiCall; 

  readonly onUpdate?: AwsApiCall; 

  readonly onDelete?: AwsApiCall; 

  /** Enables provider-like functionality for longer operations called from AwsApiCustomResource **/ 
  readonly onCreateIsComplete?: AwsApiCall; 

  readonly onUpdateIsComplete?: AwsApiCall; 

  readonly onDeleteIsComplete?: AwsApiCall; 

  /** 
   * Whether to run the resource every time the stack is rebuilt.  Adds a timestamp to the resource properties.
   */ 
  readonly runAlways?: boolean 
} 

 /** Allows an onEventIsComplete function to access an attribute returned as data from an onEvent
  *(onCreate/onUpdate/onDelete) call.  Reference this from the properties passed to the 
  * onEventIsComplete AwsApiCall
  */
export class OnEventDataField { 
  /* Returns a field from the onEvent call.  Can only be used in onEventIsComplete call properties. */ 
  static get(name: string): any 
} 

The runtime for AwsApiCustomResource should be public and easily customizable by the user, allowing at least the abitly to replace the API invoker and the response filter.

[hoegertn]

Hi, could you please provide an example of how and when to use this? I am not sure I get the use case.

[michanto]

For now this will move over to the cdk-orchestration package.