Docs Menu
Docs Home
/ /
Atlas App Services
/

Manage Edge Servers in Atlas

On this page

  • Before You Begin
  • Create a Service for Edge Server
  • Create an Edge Server Instance
  • List Edge Server Instances
  • Delete an Edge Server Instance
  • Update an Edge Server's Data Model
  • Troubleshoot an Edge Server Instance
  • Edge Server Limitations

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.

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 ObjectId

  • Device Sync Service: Type ObjectId, String, Long, Int, UUID

Any documents without this field cannot sync to an Edge Server.

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.

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.

You can get a list of your Edge Server instances in the Atlas UI, or from the Admin API.

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.

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.

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.

You can delete an individual Edge Server instance from Atlas.

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.

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.

When you want to add a collection to an Edge Server Service, you must add a schema containing:

  • The collection name.

  • An _id field that is of ObjectID type.

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 Define & 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.

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.

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.

A few conditions can cause an Edge Server instance to enter a Failed state:

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 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.

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.

While Edge Server is in Public Preview, it does not yet support the full range of MongoDB and Atlas Device SDK features and functionality.

Edge Server does not currently support time series collections.

When you create an Edge Server service, we automatically create schemas for every collection in your linked database. Trying to use Edge Server with a database that contains a time series collection throws an error.

To resolve this error, you must manually remove the schema for the time series collection. For information about how to remove the schema, refer to Remove a Schema.

Edge Server currently supports only a subset of MongoDB aggregation and CRUD operations. For a list of supported operations, refer to Edge Server MongoDB API Support.

Edge Server does not currently support Data Ingest.

← Edge Server