Manage Edge Servers in Atlas
On this page
An Edge Server-compatible service is your Atlas destination to create, delete, or monitor your Edge Server instances.
There are two types of services that enable you to use Edge Server:
Edge Server Service: use this option if you want clients to connect to an Edge Server instance with MongoDB Drivers and tools. It infers and updates the schema from the documents you insert, and provides a developer experience familiar to MongoDB developers. This service is incompatible with Atlas Device SDK; it rejects incoming Atlas Device SDK connections.
Device Sync Service (with Edge Server): use this option if you want to develop client apps using Atlas Device SDK and MongoDB Drivers and tools. This option involves more strict schema enforcement, which the SDKs use to automatically sync objects across devices and handle conflict resolution.
Regardless of which type of service you choose, Edge Servers use Device Sync to sync data between the Edge Server instance and Atlas.
Important
You can't add Atlas Device SDK later to an Edge Server Service
You can always add Edge Servers to a Device Sync Service. But you can't use Atlas Device SDK connections with an Edge Server Service.
Users are not portable between services. If you start with an Edge Server Service, but later want to develop apps using Atlas Device SDK, there is no way to transfer any users in your Edge Service to a new Device Sync Service.
Before You Begin
Create a Service for Edge Server
You can create an Edge Server-compatible service in Data Services or App Services.
You might select Data Services when you just want to get started building with Edge Server or Device Sync and Edge Server, and don't need other App Services. You can create an Edge Server Service from Data Services.
You might select App Services when you want to bundle your service with authentication, Functions, Triggers, HTTPS Endpoints, or Values and Secrets. You can create a Device Sync Service from App Services, and add Edge Server to it.
Important
Required Field
Documents that you want to sync with an Edge Server must contain an _id
field whose type varies depending on the service type:
Edge Server Service: Type
ObjectIdDevice Sync Service: Type
ObjectId,String,Long,Int,UUID
Any documents without this field cannot sync to an Edge Server.
Supported Authentication Providers
Edge Server supports a subset of authentication providers. Supported authentication providers vary depending on whether you're connecting with Atlas Device SDK or using a MongoDB URI to connect with a MongoDB Driver or tool.
You must enable at least one of these providers to enable clients to connect to an Edge Server instance.
Supported Atlas Device SDK Authentication Providers
Supported MongoDB Driver Authentication Providers
Create an Edge Server Instance
After creating an Edge Server-compatible service, you can add Edge Servers to it. The service can handle multiple Edge Servers, each of which has its own registration key.
List Edge Server Instances
You can get a list of your Edge Server instances in the Atlas UI, or from the Admin API.
Edge Server Instance Details
The information available in the Edge Server details varies depending on whether the Edge Server has been configured and connected to Atlas, or whether configuration and connection are still pending.
Pending Edge Server Instances
When an Edge Server instance has not yet connected to Atlas for the first time, the instance's Health status is Pending.
While an Edge Server instance is in Pending state, you can perform the following actions from the detail view:
Rename the instance.
Review alerts about the instance status.
Get the instance ID. You can use this to set permissions for this specific instance.
View the Install command that you can use in the terminal to install the Edge Server code.
Regenerate the registration token.
Delete the Edge Server instance.
Once you have successfully configured and connected an Edge Server instance, the detail view changes to provide additional information.
Active or Failed Edge Server Instances
After you have connected an Edge Server instance to Atlas for the first time, the instance's Health status changes to Active.
If the Edge Server instance encounters a fatal error, its Health status changes to Failed.
You can perform the following actions for active or failed instances:
Rename the instance.
Review alerts about the instance status.
View the date and time of the last connection.
Get the instance ID. You can use this to set permissions for this specific instance.
View the instance query. This determines what data syncs between the instance and Atlas, and what data clients can write to the instance. Clients can only write data that falls within their permissions, and the instance's query. For more information, refer to Specify the Edge Server's Query.
View Metrics about the Edge Server instance. For more information, refer to Edge Server Metrics.
View the instance Logs. For more information, refer to Edge Server Logs.
View version information. This page lists the current version, and the latest available version. If the instance falls more than one major version behind the latest available, it enters a Failed state and cannot sync with Atlas until it is upgraded. For more information, refer to Upgrade the Edge Server Version.
View the Install command that you can use in the terminal to install the Edge Server code.
Regenerate the registration token.
Delete the Edge Server instance.
Delete an Edge Server Instance
You can delete an individual Edge Server instance from Atlas.
Update an Edge Server's Data Model
The process to update a data model varies depending on whether you're using an Edge Server Service or a Device Sync Service with Edge Server.
Edge Server Service
When you're using an Edge Server Service, the service automatically updates fields in the schema when you make changes to the documents you sync.
If you update your schema manually using the UI, and those schema changes trigger a schema version change, this causes an Edge Server instance with the old schema to reboot and wipe itself.
If you're adding a new collection you haven't synced before, you must define a new schema.
Add a Collection
When you want to add a collection to an Edge Server Service, you must add a schema containing:
The collection name.
An
_idfield that is ofObjectIDtype.
The Edge Server Service automatically infers the other fields from the shape of the documents you sync or the documents in the collection.
For information about how to add a schema, refer to Enforce a Schema.
After adding a collection, you must stop and start the Edge Server instance to pick up the new collection details. For more information, refer to Start and Stop the Edge Server.
Change Fields in a Document
When you change the fields in a document using an Edge Server Service, the service automatically changes the schema to add new fields.
Some changes that you can make through the UI are considered "breaking" schema changes. When a "breaking" schema change occurs, any Edge Server instance with the old schema reboots and wipes itself. The wipe process erases any unsynced data.
Important
Wiping and restarting the instance erases all local unsynced data on the instance.
If that data was written by an Atlas Device SDK client, the client itself can handle data recovery. This enables local unsynced data written by the client to eventually make its way to Atlas.
If the data was written by a MongoDB Driver or tool using the Wire Protocol, the unsynced data is unrecoverable.
Before Edge Server moves from Public Preview to General Availability, you will have the option to recover local data when this error occurs.
For details about which types of changes are considered "breaking" changes, refer to Breaking vs. Non-Breaking Change Quick Reference.
Device Sync Service
An Edge Server running in a Device Sync Service uses Device Sync rules for updating a data model.
When a "breaking" schema change occurs, any Edge Server instance with the old schema reboots and wipes itself.
Important
Wiping and restarting the instance erases all local unsynced data on the instance.
If that data was written by an Atlas Device SDK client, the client itself can handle data recovery. This enables local unsynced data written by the client to eventually make its way to Atlas.
If the data was written by a MongoDB Driver or tool using the Wire Protocol, the unsynced data is unrecoverable.
Before Edge Server moves from Public Preview to General Availability, you will have the option to recover local data when this error occurs.
For more information, refer to Update Your Data Model.
Troubleshoot an Edge Server Instance
A few conditions can cause an Edge Server instance to enter a Failed state:
Edge Server is Offline Longer than Client Maximum Offline Time
Edge Server uses Device Sync to sync data between the Edge Server instance and Atlas. Device Sync has a Client Maximum Offline Time setting.
This setting is enabled by default. It trims history to reduce the amount of storage required in the backing Atlas cluster. The longer the client maximum offline time, the more storage Atlas requires to keep historical records that support Sync.
If an Edge Server instance is offline longer than this setting, this is an unrecoverable error. You must wipe and restart the instance. Alternately, when you bring the instance back online, it will be wiped and restarted automatically.
Important
Wiping and restarting the instance erases all local unsynced data on the instance.
If that data was written by an Atlas Device SDK client, the client itself can handle data recovery. This enables local unsynced data written by the client to eventually make its way to Atlas.
If the data was written by a MongoDB Driver or tool using the Wire Protocol, the unsynced data is unrecoverable.
Before Edge Server moves from Public Preview to General Availability, you will have the option to recover local data when this error occurs.
You can change the length of the client maximum offline time in the Sync Settings.
Important
Edge Server Offline Limit is 60 Days
An Edge Server instance cannot be offline longer than 60 days, no matter what setting you set for the client maximum offline time. If the setting is unset or greater than 60 days, the Edge Server offline limit is 60 days.
Edge Server Instance is More than One Major Version Behind
Edge Server does not support instances that fall more than one major version
behind the current latest version. If your Edge Server instance falls further
behind in versions, you must upgrade it to resolve the Failed state.
For information about upgrading an Edge Server instance, refer to Upgrade the Edge Server Version.
Edge Server Token is Invalid
If the Edge Server instance token is regenerated, and you do not update the
API Key on the instance itself, it can enter a Failed state.
For more details about how to update the API Key on the Edge Server instance after regenerating the Edge Server token, refer to Cycle the Edge Server API Key.