Run Amazon IoT Greengrass in a Docker container with manual resource provisioning

1. Get the Amazon IoT data endpoint for your Amazon Web Services account.

   aws iot describe-endpoint --endpoint-type iot:Data-ATS

   The response looks similar to the following example, if the request succeeds.

   {
     "endpointAddress": "device-data-prefix-ats.iot.us-west-2.amazonaws.com"
   }

2. Get the Amazon IoT credentials endpoint for your Amazon Web Services account.

   aws iot describe-endpoint --endpoint-type iot:CredentialProvider

   The response looks similar to the following example, if the request succeeds.

   {
     "endpointAddress": "device-credentials-prefix.credentials.iot.us-west-2.amazonaws.com"
   }

To create an Amazon IoT thing

1. Create an Amazon IoT thing for your device. On your development computer, run the following command.

   • Replace MyGreengrassCore with the thing name to use. This name is also the name of your Greengrass core device.

     Note

     The thing name can't contain colon (:) characters.

   aws iot create-thing --thing-name MyGreengrassCore

   The response looks similar to the following example, if the request succeeds.

   {
     "thingName": "MyGreengrassCore",
     "thingArn": "arn:aws-cn:iot:us-west-2:123456789012:thing/MyGreengrassCore",
     "thingId": "8cb4b6cd-268e-495d-b5b9-1713d71dbf42"
   }

2. (Optional) Add the Amazon IoT thing to a new or existing thing group. You use thing groups to manage fleets of Greengrass core devices. When you deploy software components to your devices, you can target individual devices or groups of devices. You can add a device to a thing group with an active Greengrass deployment to deploy that thing group's software components to the device. Do the following:

   1. (Optional) Create an Amazon IoT thing group.

      • Replace MyGreengrassCoreGroup with the name of the thing group to create.

        Note

        The thing group name can't contain colon (:) characters.

      aws iot create-thing-group --thing-group-name MyGreengrassCoreGroup

      The response looks similar to the following example, if the request succeeds.

      {
        "thingGroupName": "MyGreengrassCoreGroup",
        "thingGroupArn": "arn:aws-cn:iot:us-west-2:123456789012:thinggroup/MyGreengrassCoreGroup",
        "thingGroupId": "4df721e1-ff9f-4f97-92dd-02db4e3f03aa"
      }

   2. Add the Amazon IoT thing to a thing group.

      • Replace MyGreengrassCore with the name of your Amazon IoT thing.

      • Replace MyGreengrassCoreGroup with the name of the thing group.

      aws iot add-thing-to-thing-group --thing-name MyGreengrassCore --thing-group-name MyGreengrassCoreGroup

      The command doesn't have any output if the request succeeds.

To create the thing certificate

1. Create a folder where you download the certificates for the Amazon IoT thing.

   mkdir greengrass-v2-certs

