Use ALIYUN::ApiGateway::PluginAttachment to attach a plug-in to an API - Resource Orchestration Service

ALIYUN::ApiGateway::PluginAttachment is used to bind a plug-in to an API.

Syntax

{
  "Type": "ALIYUN::ApiGateway::PluginAttachment",
  "Properties": {
    "StageName": String,
    "PluginId": String,
    "ApiId": String
  }
}

Properties

Property Name	Type	Required	Allow Updates	Description	Constraint
ApiId	String	Yes	No	The ID of the API.	None.
PluginId	String	Yes	No	The ID of the plug-in.	None.
StageName	String	Yes	No	The API operation environment.	Valid values: RELEASE: release environment PRE: pre-release environment TEST: test environment

Return values

Fn::GetAtt

PluginId: the ID of the plug-in.
ApiId: the ID of the API.

Examples

Scenario 1: Attach a plug-in to an existing API

YAML

ROSTemplateFormatVersion: '2015-09-01'
Parameters:
  ApiId:
    Description: The ID of the API to which you want to bind the plug-in.
    Type: String
  PluginId:
    Description: The ID of the plugin that you want to bind.
    Type: String
  StageName:
    AllowedValues:
    - RELEASE
    - PRE
    - TEST
    Description: "The name of the runtime environment. Valid values: \nRELEASE: indicates\
      \ the release environment.\nPRE: indicates the pre-release environment.\nTEST:\
      \ indicates the test environment."
    Type: String
Resources:
  PluginAttachment:
    Properties:
      ApiId:
        Ref: ApiId
      PluginId:
        Ref: PluginId
      StageName:
        Ref: StageName
    Type: ALIYUN::ApiGateway::PluginAttachment
Outputs:
  ApiId:
    Description: The api id.
    Value:
      Fn::GetAtt:
      - PluginAttachment
      - ApiId
  PluginId:
    Description: The plugin id.
    Value:
      Fn::GetAtt:
      - PluginAttachment
      - PluginId

JSON

{
  "ROSTemplateFormatVersion": "2015-09-01",
  "Parameters": {
    "ApiId": {
      "Description": "The ID of the API to which you want to bind the plug-in.",
      "Type": "String"
    },
    "PluginId": {
      "Description": "The ID of the plugin that you want to bind.",
      "Type": "String"
    },
    "StageName": {
      "AllowedValues": [
        "RELEASE",
        "PRE",
        "TEST"
      ],
      "Description": "The name of the runtime environment. Valid values: \nRELEASE: indicates the release environment.\nPRE: indicates the pre-release environment.\nTEST: indicates the test environment.",
      "Type": "String"
    }
  },
  "Resources": {
    "PluginAttachment": {
      "Properties": {
        "ApiId": {
          "Ref": "ApiId"
        },
        "PluginId": {
          "Ref": "PluginId"
        },
        "StageName": {
          "Ref": "StageName"
        }
      },
      "Type": "ALIYUN::ApiGateway::PluginAttachment"
    }
  },
  "Outputs": {
    "ApiId": {
      "Description": "The api id.",
      "Value": {
        "Fn::GetAtt": [
          "PluginAttachment",
          "ApiId"
        ]
      }
    },
    "PluginId": {
      "Description": "The plugin id.",
      "Value": {
        "Fn::GetAtt": [
          "PluginAttachment",
          "PluginId"
        ]
      }
    }
  }
}

Scenario 2: Create a new API and plug-in and attach them

YAML

ROSTemplateFormatVersion: '2015-09-01'
Parameters:
  VpcId:
    Description: The ID of the VPC
    Type: String
    AssociationProperty: ALIYUN::ECS::VPC::VPCId
  ECSInstanceId:
    Description: The ID of the ECS Instance.
    Type: String
    AssociationProperty: ALIYUN::ECS::Instance::InstanceId
  APIGroupId:
    Description: The ID of the ApiGateway GroupId.
    Type: String
  PluginData:
    Description: The ApiGateway Plugin Data.
    Type: String
    Default: "type: ALLOW \t     # The control mode. Valid values: ALLOW for whitelist mode and REFUSE for blacklist mode.\nitems:\n  - blocks:          # IP address block\n      - 78.11.12.2   # IP address\n      - 61.3.9.0/24  # CIDR block\n  - blocks:          # IP address block\n      - 79.11.12.2   # IP address"
