Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

External Engines for Amazon Service Catalog

In Amazon Service Catalog, external engines are represented through an EXTERNAL product type. The EXTERNAL product type allows for the integration of third-party provisioning engines, such as Terraform. You can use external engines to extend the capabilities of Service Catalog beyond the native Amazon CloudFormation templates, enabling the use of other instructure as code (IaC) tools.

The EXTERNAL product type allows you to manage and deploy resources using the familiar interface of Service Catalog while leveraging the specific features and syntax of your chosen IaC tool.

To enable EXTERNAL product types in Service Catalog, you must define a set of standard resources in your account. These resources are known as the engine. Service Catalog delegate tasks to the engine at specific points in the artifact-parsing and provisioning operations.

A provisioning artifact represents the specific version of a product within Service Catalog, allowing you to manage and deploy consistent resources.

When you call Amazon Service Catalog's DescribeProvisioningArtifact or DescribeProvisioningParameters operations for a provisioning artifact for an EXTERNAL product type, Service Catalog invokes an Amazon Lambda function in the engine. This is required to extract the list of parameters from the provided provisioning artifact and return them to Amazon Service Catalog. These parameters will be used later as part of the provisioning process.

When you provision an EXTERNAL provisioning artifact by calling ProvisionProduct, Service Catalog first performs some actions internally, then send a message to an Amazon SQS queue in the engine. Next, the engine assumes the provided launch role (the IAM role that you assign to a product as a launch constraint), provisions the resources based on the provided provisioning artifact, and invokes the NotifyProvisionProductEngineWorkflowResult API to report success or failure.

Calls to UpdateProvisionedProduct and TerminateProvisionedProduct are handled similarly, with each having a distinct queue and Notify APIs:

Considerations

Limit of one external engine per hub account

You can only use one EXTERNAL provisioning engine per Service Catalog hub account. The Service Catalog hub-and-spoke model allows the hub account to create baseline products and share the portfolio while the spoke accounts import portfolios and leverage the products.

This limit is because EXTERNAL can only be routed to one engine in an account. If an administrator wants to have multiple external engines, the administrator must set up the external engines (along with the portfolios and products) in different hub accounts.

External engines only support launch roles with launch contraints

EXTERNAL provisioning artifacts only support provisioning with launch roles which are specified using launch constraints. A launch constraint specifies the IAM role that Service Catalog assumes when an end user launches, updates, or terminates a product. For more information on launch constraints, see Amazon Service Catalog Launch Constraints.

Parameter Parsing

EXTERNAL provisioning artifacts can be of any format. This means that when creating an EXTERNAL product type, the engine is required to extract the list of parameters from the provided provisioning artifact and return them to Service Catalog. This is done by creating a Lambda function in your account that can accept the following request format, process the provisioning artifact, and return the following response format.

Request syntax:

{
    "artifact": {
        "path": "string",
        "type": "string"
    },
    "launchRoleArn": "string"
}

Response syntax:

{
    "parameters": [
        {
            "key": "string"
            "defaultValue": "string",
            "type": "string",
            "description": "string",
            "isNoEcho": boolean
        },
    ]
}

Provisioning

For the ProvisionProduct operation, Service Catalog delegates the actual provisioning of resources to the engine. The engine is responsible for interfacing with your IaC solution of choice (such as Terraform) to provision resources as defined in the artifact. The engine is also responsible for notifying Service Catalog of the result.

Service Catalog sends all Provision requests to an Amazon SQS queue in your account named ServiceCatalogExternalProvisionOperationQueue.

Request syntax:

{
    "token": "string",
    "operation": "string",
    "provisionedProductId": "string",
    "provisionedProductName": "string",
    "productId": "string",
    "provisioningArtifactId": "string",
    "recordId": "string",
    "launchRoleArn": "string",
    "artifact": {
        "path": "string",
        "type": "string"
    },
    "identity": {
        "principal": "string",
        "awsAccountId": "string",
        "organizationId": "string"
    },
    "parameters": [
        {
            "key": "string",
            "value": "string"
        }
    ],
    "tags": [
        {
            "key": "string",
            "value": "string"
        }
    ]
}

Workflow Result Notification:

Invoke the NotifyProvisionProductEngineWorkflowResult API with the response object specified on the API details page.

Updating

For the UpdateProvisionedProduct operation, Service Catalog delegates the actual updating of resources to the engine. The engine is responsible for interfacing with your IaC solution of choice (such as Terraform) to updating resources as defined in the artifact. The engine is also responsible for notifying Service Catalog of the result.

Service Catalog sends all Update requests to an Amazon SQS queue in your account named ServiceCatalogExternalUpdateOperationQueue.

Request syntax:

{
    "token": "string",
    "operation": "string",
    "provisionedProductId": "string",
    "provisionedProductName": "string",
    "productId": "string",
    "provisioningArtifactId": "string",
    "recordId": "string",
    "launchRoleArn": "string",
    "artifact": {
        "path": "string",
        "type": "string"
    },
    "identity": {
        "principal": "string",
        "awsAccountId": "string",
        "organizationId": "string"
    },
    "parameters": [
        {
            "key": "string",
            "value": "string"
        }
    ],
    "tags": [
        {
            "key": "string",
            "value": "string"
        }
    ]
}

Workflow Result Notification:

Invoke the NotifyUpdateProvisionedProductEngineWorkflowResult API with the response object specified on the API details page.

Terminating

For the TerminateProvisionedProduct operation, Service Catalog delegates the actual terminating of resources to the engine. The engine is responsible for interfacing with your IaC solution of choice (such as Terraform) to terminate resources as defined in the artifact. The engine is also responsible for notifying Service Catalog of the result.

Service Catalog sends all Terminate requests to an Amazon SQS queue in your account named ServiceCatalogExternalTerminateOperationQueue.

Request syntax:

{
    "token": "string",
    "operation": "string",
    "provisionedProductId": "string",
    "provisionedProductName": "string",
    "recordId": "string",
    "launchRoleArn": "string",
    "identity": {
        "principal": "string",
        "awsAccountId": "string",
        "organizationId": "string"
    }
}

Workflow Result Notification:

Invoke the NotifyTerminateProvisionedProductEngineWorkflowResult API with the response object specified on the API details page.

Tagging

For managing tags through Resource Groups, your launch role need the following additional permission statements:

{
    "Effect": "Allow",
    "Action": [
        "resource-groups:CreateGroup",
        "resource-groups:ListGroupResources"
    ],
    "Resource": "*"
},
{
    "Effect": "Allow",
    "Action": [
        "tag:GetResources",
        "tag:GetTagKeys",
        "tag:GetTagValues",
        "tag:TagResources",
        "tag:UntagResources"
    ],
    "Resource": "*"
}