2. Create and download the certificates for the Amazon IoT thing.

   aws iot create-keys-and-certificate --set-as-active --certificate-pem-outfile greengrass-v2-certs/device.pem.crt --public-key-outfile greengrass-v2-certs/public.pem.key --private-key-outfile greengrass-v2-certs/private.pem.key

   The response looks similar to the following example, if the request succeeds.

   {
     "certificateArn": "arn:aws-cn:iot:us-west-2:123456789012:cert/aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4",
     "certificateId": "aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4",
     "certificatePem": "-----BEGIN CERTIFICATE-----
   MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w
    0BAQUFADCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZ
    WF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIw
    EAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5
    jb20wHhcNMTEwNDI1MjA0NTIxWhcNMTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBh
    MCVVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBb
    WF6b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMx
    HzAdBgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wgZ8wDQYJKoZIhvcNAQE
    BBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ21uUSfwfEvySWtC2XADZ4nB+BLYgVI
    k60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9TrDHudUZg3qX4waLG5M43q7Wgc/MbQ
    ITxOUSQv7c7ugFFDzQGBzZswY6786m86gpEIbb3OhjZnzcvQAaRHhdlQWIMm2nr
    AgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4nUhVVxYUntneD9+h8Mg9q6q+auN
    KyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0FkbFFBjvSfpJIlJ00zbhNYS5f6Guo
    EDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTbNYiytVbZPQUQ5Yaxu2jXnimvw
    3rrszlaEXAMPLE=
   -----END CERTIFICATE-----",
     "keyPair": {
       "PublicKey": "-----BEGIN PUBLIC KEY-----\
   MIIBIjANBgkqhkEXAMPLEQEFAAOCAQ8AMIIBCgKCAQEAEXAMPLE1nnyJwKSMHw4h\
   MMEXAMPLEuuN/dMAS3fyce8DW/4+EXAMPLEyjmoF/YVF/gHr99VEEXAMPLE5VF13\
   59VK7cEXAMPLE67GK+y+jikqXOgHh/xJTwo+sGpWEXAMPLEDz18xOd2ka4tCzuWEXAMPLEahJbYkCPUBSU8opVkR7qkEXAMPLE1DR6sx2HocliOOLtu6Fkw91swQWEXAMPLE\\GB3ZPrNh0PzQYvjUStZeccyNCx2EXAMPLEvp9mQOUXP6plfgxwKRX2fEXAMPLEDa\
   hJLXkX3rHU2xbxJSq7D+XEXAMPLEcw+LyFhI5mgFRl88eGdsAEXAMPLElnI9EesG\
   FQIDAQAB\
   -----END PUBLIC KEY-----\
   ",
       "PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\
   key omitted for security reasons\
   -----END RSA PRIVATE KEY-----\
   "
     }
   }

   Save the certificate's Amazon Resource Name (ARN) to use to configure the certificate later.

To configure the thing's certificate

1. Attach the certificate to the Amazon IoT thing.

   • Replace MyGreengrassCore with the name of your Amazon IoT thing.

   • Replace the certificate Amazon Resource Name (ARN) with the ARN of the certificate that you created in the previous step.

   aws iot attach-thing-principal --thing-name MyGreengrassCore --principal arn:aws-cn:iot:us-west-2:123456789012:cert/aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4

   The command doesn't have any output if the request succeeds.

2. Create and attach an Amazon IoT policy that defines the Amazon IoT permissions for your Greengrass core device. The following policy allows access to all MQTT topics and Greengrass operations, so your device works with custom applications and future changes that require new Greengrass operations. You can restrict this policy down based on your use case. For more information, see Minimal Amazon IoT policy for Amazon IoT Greengrass V2 core devices.

   If you have set up a Greengrass core device before, you can attach its Amazon IoT policy instead of creating a new one.

   Do the following:

   1. Create a file that contains the Amazon IoT policy document that Greengrass core devices require.

      For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.

      nano greengrass-v2-iot-policy.json

      Copy the following JSON into the file.

      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Action": [
              "iot:Publish",
              "iot:Subscribe",
              "iot:Receive",
              "iot:Connect",
              "greengrass:*"
            ],
            "Resource": [
              "*"
            ]
          }
        ]
      }

   2. Create an Amazon IoT policy from the policy document.

      • Replace GreengrassV2IoTThingPolicy with the name of the policy to create.

      aws iot create-policy --policy-name GreengrassV2IoTThingPolicy --policy-document file://greengrass-v2-iot-policy.json

      The response looks similar to the following example, if the request succeeds.

      {
        "policyName": "GreengrassV2IoTThingPolicy",
        "policyArn": "arn:aws-cn:iot:us-west-2:123456789012:policy/GreengrassV2IoTThingPolicy",
        "policyDocument": "{
          \\"Version\\": \\"2012-10-17\\",
          \\"Statement\\": [
            {
              \\"Effect\\": \\"Allow\\",
              \\"Action\\": [
                \\"iot:Publish\\",
                \\"iot:Subscribe\\",
                \\"iot:Receive\\",
                \\"iot:Connect\\",
                \\"greengrass:*\\"
              ],
              \\"Resource\\": [
                \\"*\\"
              ]
            }
          ]
        }",
        "policyVersionId": "1"
      }

   3. Attach the Amazon IoT policy to the Amazon IoT thing's certificate.

      • Replace GreengrassV2IoTThingPolicy with the name of the policy to attach.

      • Replace the target ARN with the ARN of the certificate for your Amazon IoT thing.

      aws iot attach-policy --policy-name GreengrassV2IoTThingPolicy --target arn:aws-cn:iot:us-west-2:123456789012:cert/aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4

      The command doesn't have any output if the request succeeds.

