AWS CloudFormation

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.

DeregisterType (new) Link ¶

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'
)
type Arn

string

param Arn

The Amazon Resource Name (ARN) of the type.

Conditional: You must specify TypeName or Arn .

type Type

string

param Type

The kind of type.

Currently the only valid value is RESOURCE .

type TypeName

string

param TypeName

The name of the type.

Conditional: You must specify TypeName or Arn .

type VersionId

string

param VersionId

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.

rtype

dict

returns

Response Syntax

{}

Response Structure

  • (dict) --

DescribeTypeRegistration (new) Link ¶

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'
)
type RegistrationToken

string

param RegistrationToken

[REQUIRED]

The identifier for this registration request.

This registration token is generated by CloudFormation when you initiate a registration request using `` RegisterType `` .

rtype

dict

returns

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 .

RegisterType (new) Link ¶

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'
)
type Type

string

param Type

The kind of type.

Currently, the only valid value is RESOURCE .

type TypeName

string

param TypeName

[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

type SchemaHandlerPackage

string

param SchemaHandlerPackage

[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 .

type LoggingConfig

dict

param LoggingConfig

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.

type ExecutionRoleArn

string

param ExecutionRoleArn

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.

type ClientRequestToken

string

param ClientRequestToken

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.

rtype

dict

returns

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.

DescribeType (new) Link ¶

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'
)
type Type

string

param Type

The kind of type.

Currently the only valid value is RESOURCE .

type TypeName

string

param TypeName

The name of the type.

Conditional: You must specify TypeName or Arn .

type Arn

string

param Arn

The Amazon Resource Name (ARN) of the type.

Conditional: You must specify TypeName or Arn .

type VersionId

string

param VersionId

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.

rtype

dict

returns

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.

SetTypeDefaultVersion (new) Link ¶

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'
)
type Arn

string

param Arn

The Amazon Resource Name (ARN) of the type for which you want version summary information.

Conditional: You must specify TypeName or Arn .

type Type

string

param Type

The kind of type.

type TypeName

string

param TypeName

The name of the type.

Conditional: You must specify TypeName or Arn .

type VersionId

string

param VersionId

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.

rtype

dict

returns

Response Syntax

{}

Response Structure

  • (dict) --

ListTypeRegistrations (new) Link ¶

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'
)
type Type

string

param Type

The kind of type.

Currently the only valid value is RESOURCE .

type TypeName

string

param TypeName

The name of the type.

Conditional: You must specify TypeName or Arn .

type TypeArn

string

param TypeArn

The Amazon Resource Name (ARN) of the type.

Conditional: You must specify TypeName or Arn .

type RegistrationStatusFilter

string

param RegistrationStatusFilter

The current status of the type registration request.

type MaxResults

integer

param MaxResults

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.

type NextToken

string

param NextToken

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 .

rtype

dict

returns

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 .

RecordHandlerProgress (new) Link ¶

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'
)
type BearerToken

string

param BearerToken

[REQUIRED]

Reserved for use by the CloudFormation CLI .

type OperationStatus

string

param OperationStatus

[REQUIRED]

Reserved for use by the CloudFormation CLI .

type CurrentOperationStatus

string

param CurrentOperationStatus

Reserved for use by the CloudFormation CLI .

type StatusMessage

string

param StatusMessage

Reserved for use by the CloudFormation CLI .

type ErrorCode

string

param ErrorCode

Reserved for use by the CloudFormation CLI .

type ResourceModel

string

param ResourceModel

Reserved for use by the CloudFormation CLI .

type ClientRequestToken

string

param ClientRequestToken

Reserved for use by the CloudFormation CLI .

rtype

dict

returns

Response Syntax

{}

Response Structure

  • (dict) --

ListTypes (new) Link ¶

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'
)
type Visibility

string

param Visibility

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.

type ProvisioningType

string

param ProvisioningType

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.

type DeprecatedStatus

string

param DeprecatedStatus

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.

type MaxResults

integer

param MaxResults

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.

type NextToken

string

param NextToken

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 .

rtype

dict

returns

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 .

ListTypeVersions (new) Link ¶

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'
)
type Type

string

param Type

The kind of the type.

Currently the only valid value is RESOURCE .

type TypeName

string

param TypeName

The name of the type for which you want version summary information.

Conditional: You must specify TypeName or Arn .

type Arn

string

param Arn

The Amazon Resource Name (ARN) of the type for which you want version summary information.

Conditional: You must specify TypeName or Arn .

type MaxResults

integer

param MaxResults

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.

type NextToken

string

param NextToken

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 .

type DeprecatedStatus

string

param DeprecatedStatus

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.

rtype

dict

returns

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 .