ALIYUN::ROS::CustomResource is used to create a custom resource.

In an ROS template, you can use the ALIYUN::ROS::CustomResource or Custom::String resource type to specify custom resources.

Custom resources provide a way for you to write custom provisioning logic in an ROS template and have ROS run the logic during a stack operation, such as when you create, update, or delete a stack. For more information, see Overview.

Custom resources must send responses to a presigned URL. If they cannot send responses to ROS, ROS will not receive a response and the stack operation fails. ResponseURL is used in the Internet and InnerResponseURL is used in the internal network of Alibaba Cloud.

Syntax

{
  "Type": "ALIYUN::ROS::CustomResource",
  "Properties": {
    "ServiceToken": String,
    "Timeout": Number,
    "Parameters": Map
  }
}

Properties

Property Type Required Editable Description Constraint
ServiceToken String Yes No The service token that is supplied by the service provider to the template developer to access the service.

The service token can be a Function Compute function, an MNS topic, an MNS queue, or an HTTP or HTTPS URL.

It can be up to 512 characters in length.

 Valid values:
  • Function Compute function: acs:fc:<region_id>:<account_id>:services/<service_name>/functions/<function_name>
  • MNS queue: acs:mns:<region_id>:<account_id>:queues/<queue_name>
  • MNS topic: acs:mns:<region_id>:<account_id>:topics/<topic_name>
  • HTTP or HTTPS URL: web[options]:<url>

    options is an optional parameter that can be set to sync and/or idempotent. When the preceding two values are combined, you must separate them with a comma (,).

    sync indicates that the request is a synchronous request. This means that you can directly use the response of the request instead of waiting for the presigned URL callback. By default, the request is an asynchronous request and you must wait for the presigned URL callback.

    idempotent indicates that the request for creating resources is idempotent. If a network exception occurs or a 500 error code is returned, the request is retried. By default, the request for creating resources is not idempotent. Requests for updating and deleting resources must always be idempotent.

Example:

  • acs:fc:cn-hangzhou:123456789:services/test-service/functions/test-function
  • acs:mns:cn-hangzhou:123456789:queues/test-queue
  • acs:mns:cn-hangzhou:123456789:topics/test-topic
  • web:https://example.com
  • web[sync]:http://example.com
  • web[sync,idempotent]:https://example.com
Timeout Number Yes Yes The timeout period for ROS to wait for responses from the custom service provider. Unit: seconds.
  • When ServiceToken is used to make an asynchronous HTTP or HTTPS request or access a Function Compute function, MNS topic, or MNS queue, Timeout is set to 60 by default. Valid values of this parameter are 1 to 43200.
  • When ServiceToken is used to make a synchronous HTTP or HTTPS request, the timeout period is 10 seconds and the Timeout parameter is ignored.
Parameters Map No Yes The parameters to be passed to the custom service provider. The property must be specified based on specifications provided by the custom service provider. None.

Response parameters

Fn::GetAtt

  • Outputs: the data received from the custom service provider. The data is an object in the map format.
  • *: uses the key in Outputs as the specific value.

Examples

  • YAMLformat

    ROSTemplateFormatVersion: '2015-09-01'
Resources:
  CustomResource:
    Type: ALIYUN::ROS::CustomResource
    Properties:
      ServiceToken: acs:fc:cn-hangzhou:123456789:services/test-service/functions/test-function
      Parameters:
        Key1: Value1
        Key2: Value2
      Timeout: 60
Parameters:
  Parameters:
    Type: Json
    Description: Parameters to be passed to service provider.
Outputs:
  Outputs:
    Description: Output data received from service provider.
    Value:
      Fn::GetAtt:
        - CustomResource
        - Outputs

  • JSONformat

    {
  "ROSTemplateFormatVersion": "2015-09-01",
  "Resources": {
    "CustomResource": {
      "Type": "ALIYUN::ROS::CustomResource",
      "Properties": {
        "ServiceToken": "acs:fc:cn-hangzhou:123456789:services/test-service/functions/test-function",
        "Parameters": {
          "Key1": "Value1",
          "Key2": "Value2"
        },
        "Timeout": 60
      }
    }
  },
  "Parameters": {
    "Parameters": {
      "Type": "Json",
      "Description": "Parameters to be passed to service provider."
    }
  },
  "Outputs": {
    "Outputs": {
      "Description": "Output data received from service provider.",
      "Value": {
        "Fn::GetAtt": [
          "CustomResource",
          "Outputs"
        ]
      }
    }
  }
}

Remarks

  • Specify a name for a custom resource type

    You can specify ALIYUN::ROS::CustomResource as the resource type of your custom resource or you can customize a resource type name. For example, you can use ALIYUN::ROS::CustomResource instead of Custom::MyCustomResourceTypeName.

    The name of a custom resource type can contain letters, digits, underscores (_), at signs (@), and hyphens (-). The name can be up to 68 characters in length. The resource type cannot be changed during a stack update.

    You can use your own resource type names to differentiate the types of custom resources in your stack. For example, if you have two custom resources that perform two different ping tests, you can name their resource type as Custom::PingTester instead of ALIYUN::ROS::CustomResource to identify them as ping testers.

  • Replace custom resources during a stack update

    ROS does not allow you to change physical resource IDs of resources during a stack update.

  • Retrieve return values

    For custom resources, return values are provided by the custom service provider and can be retrieved by calling Fn::GetAtt on the provider-defined attributes.