Manage Edge Servers in Atlas - Preview

Navigate to the Data Services UI

When you select a project in the Atlas UI Project dashboard, the Data Services tab displays by default.

If you are in App Services or Charts, select the Data Services tab.

Choose Device & Edge Sync

In the left sidebar, browse to the Services section. Select Device & Edge Sync.

Create a Service

Select the type of service you want to create, and follow the prompts to create an Edge Server Service or Device Sync Service.

After creating an Edge Server Service, you're able to immediately add Edge Server instances.

If you create a Device Sync Service, click Edge Server in the left navigation. This opens a list where you can add and view Edge Server instances.

Click the Add a server button, and follow the prompts to name and create your new Edge Server instance.

Create a Device Sync App

Refer to the documentation to Create an App Services App.

When you choose your App type, select Device Sync. You can add Edge Servers to your Device Sync App after you configure Device Sync.

Add Edge Server Instances to Your Device Sync Service

While viewing your Device Sync Service, click Edge Server in the left navigation. This opens a list where you can add and view Edge Server instances.

Click the Add a server button, and follow the prompts to name and create your new Edge Server instance.

Add a server

Click Add a server. You're prompted to name your Edge Server.

The UI provides an installation script, which you can copy and paste into the terminal on the device where you want to install the Edge Server code. You also get a token, which you will use when you configure the Edge Server instance.

Install and Configure the Edge Server code

Copy and paste the installation script into the terminal on the device where you want to install the Edge Server code. For more details, refer to Install and Configure the Edge Server Instance.

After you configure and start the Edge Server instance, its Health status in the Edge Server dashboard changes from Pending to Active.

Authenticate a MongoDB Atlas User

Call the admin user authentication endpoint with your MongoDB Atlas API key pair:

curl -X POST \
  https://services.cloud.mongodb.com/api/admin/v3.0/auth/providers/mongodb-cloud/login \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "username": "<Public API Key>",
    "apiKey": "<Private API Key>"
  }'

If authentication succeeds, the response body contains a JSON object with an access_token value:

{
  "access_token": "<access_token>",
  "refresh_token": "<refresh_token>",
  "user_id": "<user_id>",
  "device_id": "<device_id>"
}

The access_token grants access to the App Services Admin API. You must include it as a Bearer token in the Authorization header for all Admin API requests.

Call the Create Edge Server Instance Endpoint

Call the Admin API Create an Edge Server instance endpoint to add an Edge Server instance to your service.

Your request must include:

• An Authorization header with your Admin API access token as a Bearer token.

• A name for the new Edge Server instance

curl -X POST \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/edge \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <AccessToken>' \
  -d '{
    "name": "YOUR-EDGE-SERVER-INSTANCE-NAME"
  }'

A successful request returns a 201 code, as well as a JSON object with information about the newly-created Edge Server instance:

{
  "id": "6622b8f5118368b943d228a9",
  "user_id": "6622b8f5118368b943d2288a",
  "registration_key": "Qi4GgpvVduwwt4k1w77ZzaQ1n4SdTWC8rLBD9vyTib1w9G3CX2ta8WrJvt3giEK7"
}

• id: The unique identifier of the Edge Server instance, of type ObjectId, as a string. You can use this identifier to delete or update the Edge Server instance.

• user_id: The Edge Server itself is a user. This is the unique identifier of the Edge Server user, of type ObjectId, as a string. You can use this identifier when configuring permissions.

• registration_key: Save this information. When you install the Edge Server code on the host, enter this registration token. The Edge Server exchanges this for an API Key that it uses to authenticate with Atlas. You can only use this registration token once.

Install the Edge Server code

Copy and paste the installation script into the terminal on the device where you want to install the Edge Server code. For more details, refer to Install and Configure the Edge Server Instance.

Authenticate a MongoDB Atlas User

Call the admin user authentication endpoint with your MongoDB Atlas API key pair:

curl -X POST \
  https://services.cloud.mongodb.com/api/admin/v3.0/auth/providers/mongodb-cloud/login \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "username": "<Public API Key>",
    "apiKey": "<Private API Key>"
  }'

If authentication succeeds, the response body contains a JSON object with an access_token value:

{
  "access_token": "<access_token>",
  "refresh_token": "<refresh_token>",
  "user_id": "<user_id>",
  "device_id": "<device_id>"
}

The access_token grants access to the App Services Admin API. You must include it as a Bearer token in the Authorization header for all Admin API requests.

