Step 5: Create your component in the AWS IoT Greengrass service - AWS IoT Greengrass

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

When you finish developing a component on your core device, you can upload it to the AWS IoT Greengrass service in the AWS Cloud. You can also directly create the component in the AWS IoT Greengrass console. AWS 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 AWS 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 AWS 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 AWS IoT Greengrass service.

  1. Use an S3 bucket in your AWS account to host AWS 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 AWS account ID and region with the AWS Region that you use for this tutorial.

    3. For AWS region, select the AWS 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 amzn-s3-demo-bucket with the name of the S3 bucket.

      s3://amzn-s3-demo-bucket/artifacts/com.example.HelloWorld/1.0.0/hello_world.py

  2. 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 AWS IoT and send logs to the AWS 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 amzn-s3-demo-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:s3:::amzn-s3-demo-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 AWS 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.

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

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

    2. 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 AWS 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://amzn-s3-demo-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://amzn-s3-demo-bucket/artifacts/com.example.HelloWorld/1.0.0/hello_world.py"
        }
      ]
    }
  ]
}

    3. Replace the placeholder URI in each Artifacts section with S3 URI of your hello_world.py object.

    4. Choose Create component.

    5. On the com.example.HelloWorld component page, verify that the Status of the component is Deployable.

To upload your Hello World component

  1. Use an S3 bucket in your AWS account to host AWS 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 AWS account ID and AWS Region to form a unique bucket name. Replace 123456789012 with your AWS account ID and region with the AWS 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

  2. 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 AWS IoT and send logs to the AWS 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 amzn-s3-demo-bucket with the name of the S3 bucket.

      {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": "arn:aws:s3:::amzn-s3-demo-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 AWS 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:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy
      Windows Command Prompt (CMD)
      aws iam attach-role-policy ^
  --role-name GreengrassV2TokenExchangeRole ^
  --policy-arn arn:aws:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy
      PowerShell
      aws iam attach-role-policy `
  --role-name GreengrassV2TokenExchangeRole `
  --policy-arn arn:aws: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.

  3. 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 AWS IoT Greengrass core. Replace amzn-s3-demo-bucket with the name of the S3 bucket.

    Linux or Unix
    aws s3 cp \
  artifacts/com.example.HelloWorld/1.0.0/hello_world.py \
  s3://amzn-s3-demo-bucket/artifacts/com.example.HelloWorld/1.0.0/hello_world.py
    Windows Command Prompt (CMD)
    aws s3 cp ^
  artifacts/com.example.HelloWorld/1.0.0/hello_world.py ^
  s3://amzn-s3-demo-bucket/artifacts/com.example.HelloWorld/1.0.0/hello_world.py
    PowerShell
    aws s3 cp `
  artifacts/com.example.HelloWorld/1.0.0/hello_world.py `
  s3://amzn-s3-demo-bucket/artifacts/com.example.HelloWorld/1.0.0/hello_world.py

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

  4. 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 amzn-s3-demo-bucket with the name of the S3 bucket.

    s3://amzn-s3-demo-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://amzn-s3-demo-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 AWS 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://amzn-s3-demo-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://amzn-s3-demo-bucket/artifacts/com.example.HelloWorld/1.0.0/hello_world.py"
        }
      ]
    }
  ]
}
    YAML
    Artifacts:
  - URI: s3://amzn-s3-demo-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 AWS 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://amzn-s3-demo-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://amzn-s3-demo-bucket/artifacts/com.example.HelloWorld/1.0.0/hello_world.py

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

    JSON
    aws greengrassv2 create-component-version --inline-recipe fileb://recipes/com.example.HelloWorld-1.0.0.json
    YAML
    aws greengrassv2 create-component-version --inline-recipe fileb://recipes/com.example.HelloWorld-1.0.0.yaml

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

    {
  "arn": "arn:aws: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 AWS IoT Greengrass console on the Components page.

  6. Verify that the component creates and is ready to be deployed. When you create a component, its state is REQUESTED. Then, AWS 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: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: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 AWS IoT Greengrass. You can deploy it back to this Greengrass core device or to other core devices.