To create a token exchange IAM role

1. Create an IAM role that your device can use as a token exchange role. Do the following:

   1. Create a file that contains the trust policy document that the token exchange role requires.

      For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.

      nano device-role-trust-policy.json

      Copy the following JSON into the file.

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

   2. Create the token exchange role with the trust policy document.

      • Replace GreengrassV2TokenExchangeRole with the name of the IAM role to create.

      aws iam create-role --role-name GreengrassV2TokenExchangeRole --assume-role-policy-document file://device-role-trust-policy.json

      The response looks similar to the following example, if the request succeeds.

      {
        "Role": {
          "Path": "/",
          "RoleName": "GreengrassV2TokenExchangeRole",
          "RoleId": "AROAZ2YMUHYHK5OKM77FB",
          "Arn": "arn:aws-cn:iam::123456789012:role/GreengrassV2TokenExchangeRole",
          "CreateDate": "2021-02-06T00:13:29+00:00",
          "AssumeRolePolicyDocument": {
            "Version": "2012-10-17",
            "Statement": [
              {
                "Effect": "Allow",
                "Principal": {
                  "Service": "credentials.iot.amazonaws.com"
                },
                "Action": "sts:AssumeRole"
              }
            ]
          }
        }

   3. Create a file that contains the access policy document that the token exchange role requires.

      For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.

      nano device-role-access-policy.json

      Copy the following JSON into the file.

      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Action": [
              "logs:CreateLogGroup",
              "logs:CreateLogStream",
              "logs:PutLogEvents",
              "logs:DescribeLogStreams",
              "s3:GetBucketLocation"
            ],
            "Resource": "*"
          }
        ]
      }

      Note

      This access policy doesn't allow access to component artifacts in S3 buckets. To deploy custom components that define artifacts in Amazon S3, you must add permissions to the role to allow your core device to retrieve component artifacts. For more information, see Allow access to S3 buckets for component artifacts.

      If you don't yet have an S3 bucket for component artifacts, you can add these permissions later after you create a bucket.

   4. Create the IAM policy from the policy document.

      • Replace GreengrassV2TokenExchangeRoleAccess with the name of the IAM policy to create.

      aws iam create-policy --policy-name GreengrassV2TokenExchangeRoleAccess --policy-document file://device-role-access-policy.json

      The response looks similar to the following example, if the request succeeds.

      {
        "Policy": {
          "PolicyName": "GreengrassV2TokenExchangeRoleAccess",
          "PolicyId": "ANPAZ2YMUHYHACI7C5Z66",
          "Arn": "arn:aws-cn:iam::123456789012:policy/GreengrassV2TokenExchangeRoleAccess",
          "Path": "/",
          "DefaultVersionId": "v1",
          "AttachmentCount": 0,
          "PermissionsBoundaryUsageCount": 0,
          "IsAttachable": true,
          "CreateDate": "2021-02-06T00:37:17+00:00",
          "UpdateDate": "2021-02-06T00:37:17+00:00"
        }
      }

   5. Attach the IAM policy to the token exchange role.

      • Replace GreengrassV2TokenExchangeRole with the name of the IAM role.

      • Replace the policy ARN with the ARN of the IAM policy that you created in the previous step.

      aws iam attach-role-policy --role-name GreengrassV2TokenExchangeRole --policy-arn arn:aws-cn:iam::123456789012:policy/GreengrassV2TokenExchangeRoleAccess

      The command doesn't have any output if the request succeeds.

