diff --git a/docs/device-agent/register.md b/docs/device-agent/register.md index 18f800ad27..345383b33e 100644 --- a/docs/device-agent/register.md +++ b/docs/device-agent/register.md @@ -147,7 +147,6 @@ flowfuse-device-agent You will see the Device Agent start and perform a 'call-home' where it connects back to the platform to check what it should be running. - #### Additional Information If you copy or download a **Device Provisioning Configuration** file to your hardware, @@ -164,12 +163,12 @@ you've followed [Single Device Registration](#single-remote-instance-registratio [Bulk Registration](#bulk-registration) to register your device, it will automatically be assigned to an Application or Instance. -### Applications (Recommended) - -#### Assign to Application +### Applications This step will permit you to push Snapshots to your Remote Instance via [DevOps Pipelines](/docs/user/devops-pipelines.md), or via a [Target Snapshot](/docs/user/snapshots/#application-owned-devices) from the Application. +#### Assign to Application + 1. Go to your teams's **Remote Instances** page. 2. Open the dropdown menu to the right of the Remote Instance you want to assign and select the **Add to Application** option. @@ -206,14 +205,17 @@ NOTE: If you wish to keep the flows currently running on the Remote Instance, it ### Hosted Instances -This method permits you to set a [Target Snapshot](/docs/user/snapshots/#instance-owned-devices) from the Hosted Instance to the Remote Instance. Note though, you can only push nodes and flows that are supported by _both_ Hosted and Remote Instances. The best use case for Remote Instances are generally to be assigned by an Application instead. +This method establishes a deployment relationship where a Hosted Instance becomes the source for snapshot deployments to your Remote Instance(s). + +**Important:** This is a legacy feature; [assigning to Applications](./register.md#applications) is the recommended approach as it provides better fleet management and DevOps Pipeline capabilities. For guidance, see [when to use each approach](/docs/user/concepts.md#when-to-use-instance-assignment-vs-devops-pipelines). #### Assign to Hosted Instance -1. Go to your teams's **Remote Instances** page. -2. Open the dropdown menu to the right of the Remote Instance you want to assign and - select the **Add to Hosted Instance** option. -3. Select the instance in the dialog and click **Add** to continue. +1. Go to your team's **Remote Instances** page. +2. Open the dropdown menu to the right of the Remote Instance you want to assign and select the **Add to Instance** option. +3. Select the Hosted Instance in the dialog and click **Add** to continue. + +**Note:** There are constraints on which instances can be assigned to each other. For detailed information, refer to [Assignment Rules and Constraints](/docs/user/concepts.md#assignment-rules). ### Remove from Hosted Instance diff --git a/docs/user/concepts.md b/docs/user/concepts.md index 797e9ada91..74c61a09f5 100644 --- a/docs/user/concepts.md +++ b/docs/user/concepts.md @@ -5,7 +5,7 @@ navOrder: 2 # FlowFuse Concepts -FlowFuse makes it easy to create, manage, and scale Node-RED instances. The platform introduces a few core concepts to help you organize and work with it effectively. Throughout the platform, you’ll also see ⓘ icons that you can click on to get pop-up explanations for different features and terms. +FlowFuse makes it easy to create, manage, and scale Node-RED instances. The platform introduces a few core concepts to help you organize and work with it effectively. Throughout the platform, you'll also see ⓘ icons that you can click on to get pop-up explanations for different features and terms. ## Table of Contents @@ -25,7 +25,11 @@ FlowFuse makes it easy to create, manage, and scale Node-RED instances. The plat - [Template](#template) - [Snapshot](#snapshot) - [Hosted Instance Snapshot](#hosted-instance-snapshot) - - [Remote Instances (Device Snapshot)](#remote-instance-snapshot) + - [Remote Instance Snapshot](#remote-instance-snapshot) + - [Assigning Remote Instances to Hosted Instances](#assigning-remote-instances-to-hosted-instances) + - [How It Works](#how-it-works) + - [Assignment Rules](#assignment-rules) + - [When to Use Instance Assignment vs DevOps Pipelines](#when-to-use-instance-assignment-vs-devops-pipelines) - [Device](#device) - [Device Agent](#device-agent) - [Fleet Mode vs Developer Mode](#fleet-mode-vs-developer-mode) @@ -50,7 +54,7 @@ To organize your Node-RED instances, they are grouped within Applications. With Applications provide logical organization of related instances, support for DevOps pipeline workflows, simplified device group management, application-level audit logging, and clear organizational boundaries for managing multiple instances and devices. -With FlowFuse’s Granular RBAC, Applications can now also act as an authorization boundary. This means user roles and permissions can be managed at the application level, providing finer control over access to instances, snapshots, and devices within a given application. +With FlowFuse's Granular RBAC, Applications can now also act as an authorization boundary. This means user roles and permissions can be managed at the application level, providing finer control over access to instances, snapshots, and devices within a given application. ### DevOps Pipeline @@ -125,6 +129,35 @@ A user can create an hosted instance snapshot and then mark it as the *target* s Similar to instance snapshots, a device snapshot is a point-in-time backup of a Node-RED instance running on a remote device. It captures the flows, credentials, and runtime settings. The difference is that local changes made on a device during developer mode are pulled into the FlowFuse platform and stored as a snapshot. The dashboard also allows you to see and manage these snapshots. With devices assigned to an application, a user can create a device snapshot from the remote device. +### Assigning Remote Instances to Hosted Instances + +**Note:** This is a legacy feature that predates DevOps Pipelines. For new deployments, consider using [DevOps Pipelines](#devops-pipeline) instead, which provide more flexible and powerful deployment workflows. + +Instance assignment establishes a parent-child deployment relationship between a hosted instance and remote instances. When assigned, the hosted instance becomes the source of truth and automatically pushes snapshots to the remote instance. You can only push nodes and flows that are supported by both Hosted and Remote Instances. For more information on how this works, see [How Instance Assignment Works](/docs/user/concepts.md#how-it-works). + +#### How It Works + +Instance assignment creates a parent-child deployment relationship with the following behavior: + +- **Hosted Instance (Parent)**: Acts as the deployment controller and source of truth for snapshots +- **Remote Instance (Child)**: Receives and applies snapshot updates from the parent +- **Deployment Flow**: When you set a [Target Snapshot](/docs/user/snapshots/#instance-owned-devices) on the hosted instance, all assigned remote instances automatically restart on that snapshot +- **One-Way Relationship**: Changes flow exclusively from the hosted instance to remote instances, ensuring consistent deployments across your fleet + +#### Assignment Rules + +FlowFuse enforces specific constraints on instance assignment: + +- Remote instances can be assigned to hosted instances +- Remote instances cannot be assigned to other remote instances +- Hosted instances cannot be assigned to any other instances + +#### When to Use Instance Assignment vs DevOps Pipelines + +Instance assignment suits straightforward scenarios where you need to push snapshots from a single hosted instance directly to one or more remote instances. It works well for maintaining existing deployments or when you simply need one hosted instance deploying to multiple remote instances without staging environments. + +DevOps Pipelines are recommended for most deployment workflows. They support staged environments for testing changes in development before promoting to production, enable deployment to device groups for easier fleet management, and offer more flexibility aligned with modern development practices. If you're setting up a new deployment process, use DevOps Pipelines. + ## Device The FlowFuse platform can be used to manage Node-RED applications running on remote devices. A Device is essentially a **Remote Instance** that runs a software agent to connect back to the platform and receive updates. @@ -155,4 +188,4 @@ Device groups allow you to organize your devices into logical groups. These grou Device groups provide logical organization of devices by location, function, environment, or other criteria. They enable simplified mass deployments through DevOps pipelines, allow you to target specific device groups for staged rollouts, and let you manage subsets of devices independently. -Read more [about Device Groups](./device-groups.md). +Read more [about Device Groups](./device-groups.md). \ No newline at end of file