Custom resources let you embed custom logic in ROS templates. ROS runs this logic when you create, update, or delete a stack. Use custom resources to manage resource types that ROS does not natively support, so you can keep all resources in a single stack.
About custom resources
Define a custom resource in a template by using the ALIYUN::ROS::CustomResource or Custom::MyCustomResourceTypeName resource type. Each custom resource requires a service token that specifies where ROS sends requests, such as SMQ (Simple Message Queue (formerly MNS)) topics and queues, Function Compute (FC) functions, or HTTP and HTTPS services.
The custom resource must send a response to a pre-signed URL. If no response is sent, the stack operation fails. Use `ResponseURL` to respond over the public network and `IntranetResponseURL` to respond over the Alibaba Cloud internal network.
How custom resources work
Custom resource operations involve three entities:
-
Template developer: Creates the template that contains the custom resource type, the service token, and input data.
-
Custom resource provider: Owns the custom resource, determines how to handle and respond to ROS requests, and supplies the service token for the template developer.
-
ROS: Sends a request to the service token specified in the template during a stack operation, then waits for a response before proceeding.
The template developer and the custom resource provider can be the same person or entity. The custom resource workflow:
-
The template developer defines the custom resource in a template with the required service token and optional input data parameters.
The service token specifies where ROS sends the request, such as an MNS topic Alibaba Cloud Resource Name (ARN) or an FC function ARN, as defined in ALIYUN::ROS::CustomResource. The custom resource provider defines the service token structure and input data.
-
When you create, update, or delete a custom resource, ROS sends a request to the specified service token. Service tokens are not region-restricted.
The ROS request includes the request type, the pre-signed response URL, and other metadata described in Custom resource request objects.
Example request:
{ "RequestType" : "Create", "RequestId" : "unique id for this create request", "ResponseURL" : "pre-signed-url-for-create-response", "IntranetResponseURL" : "pre-signed-intranet-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` JSON response to the pre-signed URL.
The response can include output data on success or an error message on failure, as described in Custom resource response objects.
The provider must listen for and respond to the request. For example, an MNS-based provider listens on the specified topic ARN. ROS waits for a response at the pre-signed URL.
Example 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 ROS receives a `SUCCESS` response, it continues the stack operation. A `FAILED` response or no response causes the operation to fail. The template developer can retrieve output data from the response by using the `Fn::GetAtt` function.