Get the List of Edge Server Instances

Call the Admin API List Edge Servers endpoint to get a list of all the Edge Servers instances.

Your request must include an Authorization header with your Admin API access token as a Bearer token.

curl -X GET \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/edge \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <AccessToken>'

A successful request returns a 200 code, and an edge_servers key whose values is an array of objects containing summary details for each Edge Server instance associated with the appId.

{
  "edge_servers": [
    {
      "id": "6622b8f5118368b943d228a9",
      "created": "2024-04-19T08:51:00Z",
      "name": "Edge-Store-42",
      "user_id": "6622b8f5118368b943d2288a",
      "status": "active",
      "hostname": "ec2-13-58-70-88.us-east-2.compute.amazonaws.com",
      "last_connection": "2024-04-19T09:51:00Z"
    }
  ]
}

For more detailed information, find the id of the instance whose details you want to view.

Call the Edge Server Info Endpoint

Call the Admin API Get Edge Server information endpoint to get detailed information about an Edge Server instance.

Your request must include an Authorization header with your Admin API access token as a Bearer token.

curl -X GET \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/edge/{edgeServerId} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <AccessToken>'

A successful request returns a 200 code, as well as a JSON object with detailed information about the Edge Server instance:

{
  "id": "6622b8f5118368b943d228a9",
  "created": "2024-04-19T08:51:00Z",
  "name": "Edge-Store-42",
  "user_id": "6622b8f5118368b943d2288a",
  "status": "active",
  "hostname": "ec2-13-58-70-88.us-east-2.compute.amazonaws.com",
  "last_connection": "2024-04-19T09:51:00Z",
  "query": {
    "Item": "(store_id == \"641cb3d99e425c794ef69315\")"
  },
  "package_version": "v0.21.2",
  "latest_package_version": "v0.22.2",
  "metrics": [
    {
      "key": "edge_host_memory_percent",
      "name": "Memory Usage",
      "category": "host",
      "detail": "Percentage of memory used by the edge container",
      "value": 15,
      "unit": "%"
    },
    ...additional Edge Server metrics...
  ]
}

For more information about this response body, refer to the API specification.

Browse to the Edge Server Dashboard

Click the Edge Server option in the left navigation sidebar to open the Edge Server dashboard.

View the Edge Server Instance Details

Find the Edge Server instance you want to delete in the list, and click the View Details button.

Delete the Edge Server Instance

Click the Delete button at the bottom of the Edge Server details view.

You'll be prompted to confirm deletion. Follow the prompts to confirm that you want to delete the Edge Server.

Authenticate a MongoDB Atlas User

Call the admin user authentication endpoint with your MongoDB Atlas API key pair:

curl -X POST \
  https://services.cloud.mongodb.com/api/admin/v3.0/auth/providers/mongodb-cloud/login \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "username": "<Public API Key>",
    "apiKey": "<Private API Key>"
  }'

If authentication succeeds, the response body contains a JSON object with an access_token value:

{
  "access_token": "<access_token>",
  "refresh_token": "<refresh_token>",
  "user_id": "<user_id>",
  "device_id": "<device_id>"
}

The access_token grants access to the App Services Admin API. You must include it as a Bearer token in the Authorization header for all Admin API requests.

Get the ID of the Edge Server to Delete

Call the Admin API List Edge Servers endpoint to get a list of all the Edge Server instances.

Your request must include an Authorization header with your Admin API access token as a Bearer token.

curl -X GET \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/edge \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <AccessToken>'

A successful request returns a 200 code, and an edge_servers key whose values is an array of objects containing summary details for each Edge Server instance associated with the appId.

{
  "edge_servers": [
    {
      "id": "6622b8f5118368b943d228a9",
      "created": "2024-04-19T08:51:00Z",
      "name": "Edge-Store-42",
      "user_id": "6622b8f5118368b943d2288a",
      "status": "active",
      "hostname": "ec2-13-58-70-88.us-east-2.compute.amazonaws.com",
      "last_connection": "2024-04-19T09:51:00Z"
    }
  ]
}

Find the id of the Edge Server instance that you want to delete in the array.

Call the Delete Endpoint

Call the Admin API Delete an Edge Server instance endpoint with the ID of the Edge Server instance that you want to delete.

Your request must include an Authorization header with your Admin API access token as a Bearer token.

curl -X DELETE \
  https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/edge/{edgeServerId} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <AccessToken>'

A successful request returns a 200 code.