Custom resources let you embed custom configuration logic in Resource Orchestration Service (ROS) templates, extending your stacks to include resources beyond the built-in ROS resource types.
ROS runs custom resource logic whenever you create, update (if you have modified the custom resources), or delete a stack. For example, if a resource type is not natively supported by ROS, you can define it as a custom resource and still manage it alongside other resources in the same stack.
To define a custom resource, use the ALIYUN::ROS::CustomResource or Custom::MyCustomResourceTypeName resource type in your template. Each custom resource requires a service token property that tells ROS where to send requests. The service token can be a Message Service (MNS) topic or queue, a Function Compute function, or an HTTP or HTTPS URL.
Custom resources must send responses to presigned response URLs. If a custom resource cannot respond, the stack operation fails. Use ResponseURL for Internet access and InnerResponseURL for the Alibaba Cloud internal network.
How custom resources work
Custom resource operations involve three parties:
- template developer
- Creates a template that includes a custom resource type, specifying the service token and all input data.
- custom resource provider
- Owns the custom resource and determines how to handle and respond to requests from ROS. The provider must supply a service token to the template developer.
- ROS
- Sends a request to the service token specified in the template during a stack operation and waits for a response before proceeding.
- The template developer defines a custom resource in a template that contains a service token and optional input data parameters. The service token is always required.
The service token specifies where ROS sends requests, such as an MNS topic ARN or a Function Compute function ARN. For more information, see ALIYUN::ROS::CustomResource. The service token and input data structure are defined by the custom resource provider.
- When a stack operation creates, updates, or deletes a custom resource, ROS sends a request to the specified service token. The service token can be in any region.
The request includes the request type and a presigned URL for the response. For more information, see Custom resource request objects.
The following sample shows a ROS request:
{ "RequestType" : "Create", "RequestId" : "unique id for this create request", "ResponseURL" : "pre-signed-url-for-create-response", "InnerResponseURL" : "pre-signed-inner-url-for-create-response", "ResourceType" : "Custom::MyCustomResourceType", "LogicalResourceId" : "name of resource in template", "StackId" : "stack id", "StackName" : "stack name", "ResourceOwnerId": "resource owner id", "CallerId": "caller id", "RegionId": "region id", "ResourceProperties" : { "key1" : "string", "key2" : [ "list" ], "key3" : { "key4" : "map" } } } - The custom resource provider processes the request and returns a SUCCESS or FAILED response to the presigned URL. The response contains JSON-formatted data.
The response can include name-value pairs accessible to the template developer. For example, it can contain output data on success or an error message on failure. For more information, see Custom resource response objects.
The custom resource provider must listen for and respond to requests. For example, it must handle MNS topic notifications sent to a specific topic ARN. ROS waits for the response at the presigned URL.
The following sample shows a custom resource response:
{ "Status" : "SUCCESS", "RequestId" : "unique id for this create request (copied from request)", "LogicalResourceId" : "name of resource in template (copied from request)", "StackId" : "stack id (copied from request)", "PhysicalResourceId" : "required vendor-defined physical id that is unique for that vendor", "Data" : { "keyThatCanBeUsedInGetAtt1" : "data for key 1", "keyThatCanBeUsedInGetAtt2" : "data for key 2" } } - After receiving a SUCCESS response, ROS proceeds with the stack operation. A FAILED response or no response causes the operation to fail. Output data from the custom resource is stored at the presigned URL and can be retrieved by the template developer by using the Fn::GetAtt function.