Using resource types - Cloud Control API
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).

Using resource types

Important

Cloud Control API doesn't support third-party resource types in the China (Beijing) Region or the China (Ningxia) Region..

The extension registry is a feature of Amazon CloudFormation that contains detailed information about the resource types available for use in your account. Using the registry, you can manage the resource types in your account, including:

  • View the available resource types.

  • Set account-level configuration properties of a resource type, if it has any.

You can also use the Amazon CloudFormation registry to view a resource type's schema, which contains important information about how to use the resource with Cloud Control API, such as property definitions and permission requirements. For more information, see Viewing resource type schemas.

The registry is available through the CloudFormation console, in addition to the CloudFormation API.

Note

Not all resource types listed in the CloudFormation registry currently support Cloud Control API. For more information, see Determining if a resource type supports Cloud Control API.

For more information about resource type management options, see Using the CloudFormation registry in the Amazon CloudFormation User Guide.

Managing resource types using the Amazon CloudFormation API

In addition to accessing the extension registry through the Amazon CloudFormation console, you can use operations included in the Amazon CloudFormation API to identify and manage the resource types in your account. The table below lists the API operations that you can use to discover and configure the resource types available in your account.

CloudFormation API operation Amazon CLI command Description

DescribeType

describe-type

Returns detailed information about a resource type.

ListTypes

list-types

Returns summary information about a resource type.

Determining if a resource type supports Cloud Control API

By default, Amazon resource types published in the registry automatically support Cloud Control API resource operations. However, the Amazon CloudFormation registry also contains legacy resource types, classified as non-provisionable. These resource types don't currently support Cloud Control API, and you can't use them in resource operations.

Important

Cloud Control API doesn't support third-party resource types in the China (Beijing) Region or the China (Ningxia) Region..

For a list of the Amazon public resource types that currently support Cloud Control API resource operations, see Resource types that support Cloud Control API.

You can also use the Amazon Command Line Interface (Amazon CLI) to generate a list of supported resource types or to determine if a specific resource type supports Cloud Control API.

Generating a list of supported resources using the Amazon CLI
  • Use the list-types command, with the following parameters:

    • type – Specify RESOURCE to select only resource types.

    • visibility – Specify PUBLIC to select public resources.

    • provisioning-type – Specify FULLY_MUTABLE or IMMUTABLE to select only those resource types that are provisionable.

    For example, the following command selects the first 100 public resource types that are fully mutable from the CloudFormation registry.

    $ aws cloudformation list-types \ --type RESOURCE --visibility PUBLIC \ --provisioning-type FULLY_MUTABLE --max-results 100
Determining if a specific resource type supports Cloud Control API using the Amazon CLI
  • Use the describe-type command to return details of the resource type.

    Resource types with a ProvisioningType of either FULLY_MUTABLE or IMMUTABLE support Cloud Control API resource operations.

    The following example returns details of the AWS::Logs::LogGroup resource type.

    $ aws cloudformation describe-type \ --type RESOURCE --type-name AWS::Logs::LogGroup

Viewing resource type schemas

During resource create and update operations, you specify which resource properties to set and their values. The properties of a resource are defined in its resource type schema. This includes data type, whether the property is required, valid values, and other property constraints.

You can view a resource type's schema using the CloudFormation console or the Amazon CLI. In addition, the Amazon CloudFormation User Guide contains reference topics for each available resource type that Amazon publishes. For detailed information about resource type properties, in addition to usage examples, see the corresponding topics in the Amazon resource and property types reference section.

Note

Not all resource types listed in the Amazon CloudFormation User Guide are available for use with Cloud Control API. To determine if a resource type is available, see Resource types that support Cloud Control API.

For detailed information about the resource type definition schema, which defines how resource type schema can be authored, see Resource type definition schema in the CloudFormation CLI User Guide for Extension Development.

For information about how to view an existing resource's current state, which includes its current property values, see Reading a resource's current state.

Viewing a resource type schema using the Amazon CloudFormation console

  1. Sign in to the Amazon Web Services Management Console and open the Amazon CloudFormation console at https://console.amazonaws.cn/cloudformation.

  2. In the CloudFormation navigation pane, under Registry, select Activated extensions.

  3. On the Resource types tab, select the resource type that you want to view the resource schema of.

    CloudFormation displays the resource type details page. The resource schema is displayed on the Schema tab.

Viewing a resource type schema using the Amazon CLI

  • Run describe-type.

    In the returned output, the Schema structure contains the resource type schema.

    For example, the following command returns information about the AWS::Logs::LogGroup resource type.

    $ aws cloudformation describe-type \ --type RESOURCE --type-name AWS::Logs::LogGroup

Viewing resource property attributes

Resource type properties are defined in the properties section of the resource type schema. This includes the property data type, whether the property is required, and any constraints such as allowable values or required patterns.

In addition, certain attributes set at the resource level govern when or if a property can be specified. This includes:

  • Properties defined as required must be specified in the desired state during resource creation.

  • Properties defined as createOnlyProperties can be set by users, but only during resource creation.

  • Properties defined as readOnlyProperties can't be set by users.

  • Properties defined as writeOnlyProperties can be specified by users when creating or updating a resource but can't be returned during a read or list request.

Viewing supported resource operations

You can determine which operations a resource type supports by referring to the handlers section of its resource type schema. If the resource type supports an operation, it's listed in the handlers section, and it contains a permissions element that lists the permissions that the handler requires.

For example, below is the handlers section of the resource type schema for the AWS::Logs::LogGroup resource type. This section shows that this resource type supports all five resource operations, and lists the permissions that each handler requires.

"handlers": { "create": { "permissions": [ "logs:DescribeLogGroups", "logs:CreateLogGroup", "logs:PutRetentionPolicy" ] }, "read": { "permissions": [ "logs:DescribeLogGroups" ] }, "update": { "permissions": [ "logs:DescribeLogGroups", "logs:AssociateKmsKey", "logs:DisassociateKmsKey", "logs:PutRetentionPolicy", "logs:DeleteRetentionPolicy" ] }, "delete": { "permissions": [ "logs:DescribeLogGroups", "logs:DeleteLogGroup" ] }, "list": { "permissions": [ "logs:DescribeLogGroups" ] } }