2019/11/18 - AWS CloudFormation - 9 new api methods
Changes This release introduces APIs for the CloudFormation Registry, a new service to submit and discover resource providers with which you can manage third-party resources natively in CloudFormation.
Registers a type with the CloudFormation service. Registering a type makes it available for use in CloudFormation templates in your AWS account, and includes:
Validating the resource schema
Determining which handlers have been specified for the resource
Making the resource type available for use in your account
For more information on how to develop types and ready them for registeration, see Creating Resource Providers in the CloudFormation CLI User Guide .
Once you have initiated a registration request using RegisterType , you can use DescribeTypeRegistration to monitor the progress of the registration request.
See also: AWS API Documentation
Request Syntax
client.register_type(
Type='RESOURCE',
TypeName='string',
SchemaHandlerPackage='string',
LoggingConfig={
'LogRoleArn': 'string',
'LogGroupName': 'string'
},
ExecutionRoleArn='string',
ClientRequestToken='string'
)
string
The kind of type.
Currently, the only valid value is RESOURCE .
string
[REQUIRED]
The name of the type being registered.
We recommend that type names adhere to the following pattern: company_or_organization ::service ::type .
Note
The following organization namespaces are reserved and cannot be used in your resource type names:
Alexa
AMZN
Amazon
AWS
Custom
Dev
string
[REQUIRED]
A url to the S3 bucket containing the schema handler package that contains the schema, event handlers, and associated files for the type you want to register.
For information on generating a schema handler package for the type you want to register, see submit in the CloudFormation CLI User Guide .
dict
Specifies logging configuration information for a type.
LogRoleArn (string) -- [REQUIRED]
The ARN of the role that CloudFormation should assume when sending log entries to CloudWatch logs.
LogGroupName (string) -- [REQUIRED]
The Amazon CloudWatch log group to which CloudFormation sends error logging information when invoking the type's handlers.
string
The Amazon Resource Name (ARN) of the IAM execution role to use to register the type. If your resource type calls AWS APIs in any of its handlers, you must create an IAM execution role that includes the necessary permissions to call those AWS APIs, and provision that execution role in your account. CloudFormation then assumes that execution role to provide your resource type with the appropriate credentials.
string
A unique identifier that acts as an idempotency key for this registration request. Specifying a client request token prevents CloudFormation from generating more than one version of a type from the same registeration request, even if the request is submitted multiple times.
dict
Response Syntax
{
'RegistrationToken': 'string'
}
Response Structure
(dict) --
RegistrationToken (string) --
The identifier for this registration request.
Use this registration token when calling DescribeTypeRegistration , which returns information about the status and IDs of the type registration.
Returns summary information about the versions of a type.
See also: AWS API Documentation
Request Syntax
client.list_type_versions(
Type='RESOURCE',
TypeName='string',
Arn='string',
MaxResults=123,
NextToken='string',
DeprecatedStatus='LIVE'|'DEPRECATED'
)
string
The kind of the type.
Currently the only valid value is RESOURCE .
string
The name of the type for which you want version summary information.
Conditional: You must specify TypeName or Arn .
string
The Amazon Resource Name (ARN) of the type for which you want version summary information.
Conditional: You must specify TypeName or Arn .
integer
The maximum number of results to be returned with a single call. If the number of available results exceeds this maximum, the response includes a NextToken value that you can assign to the NextToken request parameter to get the next set of results.
string
If the previous paginated request didn't return all of the remaining results, the response object's NextToken parameter value is set to a token. To retrieve the next set of results, call this action again and assign that token to the request object's NextToken parameter. If there are no remaining results, the previous response object's NextToken parameter is set to null .
string
The deprecation status of the type versions that you want to get summary information about.
Valid values include:
LIVE : The type version is registered and can be used in CloudFormation operations, dependent on its provisioning behavior and visibility scope.
DEPRECATED : The type version has been deregistered and can no longer be used in CloudFormation operations.
dict
Response Syntax
{
'TypeVersionSummaries': [
{
'Type': 'RESOURCE',
'TypeName': 'string',
'VersionId': 'string',
'Arn': 'string',
'TimeCreated': datetime(2015, 1, 1),
'Description': 'string'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
TypeVersionSummaries (list) --
A list of TypeVersionSummary structures that contain information about the specified type's versions.
(dict) --
Contains summary information about a specific version of a CloudFormation type.
Type (string) --
The kind of type.
TypeName (string) --
The name of the type.
VersionId (string) --
The ID of a specific version of the type. The version ID is the value at the end of the Amazon Resource Name (ARN) assigned to the type version when it is registered.
Arn (string) --
The Amazon Resource Name (ARN) of the type version.
TimeCreated (datetime) --
When the version was registered.
Description (string) --
The description of the type version.
NextToken (string) --
If the request doesn't return all of the remaining results, NextToken is set to a token. To retrieve the next set of results, call this action again and assign that token to the request object's NextToken parameter. If the request returns all results, NextToken is set to null .
Returns a list of registration tokens for the specified type.
See also: AWS API Documentation
Request Syntax
client.list_type_registrations(
Type='RESOURCE',
TypeName='string',
TypeArn='string',
RegistrationStatusFilter='COMPLETE'|'IN_PROGRESS'|'FAILED',
MaxResults=123,
NextToken='string'
)
string
The kind of type.
Currently the only valid value is RESOURCE .
string
The name of the type.
Conditional: You must specify TypeName or Arn .
string
The Amazon Resource Name (ARN) of the type.
Conditional: You must specify TypeName or Arn .
string
The current status of the type registration request.
integer
The maximum number of results to be returned with a single call. If the number of available results exceeds this maximum, the response includes a NextToken value that you can assign to the NextToken request parameter to get the next set of results.
string
If the previous paginated request didn't return all of the remaining results, the response object's NextToken parameter value is set to a token. To retrieve the next set of results, call this action again and assign that token to the request object's NextToken parameter. If there are no remaining results, the previous response object's NextToken parameter is set to null .
dict
Response Syntax
{
'RegistrationTokenList': [
'string',
],
'NextToken': 'string'
}
Response Structure
(dict) --
RegistrationTokenList (list) --
A list of type registration tokens.
Use DescribeTypeRegistration to return detailed information about a type registration request.
(string) --
NextToken (string) --
If the request doesn't return all of the remaining results, NextToken is set to a token. To retrieve the next set of results, call this action again and assign that token to the request object's NextToken parameter. If the request returns all results, NextToken is set to null .
Specify the default version of a type. The default version of a type will be used in CloudFormation operations.
See also: AWS API Documentation
Request Syntax
client.set_type_default_version(
Arn='string',
Type='RESOURCE',
TypeName='string',
VersionId='string'
)
string
The Amazon Resource Name (ARN) of the type for which you want version summary information.
Conditional: You must specify TypeName or Arn .
string
The kind of type.
string
The name of the type.
Conditional: You must specify TypeName or Arn .
string
The ID of a specific version of the type. The version ID is the value at the end of the Amazon Resource Name (ARN) assigned to the type version when it is registered.
dict
Response Syntax
{}
Response Structure
(dict) --
Returns summary information about types that have been registered with CloudFormation.
See also: AWS API Documentation
Request Syntax
client.list_types(
Visibility='PUBLIC'|'PRIVATE',
ProvisioningType='NON_PROVISIONABLE'|'IMMUTABLE'|'FULLY_MUTABLE',
DeprecatedStatus='LIVE'|'DEPRECATED',
MaxResults=123,
NextToken='string'
)
string
The scope at which the type is visible and usable in CloudFormation operations.
Valid values include:
PRIVATE : The type is only visible and usable within the account in which it is registered. Currently, AWS CloudFormation marks any types you create as PRIVATE .
PUBLIC : The type is publically visible and usable within any Amazon account.
string
The provisioning behavior of the type. AWS CloudFormation determines the provisioning type during registration, based on the types of handlers in the schema handler package submitted.
Valid values include:
FULLY_MUTABLE : The type includes an update handler to process updates to the type during stack update operations.
IMMUTABLE : The type does not include an update handler, so the type cannot be updated and must instead be replaced during stack update operations.
NON_PROVISIONABLE : The type does not include create, read, and delete handlers, and therefore cannot actually be provisioned.
string
The deprecation status of the types that you want to get summary information about.
Valid values include:
LIVE : The type is registered for use in CloudFormation operations.
DEPRECATED : The type has been deregistered and can no longer be used in CloudFormation operations.
integer
The maximum number of results to be returned with a single call. If the number of available results exceeds this maximum, the response includes a NextToken value that you can assign to the NextToken request parameter to get the next set of results.
string
If the previous paginated request didn't return all of the remaining results, the response object's NextToken parameter value is set to a token. To retrieve the next set of results, call this action again and assign that token to the request object's NextToken parameter. If there are no remaining results, the previous response object's NextToken parameter is set to null .
dict
Response Syntax
{
'TypeSummaries': [
{
'Type': 'RESOURCE',
'TypeName': 'string',
'DefaultVersionId': 'string',
'TypeArn': 'string',
'LastUpdated': datetime(2015, 1, 1),
'Description': 'string'
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
TypeSummaries (list) --
A list of TypeSummary structures that contain information about the specified types.
(dict) --
Contains summary information about the specified CloudFormation type.
Type (string) --
The kind of type.
TypeName (string) --
The name of the type.
DefaultVersionId (string) --
The ID of the default version of the type. The default version is used when the type version is not specified.
To set the default version of a type, use SetTypeDefaultVersion .
TypeArn (string) --
The Amazon Resource Name (ARN) of the type.
LastUpdated (datetime) --
When the current default version of the type was registered.
Description (string) --
The description of the type.
NextToken (string) --
If the request doesn't return all of the remaining results, NextToken is set to a token. To retrieve the next set of results, call this action again and assign that token to the request object's NextToken parameter. If the request returns all results, NextToken is set to null .
Reports progress of a resource handler to CloudFormation.
Reserved for use by the CloudFormation CLI. Do not use this API in your code.
See also: AWS API Documentation
Request Syntax
client.record_handler_progress(
BearerToken='string',
OperationStatus='PENDING'|'IN_PROGRESS'|'SUCCESS'|'FAILED',
CurrentOperationStatus='PENDING'|'IN_PROGRESS'|'SUCCESS'|'FAILED',
StatusMessage='string',
ErrorCode='NotUpdatable'|'InvalidRequest'|'AccessDenied'|'InvalidCredentials'|'AlreadyExists'|'NotFound'|'ResourceConflict'|'Throttling'|'ServiceLimitExceeded'|'NotStabilized'|'GeneralServiceException'|'ServiceInternalError'|'NetworkFailure'|'InternalFailure',
ResourceModel='string',
ClientRequestToken='string'
)
string
[REQUIRED]
Reserved for use by the CloudFormation CLI.
string
[REQUIRED]
Reserved for use by the CloudFormation CLI.
string
Reserved for use by the CloudFormation CLI.
string
Reserved for use by the CloudFormation CLI.
string
Reserved for use by the CloudFormation CLI.
string
Reserved for use by the CloudFormation CLI.
string
Reserved for use by the CloudFormation CLI.
dict
Response Syntax
{}
Response Structure
(dict) --
Returns detailed information about a type that has been registered.
If you specify a VersionId , DescribeType returns information about that specific type version. Otherwise, it returns information about the default type version.
See also: AWS API Documentation
Request Syntax
client.describe_type(
Type='RESOURCE',
TypeName='string',
Arn='string',
VersionId='string'
)
string
The kind of type.
Currently the only valid value is RESOURCE .
string
The name of the type.
Conditional: You must specify TypeName or Arn .
string
The Amazon Resource Name (ARN) of the type.
Conditional: You must specify TypeName or Arn .
string
The ID of a specific version of the type. The version ID is the value at the end of the Amazon Resource Name (ARN) assigned to the type version when it is registered.
If you specify a VersionId , DescribeType returns information about that specific type version. Otherwise, it returns information about the default type version.
dict
Response Syntax
{
'Arn': 'string',
'Type': 'RESOURCE',
'TypeName': 'string',
'DefaultVersionId': 'string',
'Description': 'string',
'Schema': 'string',
'ProvisioningType': 'NON_PROVISIONABLE'|'IMMUTABLE'|'FULLY_MUTABLE',
'DeprecatedStatus': 'LIVE'|'DEPRECATED',
'LoggingConfig': {
'LogRoleArn': 'string',
'LogGroupName': 'string'
},
'ExecutionRoleArn': 'string',
'Visibility': 'PUBLIC'|'PRIVATE',
'SourceUrl': 'string',
'DocumentationUrl': 'string',
'LastUpdated': datetime(2015, 1, 1),
'TimeCreated': datetime(2015, 1, 1)
}
Response Structure
(dict) --
Arn (string) --
The Amazon Resource Name (ARN) of the type.
Type (string) --
The kind of type.
Currently the only valid value is RESOURCE .
TypeName (string) --
The name of the registered type.
DefaultVersionId (string) --
The ID of the default version of the type. The default version is used when the type version is not specified.
To set the default version of a type, use SetTypeDefaultVersion .
Description (string) --
The description of the registered type.
Schema (string) --
The schema that defines the type.
For more information on type schemas, see Resource Provider Schema in the CloudFormation CLI User Guide .
ProvisioningType (string) --
The provisioning behavior of the type. AWS CloudFormation determines the provisioning type during registration, based on the types of handlers in the schema handler package submitted.
Valid values include:
FULLY_MUTABLE : The type includes an update handler to process updates to the type during stack update operations.
IMMUTABLE : The type does not include an update handler, so the type cannot be updated and must instead be replaced during stack update operations.
NON_PROVISIONABLE : The type does not include all of the following handlers, and therefore cannot actually be provisioned.
create
read
delete
DeprecatedStatus (string) --
The deprecation status of the type.
Valid values include:
LIVE : The type is registered and can be used in CloudFormation operations, dependent on its provisioning behavior and visibility scope.
DEPRECATED : The type has been deregistered and can no longer be used in CloudFormation operations.
LoggingConfig (dict) --
Contains logging configuration information for a type.
LogRoleArn (string) --
The ARN of the role that CloudFormation should assume when sending log entries to CloudWatch logs.
LogGroupName (string) --
The Amazon CloudWatch log group to which CloudFormation sends error logging information when invoking the type's handlers.
ExecutionRoleArn (string) --
The Amazon Resource Name (ARN) of the IAM execution role used to register the type. If your resource type calls AWS APIs in any of its handlers, you must create an IAM execution role that includes the necessary permissions to call those AWS APIs, and provision that execution role in your account. CloudFormation then assumes that execution role to provide your resource type with the appropriate credentials.
Visibility (string) --
The scope at which the type is visible and usable in CloudFormation operations.
Valid values include:
PRIVATE : The type is only visible and usable within the account in which it is registered. Currently, AWS CloudFormation marks any types you register as PRIVATE .
PUBLIC : The type is publically visible and usable within any Amazon account.
SourceUrl (string) --
The URL of the source code for the type.
DocumentationUrl (string) --
The URL of a page providing detailed documentation for this type.
LastUpdated (datetime) --
When the specified type version was registered.
TimeCreated (datetime) --
When the specified type version was registered.
Returns information about a type's registration, including its current status and type and version identifiers.
When you initiate a registration request using RegisterType , you can then use DescribeTypeRegistration to monitor the progress of that registration request.
Once the registration request has completed, use DescribeType to return detailed informaiton about a type.
See also: AWS API Documentation
Request Syntax
client.describe_type_registration(
RegistrationToken='string'
)
string
[REQUIRED]
The identifier for this registration request.
This registration token is generated by CloudFormation when you initiate a registration request using RegisterType .
dict
Response Syntax
{
'ProgressStatus': 'COMPLETE'|'IN_PROGRESS'|'FAILED',
'Description': 'string',
'TypeArn': 'string',
'TypeVersionArn': 'string'
}
Response Structure
(dict) --
ProgressStatus (string) --
The current status of the type registration request.
Description (string) --
The description of the type registration request.
TypeArn (string) --
The Amazon Resource Name (ARN) of the type being registered.
For registration requests with a ProgressStatus of other than COMPLETE , this will be null .
TypeVersionArn (string) --
The Amazon Resource Name (ARN) of this specific version of the type being registered.
For registration requests with a ProgressStatus of other than COMPLETE , this will be null .
Removes a type or type version from active use in the CloudFormation registry. If a type or type version is deregistered, it cannot be used in CloudFormation operations.
To deregister a type, you must individually deregister all registered versions of that type. If a type has only a single registered version, deregistering that version results in the type itself being deregistered.
You cannot deregister the default version of a type, unless it is the only registered version of that type, in which case the type itself is deregistered as well.
See also: AWS API Documentation
Request Syntax
client.deregister_type(
Arn='string',
Type='RESOURCE',
TypeName='string',
VersionId='string'
)
string
The Amazon Resource Name (ARN) of the type.
Conditional: You must specify TypeName or Arn .
string
The kind of type.
Currently the only valid value is RESOURCE .
string
The name of the type.
Conditional: You must specify TypeName or Arn .
string
The ID of a specific version of the type. The version ID is the value at the end of the Amazon Resource Name (ARN) assigned to the type version when it is registered.
dict
Response Syntax
{}
Response Structure
(dict) --