Skip to content

README.md

Latest commit

 

History

History
299 lines (222 loc) · 11.6 KB

README.md

File metadata and controls

299 lines (222 loc) · 11.6 KB

encryption-at-rest-express

The official MongoDB Atlas AWS CDK resource for Node.js.

This L3 construct uses MongoDB Atlas L1 constructs and data structures (including Cluster, Database User, IP Access List, and Encryption at Rest).

Description

The resource lets you create an Atlas Cluster, DB User, add an entry to the IP Access List and sets Encryption at Rest using Customer Key Management in your MongoDB Atlas Project.

MongoDB Atlas API Docs

For more information about the API refer to: API Endpoints

Usage

In order to use this library, you will need to activate this AWS CloudFormation Registry type in your account. You can do this via the AWS Management Console or using the AWS CLI using the following command:

aws cloudformation activate-type \
  --type-name MongoDB::Atlas::Cluster \
  --publisher-id bb989456c78c398a858fef18f2ca1bfc1fbba082 \
  --type RESOURCE \
  --execution-role-arn ROLE-ARN
  
aws cloudformation activate-type \
  --type-name MongoDB::Atlas::EncryptionAtRest \
  --publisher-id bb989456c78c398a858fef18f2ca1bfc1fbba082 \
  --type RESOURCE \
  --execution-role-arn ROLE-ARN

aws cloudformation activate-type \
  --type-name MongoDB::Atlas::DatabaseUser \
  --publisher-id bb989456c78c398a858fef18f2ca1bfc1fbba082 \
  --type RESOURCE \
  --execution-role-arn ROLE-ARN  

aws cloudformation activate-type \
  --type-name MongoDB::Atlas::ProjectIpAccessList \
  --publisher-id bb989456c78c398a858fef18f2ca1bfc1fbba082 \
  --type RESOURCE \
  --execution-role-arn ROLE-ARN

Alternatively:

aws cloudformation activate-type \
  --public-type-arn arn:aws:cloudformation:us-east-1::type/resource/bb989456c78c398a858fef18f2ca1bfc1fbba082/MongoDB-Atlas-Cluster \
  --execution-role-arn ROLE-ARN

aws cloudformation activate-type \
  --public-type-arn arn:aws:cloudformation:us-east-1::type/resource/bb989456c78c398a858fef18f2ca1bfc1fbba082/MongoDB-Atlas-EncryptionAtRest \
  --execution-role-arn ROLE-ARN  

aws cloudformation activate-type \
  --public-type-arn arn:aws:cloudformation:us-east-1::type/resource/bb989456c78c398a858fef18f2ca1bfc1fbba082/MongoDB-Atlas-DatabaseUser \
  --execution-role-arn ROLE-ARN

aws cloudformation activate-type \
  --public-type-arn arn:aws:cloudformation:us-east-1::type/resource/bb989456c78c398a858fef18f2ca1bfc1fbba082/MongoDB-Atlas-ProjectIpAccessList \
  --execution-role-arn ROLE-ARN

Impotant Notes

  1. This CDK L3 resource allows users to create and edit the Encryption at Rest using Customer Key Management configuration. MongoDB Cloud encrypts all storage by default whether or not you use your own key management.

  2. Atlas limits this feature to dedicated cluster tiers of M10 and greater. For more information see: https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/group/endpoint-encryption-at-rest-using-customer-key-management

  3. This construnctor supports only AWS Key Management Service.

  4. MongoDB does not support creating and configuring a IAM role via CFN and CDK. Please follow this guide (Enable Role-Based Access to Your Encryption Key for a Project) before trying to use this constructor as you must provide roleId and the customerMasterKeyId.

Example: encryption-at-rest.ts

Minimal configuration to use this CDK L3 construct

In this example, @mongodbatlas-awscdk/encryption-at-rest-express is used to enable encryption at rest for your MongoDB Atlas Project.

