Step 5: Create your component in the Amazon IoT Greengrass service

When you finish developing a component on your core device, you can upload it to the Amazon IoT Greengrass service in the Amazon Web Services Cloud. You can also directly create the component in the Amazon IoT Greengrass console. Amazon IoT Greengrass provides a component management service that hosts your components so that you can deploy them to individual devices or fleets of devices. To upload a component to the Amazon IoT Greengrass service, you complete the following steps:

Upload component artifacts to an S3 bucket.
Add each artifact's Amazon Simple Storage Service (Amazon S3) URI to the component recipe.
Create a component in Amazon IoT Greengrass from the component recipe.

In this section, you complete these steps on your Greengrass core device to upload your Hello World component to the Amazon IoT Greengrass service.

Use an S3 bucket in your Amazon account to host Amazon IoT Greengrass component artifacts. When you deploy the component to a core device, the device downloads the component's artifacts from the bucket.

You can use an existing S3 bucket, or you can create a new bucket.
1. In the Amazon S3 console, under Buckets, choose Create bucket.
2. For Bucket name, enter a unique bucket name. For example, you can use greengrass-component-artifacts-region-123456789012. Replace 123456789012 with your Amazon account ID and region with the Amazon Web Services Region that you use for this tutorial.
3. For Amazon region, select the Amazon Region that you use for this tutorial.
4. Choose Create bucket.
5. Under Buckets, choose the bucket that you created, upload the hello_world.py script to the artifacts/com.example.HelloWorld/1.0.0 folder in the bucket. For information about uploading objects to S3 buckets, see Uploading objects in the Amazon Simple Storage Service User Guide.
6. Copy the S3 URI of the hello_world.py object in the S3 bucket. This URI should look similar to the following example. Replace DOC-EXAMPLE-BUCKET with the name of the S3 bucket.
```
s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py
```
Allow the core device to access component artifacts in the S3 bucket.

Each core device has a core device IAM role that allows it to interact with Amazon IoT and send logs to the Amazon Cloud. This device role doesn't allow access to S3 buckets by default, so you must create and attach a policy that allows the core device to retrieve component artifacts from the S3 bucket.

