Greengrass discovery RESTful API - AWS IoT Greengrass

Greengrass discovery RESTful API

AWS IoT Greengrass provides the Discover API operation that client devices can use to identify Greengrass core devices where they can connect. Client devices use this data plane operation to retrieve information required to connect to Greengrass core devices where you associate them with the BatchAssociateClientDeviceWithCoreDevice API operation. When a client device comes online, it can connect to the AWS IoT Greengrass cloud service and use the discovery API to find:

  • The IP address and port for each associated Greengrass core device.

  • The core device CA certificate, which client devices can use to authenticate the Greengrass core device.

Note

Client devices can also use the discovery client in the AWS IoT Device SDK to discover connectivity information for Greengrass core devices. The discovery client uses the discovery API. For more information, see the following:

To use this API operation, send HTTP requests to the discovery API on the Greengrass data plane endpoint. This API endpoint has the following format.

https://greengrass-ats.iot.region.amazonaws.com:port/greengrass/discover/thing/thing-name

For a list of supported AWS Regions and endpoints for the AWS IoT Greengrass discovery API, see AWS IoT Greengrass V2 endpoints and quotas in the AWS General Reference. This API operation is available only on the Greengrass data plane endpoint. The control plane endpoint that you use to manage components and deployments is different from the data plane endpoint.

Note

The discovery API is the same for AWS IoT Greengrass V1 and AWS IoT Greengrass V2. If you have client devices that connect to a AWS IoT Greengrass V1 core, you can connect them to AWS IoT Greengrass V2 core devices without changing the code on the client devices. For more information, see Greengrass Discovery RESTful API in the AWS IoT Greengrass Version 1 Developer Guide.

Discovery authentication and authorization

To use the discovery API to retrieve connectivity information, a client device must use TLS mutual authentication with an X.509 client certificate to authenticate. For more information, see X.509 client certificates in the AWS IoT Core Developer Guide.

A client device must also have permission to perform the greengrass:Discover action. The following example AWS IoT policy allows an AWS IoT thing named MyClientDevice1 to perform Discover for itself.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "greengrass:Discover", "Resource": [ "arn:aws:iot:us-west-2:123456789012:thing/MyClientDevice1" ] } ] }
Important

Thing policy variables (iot:Connection.Thing.*) aren't supported for in AWS IoT policies for core devices or Greengrass data plane operations. Instead, you can use a wildcard that matches multiple devices that have similar names. For example, you can specify MyGreengrassDevice* to match MyGreengrassDevice1, MyGreengrassDevice2, and so on.

For more information, see AWS IoT Core policies in the AWS IoT Core Developer Guide.

Request

The request contains the standard HTTP headers and is sent to the Greengrass discovery endpoint, as shown in the following examples.

The port number depends on whether the core device is configured to send HTTPS traffic over port 8443 or port 443. For more information, see Connect on port 443 or through a network proxy.

Note

These examples use the Amazon Trust Services (ATS) endpoint, which works with the recommended ATS root CA certificates. Endpoints must match the root CA certificate type.

Port 8443
HTTP GET https://greengrass-ats.iot.region.amazonaws.com:8443/greengrass/discover/thing/thing-name
Port 443
HTTP GET https://greengrass-ats.iot.region.amazonaws.com:443/greengrass/discover/thing/thing-name
Note

Clients that connect on port 443 must implement the Application Layer Protocol Negotiation (ALPN) TLS extension and pass x-amzn-http-ca as the ProtocolName in the ProtocolNameList. For more information, see Protocols in the AWS IoT Developer Guide.

Response

Upon success, the response includes the standard HTTP headers plus the following code and body:

HTTP 200 BODY: response document

For more information, see Example discover response documents.

Example discover response documents

Because AWS IoT Greengrass V2 uses the same discovery API as AWS IoT Greengrass V1, the response organizes information according to AWS IoT Greengrass V1 concepts, such as Greengrass groups. The response contains a list of Greengrass groups. In AWS IoT Greengrass V2, each core device is in its own group, where the group contains only that core device and its connectivity information.

The following document shows the response for a client device that is associated to one Greengrass core device. The core device has one endpoint and one CA certificate.

{ "GGGroups": [ { "GGGroupId": "greengrassV2-coreDevice-core-device-01-thing-name", "Cores": [ { "thingArn": "core-device-01-thing-arn", "Connectivity": [ { "id": "core-device-01-connection-id", "hostAddress": "core-device-01-address", "portNumber": core-device-01-port, "metadata": "core-device-01-description" } ] } ], "CAs": [ "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----" ] } ] }

The following document shows the response for a client device that is associated to two core devices. The core devices have multiple endpoints and multiple group CA certificates.

{ "GGGroups": [ { "GGGroupId": "greengrassV2-coreDevice-core-device-01-thing-name", "Cores": [ { "thingArn": "core-device-01-thing-arn", "Connectivity": [ { "id": "core-device-01-connection-id", "hostAddress": "core-device-01-address", "portNumber": core-device-01-port, "metadata": "core-device-01-connection-1-description" }, { "id": "core-device-01-connection-id-2", "hostAddress": "core-device-01-address-2", "portNumber": core-device-01-port-2, "metadata": "core-device-01-connection-2-description" } ] } ], "CAs": [ "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----", "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----", "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----" ] }, { "GGGroupId": "greengrassV2-coreDevice-core-device-02-thing-name", "Cores": [ { "thingArn":"core-device-02-thing-arn", "Connectivity" : [ { "id": "core-device-02-connection-id", "hostAddress": "core-device-02-address", "portNumber": core-device-02-port, "metadata": "core-device-02-connection-1-description" } ] } ], "CAs": [ "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----", "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----", "-----BEGIN CERTIFICATE-----cert-contents-----END CERTIFICATE-----" ] } ] }

Test the discovery API with cURL

If you have cURL installed, you can test the discovery API. The following example specifies a client device's certificates to authenticate a request to the Greengrass discovery API endpoint.

curl -i \ --cert 1a23bc4d56.cert.pem \ --key 1a23bc4d56.private.key \ https://greengrass-ats.iot.us-west-2.amazonaws.com:8443/greengrass/discover/thing/MyClientDevice1
Note

The -i argument specifies to output HTTP response headers. You can use this option to help identify errors.

If the request succeeds, this command outputs a response similar to the following example.

{ "GGGroups": [ { "GGGroupId": "greengrassV2-coreDevice-MyGreengrassCore", "Cores": [ { "thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore", "Connectivity": [ { "Id": "AUTOIP_192.168.1.4_1", "HostAddress": "192.168.1.5", "PortNumber": 8883, "Metadata": "" } ] } ], "CAs": [ "-----BEGIN CERTIFICATE-----\ncert-contents\n-----END CERTIFICATE-----\n" ] } ] }

If the command outputs an error, see Troubleshooting Greengrass discovery issues.