import * as cdk from 'aws-cdk-lib';
import { AtlasEncryptionAtRestExpress } from 'awscdk-resources-mongodbatlas';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'atlas-encryption-at-rest-express', {
  env: { region: process.env.CDK_DEFAULT_REGION, account: process.env.CDK_DEFAULT_ACCOUNT },
});


const PROJECT_ID = stack.node.tryGetContext('MONGODB_ATLAS_PROJECT_ID') || process.env.MONGODB_ATLAS_PROJECT_ID;
const ROLE_ID = stack.node.tryGetContext('MONGODB_ATLAS_ROLE_ID') || process.env.MONGODB_ATLAS_ROLE_ID;
const MASTER_KEY_ID = stack.node.tryGetContext('MONGODB_ATLAS_MASTER_KEY_ID') || process.env.MONGODB_ATLAS_MASTER_KEY_ID;

new AtlasEncryptionAtRestExpress(stack, 'atlas-encryption-at-rest-express', {
  projectId: PROJECT_ID,

  encryptionAtRest: {
    roleId: ROLE_ID,
    customerMasterKeyId: MASTER_KEY_ID,
  },
});

Minimal configuration to create a cluster and enable encryption at rest

In this example we are providing the minimal configuration to the constructor to define an Atlas Cluster and enable encryption at rest for the cluster and project.

import * as cdk from 'aws-cdk-lib';
import { AtlasEncryptionAtRestExpress } from 'awscdk-resources-mongodbatlas';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'atlas-encryption-at-rest-express', {
  env: { region: process.env.CDK_DEFAULT_REGION, account: process.env.CDK_DEFAULT_ACCOUNT },
});


const PROJECT_ID = stack.node.tryGetContext('MONGODB_ATLAS_PROJECT_ID') || process.env.MONGODB_ATLAS_PROJECT_ID;
const ROLE_ID = stack.node.tryGetContext('MONGODB_ATLAS_ROLE_ID') || process.env.MONGODB_ATLAS_ROLE_ID;
const MASTER_KEY_ID = stack.node.tryGetContext('MONGODB_ATLAS_MASTER_KEY_ID') || process.env.MONGODB_ATLAS_MASTER_KEY_ID;
const DB_USER_PASSWORD = stack.node.tryGetContext('MONGODB_ATLAS_DB_USER_PASSWORD') || process.env.MONGODB_ATLAS_DB_USER_PASSWORD;

new AtlasEncryptionAtRestExpress(this, 'EncryptionAtRestExpress', {
      cluster: {
        name: "ClusterName",
      },
      
      encryptionAtRest: {
        customerMasterKeyId: MONGODB_ATLAS_MASTER_KEY_ID,
        roleId: ROLE_ID,
      },

      projectId: PROJECT_ID,
    })
  }

The constructor will deploy the following resources using default values:

  • Cluster
    • name: [provided name]
    • provider: AWS
    • region: us-east-1
    • cluster type: replica-set
    • mongogb version: 5.0
    • eligible nodes: 3
    • instance size: M30
    • analytics node: 1
    • analytics instance size: M30
    • backup: enabled
    • encryption at rest provider: AWS

Note: In this example, the constructor did not create a DB User or enable public internet access to the cluster. See the next example to define the DB User and enable accessing the Cluster from the public internet.

Minimal configuration to create a cluster, database User, configure atlas access list and enable encryption at rest

In this example we are providing the minimal configuration to the constructor to define an Atlas Cluster, DB User, add an entry to the Atlas Access list, and enable encryption at rest for the cluster and project.

import * as cdk from 'aws-cdk-lib';
import { AtlasEncryptionAtRestExpress } from 'awscdk-resources-mongodbatlas';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'atlas-encryption-at-rest-express', {
  env: { region: process.env.CDK_DEFAULT_REGION, account: process.env.CDK_DEFAULT_ACCOUNT },
});