If your device's role already allows access to the S3 bucket, you can skip this step. Otherwise, create an IAM policy that allows access and attach it to the role, as follows:
1. In the IAM console navigation menu, choose Policies, and then choose Create policy.
2. On the JSON tab, replace the placeholder content with the following policy. Replace DOC-EXAMPLE-BUCKET with the name of the S3 bucket that contains component artifacts for the core device to download.
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": "arn:aws-cn:s3:::DOC-EXAMPLE-BUCKET/*"
    }
  ]
}
```
3. Choose Next.
4. In the Policy details section, for Name, enter MyGreengrassV2ComponentArtifactPolicy.
5. Choose Create policy.
6. In the IAM console navigation menu, choose Role, and then choose the name of the role for the core device. You specified this role name when you installed the Amazon IoT Greengrass Core software. If you did not specify a name, the default is GreengrassV2TokenExchangeRole.
7. Under Permissions, choose Add permissions, then choose Attach policies.
8. On the Add permissions page, select the check box next to the MyGreengrassV2ComponentArtifactPolicy policy that you created, and then choose Add permissions.

Use the component recipe to create a component in the Amazon IoT Greengrass console.

In the Amazon IoT Greengrass console navigation menu, choose Components, and then choose Create component.

Under Component information, choose Enter recipe as JSON. The placeholder recipe should look similar to the following example.


{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.HelloWorld",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "My first Amazon IoT Greengrass component.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "Message": "world"
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux"
      },
      "Lifecycle": {
        "run": "python3 -u {artifacts:path}/hello_world.py \"{configuration:/Message}\""
      },
      "Artifacts": [
        {
          "URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py"
        }
      ]
    },
    {
      "Platform": {
        "os": "windows"
      },
      "Lifecycle": {
        "run": "py -3 -u {artifacts:path}/hello_world.py \"{configuration:/Message}\""
      },
      "Artifacts": [
        {
          "URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py"
        }
      ]
    }
  ]
}

Replace the placeholder URI in each Artifacts section with S3 URI of your hello_world.py object.
Choose Create component.
On the com.example.HelloWorld component page, verify that the Status of the component is Deployable.

To upload your Hello World component

Use an S3 bucket in your Amazon Web Services account to host Amazon IoT Greengrass component artifacts. When you deploy the component to a core device, the device downloads the component's artifacts from the bucket.

You can use an existing S3 bucket, or run the following command to create a bucket. This command creates a bucket with your Amazon Web Services account ID and Amazon Web Services Region to form a unique bucket name. Replace 123456789012 with your Amazon Web Services account ID and region with the Amazon Web Services Region that you use for this tutorial.
```
aws s3 mb s3://greengrass-component-artifacts-123456789012-region
```
The command outputs the following information if the request succeeds.
```
make_bucket: greengrass-component-artifacts-123456789012-region
```
Allow the core device to access component artifacts in the S3 bucket.

Each core device has a core device IAM role that allows it to interact with Amazon IoT and send logs to the Amazon Web Services Cloud. This device role doesn't allow access to S3 buckets by default, so you must create and attach a policy that allows the core device to retrieve component artifacts from the S3 bucket.

If the core device's role already allows access to the S3 bucket, you can skip this step. Otherwise, create an IAM policy that allows access and attach it to the role, as follows:
1. Create a file called component-artifact-policy.json and copy the following JSON into the file. This policy allows access to all files in an S3 bucket. Replace DOC-EXAMPLE-BUCKET with the name of the S3 bucket.
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": "arn:aws:s3:::DOC-EXAMPLE-BUCKET/*"
    }
  ]
}
```
2. Run the following command to create the policy from the policy document in component-artifact-policy.json.
  Linux or Unix
  aws iam create-policy \\ --policy-name MyGreengrassV2ComponentArtifactPolicy \\ --policy-document file://component-artifact-policy.json
  Windows Command Prompt (CMD)
  aws iam create-policy ^ --policy-name MyGreengrassV2ComponentArtifactPolicy ^ --policy-document file://component-artifact-policy.json
  PowerShell
  aws iam create-policy ` --policy-name MyGreengrassV2ComponentArtifactPolicy ` --policy-document file://component-artifact-policy.json
  Copy the policy Amazon Resource Name (ARN) from the policy metadata in the output. You use this ARN to attach this policy to the core device role in the next step.
3. Run the following command to attach the policy to the core device role. Replace GreengrassV2TokenExchangeRole with the name of the role for the core device. You specified this role name when you installed the Amazon IoT Greengrass Core software. Replace the policy ARN with the ARN from the previous step.
  Linux or Unix
  aws iam attach-role-policy \\ --role-name GreengrassV2TokenExchangeRole \\ --policy-arn arn:aws-cn:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy
  Windows Command Prompt (CMD)
  aws iam attach-role-policy ^ --role-name GreengrassV2TokenExchangeRole ^ --policy-arn arn:aws-cn:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy
  PowerShell
  aws iam attach-role-policy ` --role-name GreengrassV2TokenExchangeRole ` --policy-arn arn:aws-cn:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy
  If the command has no output, it succeeded. The core device can now access artifacts that you upload to this S3 bucket.

Upload the Hello World Python script artifact to the S3 bucket.

Run the following command to upload the script to the same path in the bucket where the script exists on your Amazon IoT Greengrass core. Replace DOC-EXAMPLE-BUCKET with the name of the S3 bucket.

The command outputs a line that starts with upload: if the request succeeds.

Add the artifact's Amazon S3 URI to the component recipe.

The Amazon S3 URI is composed of the bucket name and the path to the artifact object in the bucket. Your script artifact's Amazon S3 URI is the URI that you upload the artifact to in the previous step. This URI should look similar to the following example. Replace DOC-EXAMPLE-BUCKET with the name of the S3 bucket.


s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py

To add the artifact to the recipe, add a list of Artifacts that contains a structure with the Amazon S3 URI.

JSON


"Artifacts": [
  {
    "URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py"
  }
]

Open the recipe file in a text editor.

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


nano recipes/com.example.HelloWorld-1.0.0.json

Add the artifact to the recipe. Your recipe file should look similar to the following example.


{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.HelloWorld",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "My first Amazon IoT Greengrass component.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "Message": "world"
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux"
      },
      "Lifecycle": {
        "run": "python3 -u {artifacts:path}/hello_world.py \"{configuration:/Message}\""
      },
      "Artifacts": [
        {
          "URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py"
        }
      ]
    },
    {
      "Platform": {
        "os": "windows"
      },
      "Lifecycle": {
        "run": "py -3 -u {artifacts:path}/hello_world.py \"{configuration:/Message}\""
      },
      "Artifacts": [
        {
          "URI": "s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py"
        }
      ]
    }
  ]
}

YAML


Artifacts:
  - URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py

Open the recipe file in a text editor.

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


nano recipes/com.example.HelloWorld-1.0.0.yaml

Add the artifact to the recipe. Your recipe file should look similar to the following example.


---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.HelloWorld
ComponentVersion: '1.0.0'
ComponentDescription: My first Amazon IoT Greengrass component.
ComponentPublisher: Amazon
ComponentConfiguration:
  DefaultConfiguration:
    Message: world
Manifests:
  - Platform:
      os: linux
    Lifecycle:
      run: |
        python3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
    Artifacts:
      - URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py
  - Platform:
      os: windows
    Lifecycle:
      run: |
        py -3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
    Artifacts:
      - URI: s3://DOC-EXAMPLE-BUCKET/artifacts/com.example.HelloWorld/1.0.0/hello_world.py

Create a component resource in Amazon IoT Greengrass from the recipe. Run the following command to create the component from the recipe, which you provide as a binary file.

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


{
  "arn": "arn:aws-cn:greengrass:region:123456789012:components:com.example.HelloWorld:versions:1.0.0",
  "componentName": "com.example.HelloWorld",
  "componentVersion": "1.0.0",
  "creationTimestamp": "Mon Nov 30 09:04:05 UTC 2020",
  "status": {
    "componentState": "REQUESTED",
    "message": "NONE",
    "errors": {}
  }
}

Copy the arn from the output to check the state of the component in the next step.

Note

You can also see your Hello World component in the Amazon IoT Greengrass console on the Components page.

Verify that the component creates and is ready to be deployed. When you create a component, its state is REQUESTED. Then, Amazon IoT Greengrass validates that the component is deployable. You can run the following command to query the component status and verify that your component is deployable. Replace the arn with the ARN from the previous step.


aws greengrassv2 describe-component --arn "arn:aws-cn:greengrass:region:123456789012:components:com.example.HelloWorld:versions:1.0.0"

If the component validates, the response indicates that the component state is DEPLOYABLE.


{
  "arn": "arn:aws-cn:greengrass:region:123456789012:components:com.example.HelloWorld:versions:1.0.0",
  "componentName": "com.example.HelloWorld",
  "componentVersion": "1.0.0",
  "creationTimestamp": "2020-11-30T18:04:05.823Z",
  "publisher": "Amazon",
  "description": "My first Greengrass component.",
  "status": {
    "componentState": "DEPLOYABLE",
    "message": "NONE",
    "errors": {}
  },
  "platforms": [
    {
      "os": "linux",
      "architecture": "all"
    }
  ]
}

Your Hello World component is now available in Amazon IoT Greengrass. You can deploy it back to this Greengrass core device or to other core devices.

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Step 4: Develop and test a component on your device

Step 6: Deploy your component