Using resource types - Cloud Control API

Using resource types

To use a resource type with AWS Cloud Control API, that resource type must be present and activated in your AWS account. Resource types published by Amazon are activated by default. You can choose to activate public resource types offered by third-party publishers as well. You do this, and other resource type management tasks, through the AWS CloudFormation extension registry.

The extension registry is a feature of AWS CloudFormation that contains detailed information about the resource types available for use in your account. These can include resource types published by third-parties, in addition to those published by Amazon. Using the registry, you can manage the resource types in your account, including:

  • View the available and activated resource types.

  • Register private resource types for use in your account.

  • Activate public third-party resource types.

  • Manage the resource type versions, including setting the default version of a resource type in your account.

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

You can also use the AWS 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 AWS CloudFormation User Guide.

Managing resource types using the AWS CloudFormation API

In addition to accessing the extension registry through the AWS CloudFormation console, you can use operations included in the AWS 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, activate, and configure the resource types available in your account.

CloudFormation API operation AWS CLI command Description

DescribeType

describe-type

Returns detailed information about a resource type.

ListTypes

list-types

Returns summary information about a resource type.

ActivateType

activate-type

Activates a public third-party resource type, making it available for use in your account.

DeactivateType

deactivate-type

Deactivates a public third-party resource type in your account.

ListTypeVersions

list-type-versions

Returns summary information about the versions of a resource type.

SetTypeDefaultVersion

set-type-default-version

Specifies the default version of a resource type.

BatchDescribeTypeConfigurations

batch-describe-type-configurations

Returns configuration data for the specified resource types.

SetTypeConfiguration

set-type-configuration

Specifies the configuration data for a resource type in your account.

RegisterType

register-type

Registers a private third-party resource, making it available for use in your account.

DeregisterType

deregister-type

Deregisters a private third-party resource, removing it from active use in your account.

Determining if a resource type supports Cloud Control API

By default, resource types published in the CloudFormation registry automatically support Cloud Control API resource operations. This includes private resource types, in addition to public third-party resource types. However, the AWS 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.

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

You can also use the AWS Command Line Interface (AWS 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 AWS 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 or PRIVATE for private 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 AWS 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 AWS CLI. In addition, the AWS CloudFormation User Guide contains reference topics for each available resource type that AWS publishes. For detailed information about resource type properties, in addition to usage examples, see the corresponding topics in the AWS resource and property types reference section.

Note

Not all resource types listed in the AWS 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 resources.

Viewing a resource type schema using the AWS CloudFormation console

  1. Sign in to the AWS Management Console and open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation.

  2. In the CloudFormation navigation pane, under Registry, select Activate 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 AWS 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" ] } }