From ef95336c3301401a7e63d540c33a6faeeba541e7 Mon Sep 17 00:00:00 2001 From: Reuben Miller Date: Tue, 16 Jul 2024 17:21:26 +0200 Subject: [PATCH] improve aws connection docs with user context and reformatting structure Signed-off-by: Reuben Miller --- docs/src/start/connect-aws.md | 188 ++++++++++++++++++++++++++++------ 1 file changed, 157 insertions(+), 31 deletions(-) diff --git a/docs/src/start/connect-aws.md b/docs/src/start/connect-aws.md index ea1b1a6627d..e973cd818a2 100644 --- a/docs/src/start/connect-aws.md +++ b/docs/src/start/connect-aws.md @@ -5,6 +5,21 @@ sidebar_position: 4 description: Connect %%te%% to AWS IoT and publish telemetry data --- +import UserContext from '@site/src/components/UserContext'; +import UserContextForm from '@site/src/components/UserContextForm'; + +:::tip +#### User Context {#user-context} + +You can customize the documentation and commands shown on this page by providing relevant settings which will be reflected in the instructions. It makes it even easier to explore and use %%te%%. + + + +The user context will be persisted in your web browser's local storage. +::: + +### Overview + The very first step to enable %%te%% is to connect your device to the cloud. * This is a 10 minutes operation to be done only once. @@ -23,7 +38,7 @@ Before you try to connect your device to AWS IoT, you need: You can now use [`tedge` command](../references/cli/index.md) to: * [create a certificate for your device](#create-certificate), -* [register the device on AWS IoT Hub](#register), +* [register the device on AWS IoT Core](#register), * [configure the device](#configure), * [connect the device](#connect), and * [send your first telemetry data](#send). @@ -37,10 +52,15 @@ This identifier will be used to uniquely identify your devices among others in y This identifier will be also used as the Common Name (CN) of the certificate. Indeed, this certificate aims to authenticate that this device is the device with that identity. + + + ```sh -sudo tedge cert create --device-id my-device +sudo tedge cert create --device-id $DEVICE_ID ``` + + ## Show certificate details You can then check the content of that certificate. @@ -49,83 +69,180 @@ You can then check the content of that certificate. sudo tedge cert show ``` + + ```text title="Output" Device certificate: /etc/tedge/device-certs/tedge-certificate.pem -Subject: CN=my-device, O=Thin Edge, OU=Test Device -Issuer: CN=my-device, O=Thin Edge, OU=Test Device +Subject: CN=$DEVICE_ID, O=Thin Edge, OU=Test Device +Issuer: CN=$DEVICE_ID, O=Thin Edge, OU=Test Device Valid from: Tue, 09 Mar 2021 14:10:30 +0000 Valid up to: Thu, 10 Mar 2022 14:10:30 +0000 Thumbprint: 860218AD0A996004449521E2713C28F67B5EA580 ``` + + You may notice that the issuer of this certificate is the device itself. This is a self-signed certificate. To use a certificate signed by your Certificate Authority, see the reference guide of [`tedge cert`](../references/cli/tedge-cert.md). -## Register the device on AWS IoT Hub {#register} +## Register the device on AWS IoT Core {#register} For a device to be trusted by AWS, one needs a device certificate and the `tedge cert create` command is the simplest way to get one. Also a policy needs to be attached to the device certificate in AWS IoT Core. AWS IoT Core policies determine what an authenticated identity can do (here the authenticated identity is the device being connected). More info on AWS IoT Core policies can be found [here](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html). -To create a new policy, head over to the AWS IoT Core and navigate to +### Create new policy -**Security → Policies → Create policy → Policy properties → Policy name → Enter the name of your policy (e.g.tedge)** +Before you can register any devices, you must create a policy which can be assigned to each new device during the registration process. The policy grants permissions to the devices to be able to write to specific MQTT topics. -On the Policy statements tab click on ***JSON*** and enter the policy in the ***Policy document*** (an example policy can be found [here](https://raw.githubusercontent.com/thin-edge/thin-edge.io/main/docs/src/start/aws-example-policy.json)) then click ***Create***. +1. Open your AWS IoT Core -In the AWS IoT Core, navigate to ***Manage → All devices → Things → Create things → Create Single thing → Next***. Enter the Thing name which can be obtained from the device with the output of the following command: +2. Navigate to the Policies section under **Security** → **Policies** -```sh -tedge config get device.id -``` +3. Click **Create policy**, and enter a policy name (e.g. `thin-edge.io`) + +4. Under the **Policy statements** tab click on ***JSON*** and add the following JSON: + + :::tip + If you haven't provided the [User Context](#user-context) then it is strongly encouraged to do so, as the following snippet will be updated to reflect your AWS IoT Core settings. + ::: + + + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "iot:Connect", + "Resource": "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:client/${iot:Connection.Thing.ThingName}" + }, + { + "Effect": "Allow", + "Action": "iot:Subscribe", + "Resource": [ + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topicfilter/thinedge/${iot:Connection.Thing.ThingName}/cmd/#", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topicfilter/$aws/things/${iot:Connection.Thing.ThingName}/shadow/#", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topicfilter/thinedge/devices/${iot:Connection.Thing.ThingName}/test-connection" + ] + }, + { + "Effect": "Allow", + "Action": "iot:Receive", + "Resource": [ + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/${iot:Connection.Thing.ThingName}/cmd", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/${iot:Connection.Thing.ThingName}/cmd/*", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/devices/${iot:Connection.Thing.ThingName}/test-connection" + ] + }, + { + "Effect": "Allow", + "Action": "iot:Publish", + "Resource": [ + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/${iot:Connection.Thing.ThingName}/td", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/${iot:Connection.Thing.ThingName}/td/*", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/devices/${iot:Connection.Thing.ThingName}/test-connection" + ] + } + ] + } + ``` + + + + :::info + A static form of the example policy can be downloaded from the [repository](https://raw.githubusercontent.com/thin-edge/thin-edge.io/main/docs/src/start/aws-example-policy.json), though you will need to replace the `` and `` placeholders with your AWS IoT Core values. + ::: + +4. Click **Create** -In the Device Shadow section which allows connected devices to sync states with AWS choose ***Unnamed shadow (classic)*** and click ***Next*** and ***Configure device certificate - optional*** page opens. +### Registering a Device (thing) -At ***Device certificate*** choose ***Use my certificate → CA is not registered with AWS IoT*** then ***Choose file*** and select your tedge-certificate.pem file, click on ***Open → Next***. +1. Open the AWS IoT Core page -The last step needed is to attach previously created policy to your certificate, **Attach policies to certificate -optional** → Select your created policy **→ Create thing**. +2. Navigate to **Manage** → **All devices** → **Things** + +3. Click **Create things**, select the **Create single thing** option, then click **Next** + +4. Enter the device name (e.g. Thing name) + + + + ``` + $DEVICE_ID + ``` + + + + :::tip + The thing name must match the device certificate's Common Name. If you are unsure what the value is, then you can check the common name of the device by using the following `tedge` command: + + ```sh + tedge config get device.id + ``` + ::: + +4. Select the ***Unnamed shadow (classic)*** option and click ***Next*** + +5. On the ***Device certificate*** page, choose ***Use my certificate → CA is not registered with AWS IoT*** + +6. ***Choose file*** and select your `tedge-certificate.pem` file, click on ***Open → Next*** + + If you haven't previously downloaded the public device certificate, you can print the contents (don't worry this is not sensitive information), and then you can save the certificate's contents to a file on your computer so it can be uploaded to AWS. + + You can print the public certificate to the console using the following command: + + ```sh + cat /etc/tedge/device-certs/tedge-certificate.pem + ``` + +7. On the **Policies** page, select the previously created policy, e.g. `thin-edge.io`, then click **Create thing** ## Configure the device {#configure} -To connect the device to the AWS IoT Hub, one needs to set the URL of the IoT Hub and the root certificate of the IoT +To connect the device to the AWS IoT Core, one needs to set the URL of the IoT Hub and the root certificate of the IoT Hub as below. -Set the URL of your AWS IoT Hub. +Set the URL of your AWS IoT Core. + + ```sh -sudo tedge config set aws.url "${AWS_URL}" +sudo tedge config set aws.url "$AWS_URL" ``` -```sh title="Example" -sudo tedge config set aws.url "a2e8ahbpo21syc.iot.eu-central-1.amazonaws.com" -``` + The URL is unique to the AWS account and region that is used, and can be found in the AWS IoT Core by navigating to -"Settings". It will be listed under "Device data endpoint" (e.g. `a2e8ahbpo21syc.iot.eu-central-1.amazonaws.com`) +**Settings**. It will be listed under **Device data endpoint**. -Set the path to the root certificate if necessary. The default is `/etc/ssl/certs`. -```sh -sudo tedge config set aws.root_cert_path /etc/ssl/certs/AmazonRootCA1.pem -``` +:::note +The Amazon's public root certificate for your region's AWS IoT Core needs to be present in your ca-certificate store for the communication to the cloud to be trusted. -This will set the root certificate path of the AWS IoT Hub. In most of the Linux flavors, the certificate will be -present in /etc/ssl/certs. If not found download it from -[here](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html#server-authentication-certs). +In most of the Linux flavors, the certificate will be present in `/etc/ssl/certs` directory. If the certificate is not present, then you can download it manually from +[Amazon](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html#server-authentication-certs) and add it to your system's ca-certificate store by following the +[Adding a root certificate](../operate/security/cloud-authentication.md#adding-a-root-certificate) documentation. +::: ## Connect the device {#connect} -Now, you are ready to get your device connected to AWS IoT Hub with `tedge connect aws`. +Now, you are ready to get your device connected to AWS IoT Core with `tedge connect aws`. This command configures the MQTT broker: * to establish a permanent and secure connection to the AWS cloud, * to forward local messages to the cloud and vice versa. Also, if you have installed `tedge-mapper`, this command starts and enables the tedge-mapper-aws systemd service. -At last, it sends packets to AWS IoT Hub to check the connection. +At last, it sends packets to AWS IoT Core to check the connection. ```sh sudo tedge connect aws @@ -198,6 +315,15 @@ tedge-mapper-aws service successfully started and enabled! ``` +:::tip +If you having troubles with the connection, then check the following items: + +* Check that the policy is attached to the device's certificate +* Check that the policy includes your AWS IoT Core's region and account id +* Check [Amazon diagnosing connectivity issues](https://docs.aws.amazon.com/iot/latest/developerguide/diagnosing-connectivity-issues.html) documentation for further debugging steps +* Check the mosquitto logs for errors, e.g. "verify" errors would indicate that you are missing Amazon's root certificate in the ca-certificate store +::: + ## Sending your first telemetry data {#send} Using the AWS mapper, you can publish measurement telemetry data to AWS by publishing on the `te/device/main///m/` topic: