Modeling resource types for use in AWS CloudFormation
The first step in creating a resource type is modeling that resource,
which involves crafting a schema that defines the resource, its properties, and their
attributes. When you initially create your resource type project using the CloudFormation
CLI init
command, one of the files created is an example resource schema. Use this
schema file as a starting point for defining the shape and semantics of your resource
type.
In order to be considered valid, your resource type's schema must adhere to the Resource type definition schema
The Resource Type Definition Schema is a meta-schema that extends
draft-07
Once you have defined your resource schema, you can use the CloudFormation CLI
validate
command to verify that the resource schema is valid.
In terms of testing, the resource schema also determines:
-
What unit test stubs are generated in your resource package, and what contract tests are appropriate to run for the resource. When you run the CloudFormation CLI
generate
command, the CloudFormation CLI generates empty unit tests based on the properties of the resource and their attributes. -
Which contract tests are appropriate for CloudFormation CLI to run for your resources. When you run the
test
command, the CloudFormation CLI runs the appropriate contract tests, based on which handlers are included in your resource schema.
Defining Property Attributes
Certain properties of a resource may have special meaning when used in different contexts. For example, a given resource property may be read-only when read back for state changes, but can be specified when used as the target of a $ref from a related resource. Because of this semantic difference in how this property metadata should be interpreted, certain property attributes are defined at the resource level, rather than at a property level.
These attributes include:
-
primaryIdentifier
-
additionalIdentifiers
-
createOnlyProperties
-
readOnlyProperties
-
writeOnlyProperties
For reference information on resource schema elements, see Resource type schema.
How to Define a Minimal Resource
The example below displays a minimal resource type definition. In this case, the
resource consists of a single optional property, Name
, which is also
specified as its primary (and only) identifier.
Note that this resource schema would require a handlers
section with the
create, read, and update handlers specified in order for the resource to actually
be
provisioned within a CloudFormation account.
{ "typeName": "myORG::myService::myResource", "properties": { "Name": { "description": "The name of the resource.", "type": "string", "pattern": "^[a-zA-Z0-9_-]{0,64}$", "maxLength": 64 } }, "createOnlyProperties": [ "/properties/Name" ], "identifiers": [ [ "/properties/Name" ] ], "additionalProperties": false }