Use IP detector to automatically manage endpoints Manually manage endpoints

Manage core device endpoints

When you use cloud discovery, you store MQTT broker endpoints for core devices in the AWS IoT Greengrass cloud service. Client devices connect to AWS IoT Greengrass to retrieve these endpoints and other information for their associated core devices.

For each core device, you can automatically or manually manage endpoints.

Automatically manage endpoints with IP detector

You can deploy the IP detector component to automatically manage core device endpoints for you if you have a non-complex network setup, such as where the client devices are on the same network as the core device. You can't use the IP detector component if the core device is behind a router that forwards the MQTT broker port to the core device, for example.

The IP detector component is also useful if you deploy to thing groups, because it manages the endpoints for all core devices in the thing group. For more information, see Use IP detector to automatically manage endpoints.
Manually manage endpoints

If you can't use the IP detector component, you must manually manage core device endpoints. You can update these endpoints with the console or the API. For more information, see Manually manage endpoints.

Topics

Use IP detector to automatically manage endpoints
Manually manage endpoints

Use IP detector to automatically manage endpoints

If you have a simple network setup, such as the client devices on the same network as the core device, you can deploy the IP detector component to do the following:

Monitor the Greengrass core device's local network connectivity information. This information includes the core device's network endpoints and the port where the MQTT broker operates.
Report the core device's connectivity information to the AWS IoT Greengrass cloud service.

The IP detector component overwrites endpoints that you set manually.

Important

The core device's AWS IoT policy must allow the greengrass:UpdateConnectivityInfo permission to use the IP detector component. For more information, see AWS IoT policies for data plane operations and Configure the AWS IoT thing policy.

You can do either of the following to deploy the IP detector component:

Use the Configure discovery page in the console. For more information, see Configure cloud discovery (console).
Create and revise deployments to include the IP detector. You can use the console, AWS CLI, or AWS API to manage deployments. For more information, see Create deployments.

In the AWS IoT Greengrass console navigation menu, choose Components.
On the Components page, choose the Public components tab, and then choose aws.greengrass.clientdevices.IPDetector.
On the aws.greengrass.clientdevices.IPDetector page, choose Deploy.
From Add to deployment, choose an existing deployment to revise, or choose to create a new deployment, and then choose Next.
If you chose to create a new deployment, choose the target core device or thing group for the deployment. On the Specify target page, under Deployment target, choose a core device or thing group, and then choose Next.
On the Select components page, verify that the aws.greengrass.clientdevices.IPDetector component is selected, choose Next.
On the Configure components page, select aws.greengrass.clientdevices.IPDetector, and then do the following:
1. Choose Configure component.
2. In the Configure aws.greengrass.clientdevices.IPDetector modal, under Configuration update, in Configuration to merge, you can enter a configuration update to configure the IP detector component. You can specify any of the following configuration options:
  - defaultPort – (Optional) The MQTT broker port to report when this component detects IP addresses. You must specify this parameter if you configure the MQTT broker to use a different port than the default port 8883.
  - includeIPv4LoopbackAddrs – (Optional) You can enable this option to detect and report IPv4 loopback addresses. These are IP addresses, such as localhost, where a device can communicate with itself. Use this option in test environments where the core device and client device run on the same system.
  - includeIPv4LinkLocalAddrs – (Optional) You can enable this option to detect and report IPv4 link-local addresses. Use this option if the core device's network doesn't have Dynamic Host Configuration Protocol (DHCP) or statically assigned IP addresses.
  The configuration update might look similar to the following example.
```
{
  "defaultPort": "8883",
  "includeIPv4LoopbackAddrs": false,
  "includeIPv4LinkLocalAddrs": false
}
```
3. Choose Confirm to close the modal, and then choose Next.
On the Configure advanced settings page, keep the default configuration settings, and choose Next.
On the Review page, choose Deploy.

The deployment can take up to a minute to complete.

To deploy the IP detector component, create a deployment document that includes aws.greengrass.clientdevices.IPDetector in the components object, and specify the configuration update for the component. Follow instructions in Create deployments to create a new deployment or revise an existing deployment.

You can specify any of the following options to configure the IP detector component when you create the deployment document:

defaultPort – (Optional) The MQTT broker port to report when this component detects IP addresses. You must specify this parameter if you configure the MQTT broker to use a different port than the default port 8883.
includeIPv4LoopbackAddrs – (Optional) You can enable this option to detect and report IPv4 loopback addresses. These are IP addresses, such as localhost, where a device can communicate with itself. Use this option in test environments where the core device and client device run on the same system.
includeIPv4LinkLocalAddrs – (Optional) You can enable this option to detect and report IPv4 link-local addresses. Use this option if the core device's network doesn't have Dynamic Host Configuration Protocol (DHCP) or statically assigned IP addresses.

The following example partial deployment document specifies to report port 8883 as the MQTT broker port.


{
  ...,
  "components": {
    ...,
    "aws.greengrass.clientdevices.IPDetector": {
      "componentVersion": "2.1.1",
      "configurationUpdate": {
        "merge": "{\"defaultPort\":\"8883\",}"
      }
    }
  }
}

Manually manage endpoints

You can manually manage MQTT broker endpoints for core devices.

Each MQTT broker endpoint has the following information:

Endpoint (HostAddress)

An IP address or DNS address where client devices can connect to an MQTT broker on the core device.

Port (PortNumber)

The port where the MQTT broker operates on the core device.

You can configure this port on the Moquette MQTT broker component, which defaults to use port 8883.

Metadata (Metadata)

Additional metadata to provide to client devices that connect to this endpoint.

Manage endpoints (console)

You can use the AWS IoT Greengrass console to view, update, and remove endpoints for a core device.

To manage endpoints for a core device (console)

Navigate to the AWS IoT Greengrass console.
Choose Core devices.
Choose the core device to manage.
On the core device's details page, choose the Client devices tab.
In the MQTT broker endpoints section, you can see the core device's MQTT broker endpoints. Choose Manage endpoints.
In the Manage endpoints modal, add or remove MQTT broker endpoints for the core device.
Choose Update.

Manage endpoints (AWS CLI)

You can use the AWS Command Line Interface (AWS CLI) to manage endpoints for a core device.

Note

Because client device support in AWS IoT Greengrass V2 is backward compatible with AWS IoT Greengrass V1, you can use AWS IoT Greengrass V2 or AWS IoT Greengrass V1 API operations to manage core device endpoints.