Menu
AWS IoT
Developer Guide

Provisioning Templates

A provision template is a JSON document that uses parameters to describe the resources your device must use to interact with AWS IoT. A template contains two sections: Parameters and Resources.

Parameters Section

The Parameters section declares the parameters used within the Resources section. Each parameter declares a name, a type, and an optional default value. The default value is used when the dictionary passed in with the template does not contain a value for the parameter. The Parameters section of a template document looks like the following:

"Parameters" : { "ThingName" : { "Type" : "String", }, "SerialNumber" : { "Type" : "String", }, "Location" : { "Type" : "String", "Default" : "WA" }, "CSR" : { "Type" : "String", } }

This template snippet declares four parameters: ThingName, SerialNumber, Location, and CSR. All of these parameters are of type String. The Location parameter declares a default value of "WA".

Resources Section

The Resources section of the template declares the resources required for your device to communicate with AWS IoT: a thing, a certificate, and one or more policies. Each resource specifies a logical name, a type, and a set of properties.

A logical name allows you to refer to a resource elsewhere in the template.

The type specifies the kind of resource you are declaring. Valid types are:

  • AWS::IoT::Thing

  • AWS::IoT::Certificate

  • AWS::IoT::Policy

The properties you specify depend on the type of resource you are declaring.

Thing Resources

Thing resources are declared using the following properties:

  • ThingName: String.

  • AttributePayload: A list of name/value pairs.

  • ThingTypeName: Optional. String for an associated thing type for the thing.

  • ThingGroups: Optional. A list of groups to which the thing belongs.

Certificate Resources

Certificates can be specified in one of the following ways:

  • A certificate signing request (CSR).

  • A certificate ID of an existing device certificate.

  • A device certificate created with a CA certificate registered with AWS IoT. If you have more than one CA certificate registered with the same subject field, you must also pass in the CA certificate used to sign the device certificate.

Note

When you declare a certificate in a template, use only one of the preceding methods. If you use a CSR, you cannot also specify a certificate ID or a device certificate.

For more information about certificates and AWS IoT see AWS IoT and Certificates.

Certificate resources are declared using the following properties:

  • CertificateSigningRequest: String.

  • CertificatePem: String.

  • CACertificatePem: String.

  • Status: Optional. String that can be one of: ACTIVE, INACTIVE, PENDING_ACTIVATION. Defaults to ACTIVE.

Policy Resources

Policy resources are declared using one the following properties:

  • PolicyName: Optional. String. Defaults to a hash of the policy document.

  • PolicyDocument: a stringified JSON object. Optional. If PolicyDocument is not provided, the policy must already be created.

Note

If a Policy section is present, PolicyName or PolicyDocument, but not both, must be specified.

Override Settings

If a template specifies a resource that already exists, the OverrideSettings section allows you to specify the action to take:

DO_NOTHING

Leave the resource as is.

REPLACE

Replace the resource with the resource specified in the template.

FAIL

Cause the request to fail with a ResourceConflictsException.

MERGE

Valid only for the ThingGroups and AttributePayload properties of a thing. Merge the existing attributes or group memberships of the thing with those specified in the template.

Resource Example

The following template snippet declares a thing, a certificate, and a policy:

"Resources" : { "thing" : { "Type" : "AWS::IoT::Thing", "Properties" : { "ThingName" : {"Ref" : "ThingName"}, "AttributePayload" : { "version" : "v1", "serialNumber" : {"Ref" : "SerialNumber"}}, "ThingTypeName" : "lightBulb-versionA", "ThingGroups" : ["v1-lightbulbs", {"Ref" : "Location"}] }, "OverrideSettings" : { "AttributePayload" : "MERGE", "ThingTypeName" : "REPLACE", "ThingGroups" : "DO_NOTHING" } }, "certificate" : { "Type" : "AWS::IoT::Certificate", "Properties" : { "CertificateSigningRequest": {"Ref" : "CSR"}, "Status" : "ACTIVE" }, "OverrideSettings" : { "Status" : "DO_NOTHING" } }, "policy" : { "Type" : "AWS::IoT::Policy", "Properties" : { "PolicyDocument" : "{ \"Version\": \"2012-10-17\", \"Statement\": [{ \"Effect\": \"Allow\", \"Action\":[\"iot:Publish\"], \"Resource\": [\"arn:aws:iot:us-east-1:123456789012:topic/foo/bar\"] }] }" } } }

The thing is declared with:

  • The logical name "thing".

  • The type AWS::IoT::Thing.

  • A set of thing properties.

    The thing properties include the thing name, a set of attributes, an optional thing type name, and an optional list of thing groups to which the thing will belong.

Parameters are referenced by {"Ref": "<parameter-name>"}. When the template is evaluated, the parameters are replaced with the parameter's value from the dictionary passed in with the template.

The certificate is declared with:

  • The logical name "certificate".

  • The type AWS::IoT::Certificate.

  • A set of properties.

    The properties include the CSR for the certificate, and setting the status to ACTIVE. The CSR text is passed as a parameter in the dictionary passed with the template.

The policy is declared with:

  • The logical name "policy".

  • The type AWS::IoT::Policy.

  • Either the name of an existing policy or a policy document.

Template Example

The following JSON file is an example of a complete provisioning template:

(Note that the PolicyDocument field value must be a stringified JSON object.)

{ "Parameters" : { "ThingName" : { "Type" : "String" }, "SerialNumber" : { "Type" : "String" }, "Location" : { "Type" : "String", "Default" : "WA" }, "CSR" : { "Type" : "String" } }, "Resources" : { "thing" : { "Type" : "AWS::IoT::Thing", "Properties" : { "ThingName" : {"Ref" : "ThingName"}, "AttributePayload" : { "version" : "v1", "serialNumber" : {"Ref" : "SerialNumber"}}, "ThingTypeName" : "lightBulb-versionA", "ThingGroups" : ["v1-lightbulbs", {"Ref" : "Location"}] } }, "certificate" : { "Type" : "AWS::IoT::Certificate", "Properties" : { "CertificateSigningRequest": {"Ref" : "CSR"}, "Status" : "ACTIVE" } }, "policy" : { "Type" : "AWS::IoT::Policy", "Properties" : { "PolicyDocument" : "{ \"Version\": \"2012-10-17\", \"Statement\": [{ \"Effect\": \"Allow\", \"Action\":[\"iot:Publish\"], \"Resource\": [\"arn:aws:iot:us-east-1:123456789012:topic/foo/bar\"] }] }" } } } }