Resources:
  ApiGatewayApi:
    Type: ALIYUN::ApiGateway::Api
    Properties:
      AuthType: APP
      ServiceConfig:
        ServiceHttpMethod: GET
        ServiceProtocol: HTTP
        ServiceVpcEnable: 'TRUE'
        VpcConfig:
          InstanceId:
            Ref: ECSInstanceId
          VpcId:
            Ref: VpcId
          Port: 80
        ServicePath: /backend
      RequestConfig:
        RequestHttpMethod: GET
        RequestPath: /path/to/resource
      Visibility: PUBLIC
      ApiName: api_2026-01-12-11-38-54
      GroupId:
        Ref: APIGroupId
  ApiGatewayPlugin:
    Type: ALIYUN::ApiGateway::Plugin
    Properties:
      PluginName: TestPlugin
      PluginData:
        Ref: PluginData
      PluginType: trafficControl
  ApiGatewayDeployment:
    Type: ALIYUN::ApiGateway::Deployment
    Properties:
      ApiId:
        Ref: ApiGatewayApi
      GroupId:
        Ref: APIGroupId
      StageName: RELEASE
  ApiGatewayPluginAttachment:
    Type: ALIYUN::ApiGateway::PluginAttachment
    DependsOn:
      - ApiGatewayDeployment
    Properties:
      PluginId:
        Ref: ApiGatewayPlugin
      ApiId:
        Ref: ApiGatewayApi
      StageName: RELEASE

JSON

{
  "ROSTemplateFormatVersion": "2015-09-01",
  "Parameters": {
    "VpcId": {
      "Description": "The ID of the VPC",
      "Type": "String",
      "AssociationProperty": "ALIYUN::ECS::VPC::VPCId"
    },
    "ECSInstanceId": {
      "Description": "The ID of the ECS Instance.",
      "Type": "String",
      "AssociationProperty": "ALIYUN::ECS::Instance::InstanceId"
    },
    "APIGroupId": {
      "Description": "The ID of the ApiGateway GroupId.",
      "Type": "String"
    },
    "PluginData": {
      "Description": "The ApiGateway Plugin Data.",
      "Type": "String",
      "Default": "type: ALLOW \t     # The control mode. Valid values: ALLOW for whitelist mode and REFUSE for blacklist mode.\nitems:\n  - blocks:          # IP address block\n      - 78.11.12.2   # IP address\n      - 61.3.9.0/24  # CIDR block\n  - blocks:          # IP address block\n      - 79.11.12.2   # IP address"
    }
  },
  "Resources": {
    "ApiGatewayApi": {
      "Type": "ALIYUN::ApiGateway::Api",
      "Properties": {
        "AuthType": "APP",
        "ServiceConfig": {
          "ServiceHttpMethod": "GET",
          "ServiceProtocol": "HTTP",
          "ServiceVpcEnable": "TRUE",
          "VpcConfig": {
            "InstanceId": {
              "Ref": "ECSInstanceId"
            },
            "VpcId": {
              "Ref": "VpcId"
            },
            "Port": 80
          },
          "ServicePath": "/backend"
        },
        "RequestConfig": {
          "RequestHttpMethod": "GET",
          "RequestPath": "/path/to/resource"
        },
        "Visibility": "PUBLIC",
        "ApiName": "api_2026-01-12-11-38-54",
        "GroupId": {
          "Ref": "APIGroupId"
        }
      }
    },
    "ApiGatewayPlugin": {
      "Type": "ALIYUN::ApiGateway::Plugin",
      "Properties": {
        "PluginName": "TestPlugin",
        "PluginData": {
          "Ref": "PluginData"
        },
        "PluginType": "trafficControl"
      }
    },
    "ApiGatewayDeployment": {
      "Type": "ALIYUN::ApiGateway::Deployment",
      "Properties": {
        "ApiId": {
          "Ref": "ApiGatewayApi"
        },
        "GroupId": {
          "Ref": "APIGroupId"
        },
        "StageName": "RELEASE"
      }
    },
    "ApiGatewayPluginAttachment": {
      "Type": "ALIYUN::ApiGateway::PluginAttachment",
      "DependsOn": [
        "ApiGatewayDeployment"
      ],
      "Properties": {
        "PluginId": {
          "Ref": "ApiGatewayPlugin"
        },
        "ApiId": {
          "Ref": "ApiGatewayApi"
        },
        "StageName": "RELEASE"
      }
    }
  }
}

Important

When attaching or detaching a plug-in, the API must be in the published state. Otherwise, the operation fails.