Using the AWS CloudFormation registry

The CloudFormation registry lists the resources, both private and public (AWS), that are available for use in your CloudFormation account.

Private and public resource providers

Private resource providers are those resource providers that you have explicitly registered for use in your AWS account. These may be resource providers you've created yourself, as well as ones shared with you. You can use the CloudFormation CLI, an open-source tool for resource management, to create private resource providers. For more information, see the CloudFormation Command Line Interface User Guide.

Note

Private resource providers implement custom logic that runs during resource create, read, update, list, and delete operations. Because of this, using private resource providers in your CloudFormation stacks incurs charges to your account. This is in addition to any charges incurred for the resources created. For more information, see AWS CloudFormation pricing.

Public resource providers are those provided by AWS to manage specific AWS service resources. While the registry lists AWS resources implemented using the open-source resource provider framework, all the resources included in the Resource and property types reference are available for use in your CloudFormation account.

Registering resource providers in CloudFormation

To use private resource providers--either ones you develop yourself, or providers shared with you--you must first register them with CloudFormation, in the accounts and regions in which you want to use them. Once you're registered a resource provider, it will appear in the CloudFormation registry for that account and region, and you can use it in your stack templates.

You can register a resource provider using the register-type command of the AWS CLI, or using the submit command of the CloudFormation CLI. To register a resource provider using the CloudFormation CLI, see Registering resource providers in the CloudFormation CLI User Guide.

IAM permissions for registering a resource provider

As part of registering a resource provider, you specify an S3 bucket which contains the schema handler package. This package contains the schema, event handlers, and associated files for the resource provider you want to register. CloudFormation requires the following IAM permissions in order to access this S3 bucket and the schema handler package. (This is true whether you're either using the register-type command of the AWS CLI, or the submit command of the CloudFormation CLI.)

• s3:ListBucket

• s3:GetObject

Make sure you grant the cloudformation.amazonaws.com service these permissions for the appropriate S3 bucket before you attempt to register the resource provider. For example:

  ArtifactCopyPolicy:
    Type: AWS::S3::BucketPolicy
    Properties:
      Bucket: !Ref ArtifactBucket
      PolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Sid: Allow CloudFormation to copy artifacts from the bucket
            Effect: Allow
            Principal:
              Service: cloudformation.amazonaws.com
            Action:
              - s3:ListBucket
              - s3:GetObject
            Resource:
              - !Sub "arn:${AWS::Partition}:s3:::${ArtifactBucket}"
              - !Sub "arn:${AWS::Partition}:s3:::${ArtifactBucket}/*"

For more information, see Actions, resources, and condition keys for Amazon S3 in the AWS Identity and Access Management User Guide.

In addition, both the execution role and the logging role you specify when registering the resource provider must specify a trust relationship that allows the CloudFormation service principal to assume that role. For example:

  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": {
          "Service": "resources.cloudformation.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
      }
    ]
  }

For more information, see Creating a role to delegate permissions to an AWS service in the AWS Identity and Access Management User Guide.

To register a resource provider using the AWS CLI

1. Locate the S3 bucket that contains the resource provider package for the resource provider you want to register in your account.

2. Use the register-type command to register the resource provider in your account:

   RegisterType is an asynchronous action, and returns a registration token you can use to track the progress of your registration request.

   Note

   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. You can then specify this execution role using the --execution-role-arn parameter. CloudFormation then assumes that execution role to provide your resource type with the appropriate credentials.

   For example. the following command registers the My::Resource::Example resource type in the current AWS account:

   aws cloudformation register-type --type-name My::Resource::Example --schema-handler-package [s3 object path] --type RESOURCE
                   
   {
       "RegistrationToken": "f5525280-104e-4d35-bef5-8f1fexample"
   }

3. Optional: Use the registration token with the describe-type-registration command to track the progress of your registration request.

   When CloudFormation completes the registration request, it sets the progress status of the request to COMPLETE.

   The following example uses the registration token returned by the RegisterType command above to return registration status information.

   aws cloudformation describe-type-registration --registration-token f5525280-104e-4d35-bef5-8f1fexample
   
   {
       "ProgressStatus": "COMPLETE", 
       "TypeArn": "arn:aws:cloudformation:us-east-1:012345678910:type/resource/My-Resource-Example", 
       "Description": "Deployment is currently in DEPLOY_STAGE of status COMPLETED; ", 
       "TypeVersionArn": "arn:aws:cloudformation:us-east-1:012345678910:type/resource/My-Resource-Example/00000001"
   }

Specifying which version of a resource provider to use

Over time, you may register multiple versions of the same resource provider. You can specify which version of the resource provider you want to use for CloudFormation operations.

To specify which version of a resource provider to use using the AWS CLI

• Use the set-type-default-version command to specify which version of the resource provider to use for CloudFormation operations in your account.

  For example, the following command sets the default version of the My::Resource::Example resource type to 00000003 for the current account.

  aws cloudformation set-type-default-version --type RESOURCE --type-name My::Resource::Example --version-id 00000003

Viewing registered resource providers in CloudFormation

Once you've registered a resource provider in an account, you can view the details of that resource provider in the CloudFormation console. Private resource providers are displayed in the Private section of the CloudFormation registry.

To view registered resource providers in the CloudFormation console

1. In the AWS CloudFormation console, from the CloudFormation navigation pane, under CloudFormation registry, select Resource types.

2. On the Resource types page, under Resource types, select Public or Private.

Record resource types in AWS Config

You can specify that AWS Config automatically track your private resource types and record changes to those resources as configuration items. This enables you to view configuration history for these private resource types, as well as write Config rules to verify configuration best practices.

To have AWS Config automatically track your private resource types:

• Manage the resources through CloudFormation. This includes performing all resource create, updated, and delete operations through CloudFormation.

  Note

  If you use an IAM role to perform your stack operations, that IAM role must have permission to call the following AWS Config actions:

  • PutResourceConfig

  • DeleteResourceConfig

• Configure AWS Config to record all resource types. For more information, see Record configurations for third-party resources in the AWS Config Developer Guide.

  Note

  Config does not support recording of private resources containing properties defined as both required and write-only.

  By design, resource properties defined as write-only are not returned in the schema used to create the Config configuration item. Because of this, including a property that is defined as both write-only and required will cause the configuration item creation to fail, as a required property will not be not present. To view the schema that will be used to create the configuration item, you can review the schema property of the DescribeType action.

For more information on configuration items, see Configuration items in the AWS Config Developer Guide.

Preventing sensitive properties being recorded in a configuration item

Your resource type may contain properties that you consider sensitive information, such as passwords, secrets, or other sensitive data, that you don't want recorded as part of the configuration item. To prevent a property from being recorded in the configuration item, you can include that property in the writeOnlyproperties list in your resource type schema. Resource properties listed as writeOnlyproperties can be specified by the user, but will not be returned by a read or list request.

For more information, see Resource Provider Schema in the CloudFormation Command Line Interface User Guide.