Navigation

Update One Data Lake

Beta

The Atlas Data Lake is available as a Beta feature. The product and the corresponding documentation may change at any time during the Beta stage. For support, see Atlas Support.

Note

Groups and projects are synonymous terms. Your {GROUP-ID} is the same as your project ID. For existing groups, your group/project ID remains the same. The resource and corresponding endpoints use the term groups.

The Atlas API uses HTTP Digest Authentication. Provide a programmatic API public key and corresponding private key as the username and password when constructing the HTTP request.

For complete documentation on configuring API access for an Atlas project, see Configure Atlas API Access.

Base URL: https://cloud.mongodb.com/api/atlas/v1.0

Use this endpoint to update a specific Atlas Data Lake associated to an Atlas project.

Syntax

PATCH /groups/{GROUP-ID}/dataLakes/{NAME}

Request Path Parameters

Path Element Required/Optional Description
GROUP-ID Required. The unique identifier for the project.
NAME Required

The name of the Atlas Data Lake that you want to update.

You can use the Get All Data Lakes endpoint to retrieve all Atlas Data Lake associated to the project. The name field in the response of that endpoint corresponds to the NAME parameter.

Request Query Parameters

The following query parameters are optional:

Query Parameter Type Description Default
pretty boolean Displays response in a prettyprint format. false
envelope boolean Specifies whether or not to wrap the response in an envelope. false

Request Body Parameters

Field Required/Optional Description
cloudProviderConfig Optional

Configuration information related to the cloud service where Atlas Data Lake source data is stored.

Required if updating a Data Lake in UNVERIFIED state.

cloudProviderConfig.<provider> Required

Name of the provider of the cloud service where Data Lake can access the S3 Bucket.

Atlas Data Lake supports only AWS.

Required if specifying cloudProviderConfig.

cloudProviderConfig.aws. iamAssumedRoleARN Required

Amazon Resource Name (ARN) of the role which Atlas Data Lake uses for accessing the data stores.

The IAM Role must support the following actions against each S3 bucket:

  • s3:GetObject
  • s3:ListBucket
  • s3:GetObjectVersion

For more information on S3 actions, see Actions, Resources, and Condition Keys for Amazon S3.

Required if specifying cloudProviderConfig.

cloudProviderConfig.aws. testS3Bucket Required

Name of an S3 data bucket which Data Lake uses to validate the provided cloudProviderConfig.aws. iamAssumedRoleArn.

The provided iamAssumedRoleARN must grant read access to the S3 bucket for the Atlas user ARN and external ID provided during tenant creation. Specifically, the IAM Role must support the following actions against the S3 bucket:

  • s3:GetObject
  • s3:ListBucket
  • s3:GetObjectVersion

Required if specifying cloudProviderConfig.

dataProcessRegion Optional

The cloud provider region to which Atlas Data Lake routes client connections for data processing.

Set to null to direct Atlas Data Lake to route client connections to the region nearest to the client based on DNS resolution.

dataProcessRegion.cloudProvider Required

Name of the cloud service provider.

Atlas Data Lake only supports AWS.

Required if specifying dataProcessRegion.

dataProcessRegion.region Required

Name of the region to which Data Lake routes client connections for data processing.

Atlas Data Lake only supports the following regions:

  • SYDNEY_AUS (ap-southeast-2)
  • FRANKFURT_DEU (eu-central-1)
  • DUBLIN_IRL (eu-west-1)
  • LONDON_GBR (eu-west-2)
  • VIRGINIA_USA (us-east-1)
  • OREGON_USA (us-west-2)

Required if specifying dataProcessRegion.

Response

Name Type Description
cloudProviderConfig object Configuration information related to the cloud service where Atlas Data Lake source data is stored.
cloudProviderConfig.<provider> object

Name of the provider of the cloud service where Data Lake can access the S3 Bucket data stores.

Data Lake only supports AWS.

cloudProviderConfig.aws. iamAssumedRoleARN string

Amazon Resource Name (ARN) of the IAM Role that Data Lake assumes when accessing S3 Bucket data stores.

The IAM Role must support the following actions against each S3 bucket:

  • s3:GetObject
  • s3:ListBucket
  • s3:GetObjectVersion

For more information on S3 actions, see Actions, Resources, and Condition Keys for Amazon S3.

dataProcessRegion Optional

The cloud provider region to which Atlas Data Lake routes client connections for data processing.

If null, the Atlas Data Lake routes client connections to the region nearest to the client based on DNS resolution.

dataProcessRegion.cloudProvider Required

Name of the cloud service provider.

Atlas Data Lake only supports AWS.

dataProcessRegion.region Required

Name of the region to which Atlas Data Lake routes client connections for data processing.

Atlas Data Lake only supports the following regions:

  • SYDNEY_AUS (ap-southeast-2)
  • FRANKFURT_DEU (eu-central-1)
  • DUBLIN_IRL (eu-west-1)
  • LONDON_GBR (eu-west-2)
  • VIRGINIA_USA (us-east-1)
  • OREGON_USA (us-west-2)
groupId string The unique identifier for the project.
hostnames array The list of hostnames assigned to the Atlas Data Lake. Each string in the array is a hostname assigned to the Atlas Data Lake.
name string Name of the Atlas Data Lake.
state string

Current state of the Atlas Data Lake:

  • ACTIVE - The Data Lake is active and verified. You can query the data stores associated to the Atlas Data Lake.

  • UNVERIFIED - The Atlas Data Lake has an incomplete configuration or the provided credentials do not grant the access to the data stores.

    For AWS specifically, the provided cloudProviderConfig.aws.iamAssumedRoleARN must grant access to the AWS S3 buckets associated with any data stores.

    Use the update endpoint to update the data store configuration with the required settings.

storage object Configuration details for each data store and its mapping to MongoDB database(s) and collection(s).
storage.databases object

Configuration details for mapping each data store to queryable databases and collections. For complete documentation on this object and its nested fields, see databases.

An empty object indicates that the Data Lake has no mapping configuration for any data store.

storage.stores array

Each object in the array represents a data store. Data Lake uses the storage.databases configuration details to map data in each data store to queryable databases and collections. For complete documentation on this object and its nested fields, see stores.

An empty object indicates that the Data Lake has no configured data stores.

Example

Request

curl -u "username:apiKey" --digest \
 --header "Accept: application/json" \
 --header "Content-Type: application/json" \
 --request PATCH "https://cloud.mongodb.com/api/atlas/v1.0/groups/{GROUP-ID}/dataLakes/{NAME}?pretty=true"
 --data '{
   "cloudProviderConfig" : {
     "AWS" : {
       "iamAssumedRoleARN" : "arn:aws:iam::123456789012:role/ReadS3BucketRole",
       "testS3Bucket" : "user-metric-data-bucket"
     }
   },
   "dataProcessRegion" : {
     "cloudProvider" : "AWS",
     "region" : "OREGON_USA"
   }
 }'

Response

{
  "cloudProviderConfig": {
    "aws": {
      "iamAssumedRoleARN": "arn:aws:iam::123456789012:role/ReadS3BucketRole"
    }
  },
  "dataProcessRegion": {
    "cloudProvider" : "AWS",
    "region" : "OREGON_USA"
  },
  "groupId": "1ab23c4567def890gh12ij34",
  "hostnames": [
    "dataLakes3tenant.mongodb.example.net"
  ],
  "name": "HardwareMetricData",
  "state": "ACTIVE",
  "storage": {
    "databases": {},
    "stores": []
  }
}