2. Create an Amazon IoT role alias that points to the token exchange role.

   • Replace GreengrassCoreTokenExchangeRoleAlias with the name of the role alias to create.

   • Replace the role ARN with the ARN of the IAM role that you created in the previous step.

   aws iot create-role-alias --role-alias GreengrassCoreTokenExchangeRoleAlias --role-arn arn:aws-cn:iam::123456789012:role/GreengrassV2TokenExchangeRole

   The response looks similar to the following example, if the request succeeds.

   {
     "roleAlias": "GreengrassCoreTokenExchangeRoleAlias",
     "roleAliasArn": "arn:aws-cn:iot:us-west-2:123456789012:rolealias/GreengrassCoreTokenExchangeRoleAlias"
   }

   Note

   To create a role alias, you must have permission to pass the token exchange IAM role to Amazon IoT. If you receive an error message when you try to create a role alias, check that your Amazon user has this permission. For more information, see Granting a user permissions to pass a role to an Amazon service in the Amazon Identity and Access Management User Guide.

3. Create and attach an Amazon IoT policy that allows your Greengrass core device to use the role alias to assume the token exchange role. If you have set up a Greengrass core device before, you can attach its role alias Amazon IoT policy instead of creating a new one. Do the following:

   1. (Optional) Create a file that contains the Amazon IoT policy document that the role alias requires.

      For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.

      nano greengrass-v2-iot-role-alias-policy.json

      Copy the following JSON into the file.

      • Replace the resource ARN with the ARN of your role alias.

      {
        "Version":"2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Action": "iot:AssumeRoleWithCertificate",
            "Resource": "arn:aws-cn:iot:us-west-2:123456789012:rolealias/GreengrassCoreTokenExchangeRoleAlias"
          }
        ]
      }

   2. Create an Amazon IoT policy from the policy document.

      • Replace GreengrassCoreTokenExchangeRoleAliasPolicy with the name of the Amazon IoT policy to create.

      aws iot create-policy --policy-name GreengrassCoreTokenExchangeRoleAliasPolicy --policy-document file://greengrass-v2-iot-role-alias-policy.json

      The response looks similar to the following example, if the request succeeds.

      {
        "policyName": "GreengrassCoreTokenExchangeRoleAliasPolicy",
        "policyArn": "arn:aws-cn:iot:us-west-2:123456789012:policy/GreengrassCoreTokenExchangeRoleAliasPolicy",
        "policyDocument": "{
          \\"Version\\":\\"2012-10-17\\",
          \\"Statement\\": [
            {
              \\"Effect\\": \\"Allow\\",
              \\"Action\\": \\"iot:AssumeRoleWithCertificate\\",
              \\"Resource\\": \\"arn:aws-cn:iot:us-west-2:123456789012:rolealias/GreengrassCoreTokenExchangeRoleAlias\\"
            }
          ]
        }",
        "policyVersionId": "1"
      }

   3. Attach the Amazon IoT policy to the Amazon IoT thing's certificate.

      • Replace GreengrassCoreTokenExchangeRoleAliasPolicy with the name of the role alias Amazon IoT policy.

      • Replace the target ARN with the ARN of the certificate for your Amazon IoT thing.

      aws iot attach-policy --policy-name GreengrassCoreTokenExchangeRoleAliasPolicy --target arn:aws-cn:iot:us-west-2:123456789012:cert/aa0b7958770878eabe251d8a7ddd547f4889c524c9b574ab9fbf65f32248b1d4

      The command doesn't have any output if the request succeeds.

To download certificates to the device