const PROJECT_ID = stack.node.tryGetContext('MONGODB_ATLAS_PROJECT_ID') || process.env.MONGODB_ATLAS_PROJECT_ID;
const ROLE_ID = stack.node.tryGetContext('MONGODB_ATLAS_ROLE_ID') || process.env.MONGODB_ATLAS_ROLE_ID;
const MASTER_KEY_ID = stack.node.tryGetContext('MONGODB_ATLAS_MASTER_KEY_ID') || process.env.MONGODB_ATLAS_MASTER_KEY_ID;
const DB_USER_PASSWORD = stack.node.tryGetContext('MONGODB_ATLAS_DB_USER_PASSWORD') || process.env.MONGODB_ATLAS_DB_USER_PASSWORD;

new AtlasEncryptionAtRestExpress(this, 'EncryptionAtRestExpress', {
      cluster: {
        name: "ClusterName",
      },

      accessList: {
        accessList: [{
          ipAddress: "192.0.0.1"
        }]
      },

      encryptionAtRest: {
        customerMasterKeyId: MONGODB_ATLAS_MASTER_KEY_ID,
        roleId: ROLE_ID,
      },

      databaseUser: {
        password: DB_USER_PASSWORD
      },

      projectId: PROJECT_ID,
    })
  }

The constructor will deploy the following resources using default values:

  • Cluster

    • name: [provided name]
    • provider: AWS
    • region: us-east-1
    • cluster type: replica-set
    • mongogb version: 5.0
    • eligible nodes: 3
    • instance size: M30
    • analytics node: 1
    • analytics instance size: M30
    • backup: enabled
    • encryption at rest provider: AWS

  • DataBase User

    • username: cdkUser
    • password: [provided password]

  • Atlas Access list

    • ip address: [provided ip address]

Configuration to create a cluster, database User, configure atlas access list and enable encryption at rest

In this example we override the default values for the atlas cluster and creates a replica-set with 6 nodes, instance size M10 in the AWS region US_WEST_2.

import * as cdk from 'aws-cdk-lib';
import { AtlasEncryptionAtRestExpress } from 'awscdk-resources-mongodbatlas';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'atlas-encryption-at-rest-express', {
  env: { region: process.env.CDK_DEFAULT_REGION, account: process.env.CDK_DEFAULT_ACCOUNT },
});


const PROJECT_ID = stack.node.tryGetContext('MONGODB_ATLAS_PROJECT_ID') || process.env.MONGODB_ATLAS_PROJECT_ID;
const ROLE_ID = stack.node.tryGetContext('MONGODB_ATLAS_ROLE_ID') || process.env.MONGODB_ATLAS_ROLE_ID;
const MASTER_KEY_ID = stack.node.tryGetContext('MONGODB_ATLAS_MASTER_KEY_ID') || process.env.MONGODB_ATLAS_MASTER_KEY_ID;
const DB_USER_PASSWORD = stack.node.tryGetContext('MONGODB_ATLAS_DB_USER_PASSWORD') || process.env.MONGODB_ATLAS_DB_USER_PASSWORD;

new AtlasEncryptionAtRestExpress(this, 'EncryptionAtRestExpress', {
      cluster: {
        name: "Cluster0",
        backupEnabled: false,
        mongoDbMajorVersion: "6.0",
        replicationSpecs: [
          {
            numShards: 1,
            advancedRegionConfigs: [
              {
                regionName: "US_WEAST_2",
                electableSpecs: {
                  instanceSize: "M10",
                  nodeCount: 6,
                  ebsVolumeType: "STANDARD"
                },
                priority: 7
            }
          ]}
        ]
      },

      accessList: {
        accessList: [{
          ipAddress: "192.0.0.1"
        }]
      },

      encryptionAtRest: {
        customerMasterKeyId: MONGODB_ATLAS_MASTER_KEY_ID,
        roleId: ROLE_ID,
      },

      databaseUser: {
        password: DB_USER_PASSWORD
      },

      projectId: PROJECT_ID,
    })
  }

You can find more information about activating this type in the AWS CloudFormation documentation.

Feedback

  • Issues related to this CDK Labs generated library should be reported here.
  • Issues related to this MongoDB Atlas library should be reported to the publisher.
  • Feature requests should be reported here

License

Distributed under the Apache-2.0 License.
⚡