1. On your development computer, download the Amazon root certificate authority (CA) certificate. Amazon IoT certificates are associated with Amazon's root CA certificate by default.

   Linux or Unix

   sudo curl -o ./greengrass-v2-certs/AmazonRootCA1.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem

   Windows Command Prompt (CMD)

   curl -o .\greengrass-v2-certs\AmazonRootCA1.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem

   PowerShell

   iwr -Uri https://www.amazontrust.com/repository/AmazonRootCA1.pem -OutFile .\greengrass-v2-certs\AmazonRootCA1.pem

2. If you plan to run the Amazon IoT Greengrass Core software in Docker on a different device than your development computer, copy the certificates to the host computer. If SSH and SCP are enabled on the development computer and the host computer, you can use the scp command on your development computer to transfer the certificates. Replace device-ip-address with the IP address of your host computer.

   scp -r greengrass-v2-certs/ device-ip-address:~

1. On the host computer, create a folder where you place your configuration file.

   mkdir ./greengrass-v2-config

2. Use a text editor to create a configuration file named config.yaml in the ./greengrass-v2-config folder.

   For example, you can run the following command to use GNU nano to create the config.yaml.

   nano ./greengrass-v2-config/config.yaml

3. Copy the following YAML content into the file. This partial configuration file specifies system parameters and Greengrass nucleus parameters.

   ---
   system:
     certificateFilePath: "/tmp/certs/device.pem.crt"
     privateKeyPath: "/tmp/certs/private.pem.key"
     rootCaPath: "/tmp/certs/AmazonRootCA1.pem"
     rootpath: "/greengrass/v2"
     thingName: "MyGreengrassCore"
   services:
     aws.greengrass.Nucleus:
       componentType: "NUCLEUS"
       version: "nucleus-version"
       configuration:
         awsRegion: "region"
         iotRoleAlias: "GreengrassCoreTokenExchangeRoleAlias"
         iotDataEndpoint: "device-data-prefix-ats.iot.region.amazonaws.com"
         iotCredEndpoint: "device-credentials-prefix.credentials.region.amazonaws.com"

   Then, replace the following values:

   • /tmp/certs. The directory in the Docker container to which you mount the downloaded certificates when you start the container.

   • /greengrass/v2. The Greengrass root folder that you want to use for installation. You use the GGC_ROOT environment variable to set this value.

   • MyGreengrassCore. The name of the Amazon IoT thing.

   • nucleus-version. The version of the Amazon IoT Greengrass Core software to install. This value must match the version of the Docker image or Dockerfile that you downloaded. If you downloaded the Greengrass Docker image with the latest tag, use docker inspect image-id to see the image version.

   • region. The Amazon Web Services Region where you created your Amazon IoT resources. You must also specify the same value for the AWS_REGION environment variable in your environment file.

   • GreengrassCoreTokenExchangeRoleAlias. The token exchange role alias.

   • device-data-prefix. The prefix for your Amazon IoT data endpoint.

   • device-credentials-prefix. The prefix for your Amazon IoT credentials endpoint.

1. Use a text editor to create an environment file named .env.

   For example, on a Linux-based system, you can run the following command to use GNU nano to create the .env in the current directory.

   nano .env

2. Copy the following content into the file.

   GGC_ROOT_PATH=/greengrass/v2
   AWS_REGION=region
   PROVISION=false
   COMPONENT_DEFAULT_USER=ggc_user:ggc_group
   INIT_CONFIG=/tmp/config/config.yaml

   Then, replace the following values.

   • /greengrass/v2. The path to the root folder to use to install the Amazon IoT Greengrass Core software.

   • region. The Amazon Web Services Region where you created your Amazon IoT resources. You must specify the same value for the awsRegion configuration parameter in your configuration file.

   • /tmp/config/. The folder where you mount the configuration file when you start the Docker container.

   Note

   You can set the DEPLOY_DEV_TOOLS environment variable to true to deploy the Greengrass CLI component, which enables you to develop custom components inside of the Docker container. We recommend that you use this component in only development environments, not production environments. This component provides access to information and operations that you typically won't need in a production environment. Follow the principle of least privilege by deploying this component to only core devices where you need it.