Skip to content

Latest commit

 

History

History
196 lines (149 loc) · 9.81 KB

index.html.markdown

File metadata and controls

196 lines (149 loc) · 9.81 KB
layout page_title sidebar_current description
mongodbatlas
Provider: MongoDB Atlas
docs-mongodbatlas-index
The MongoDB Atlas provider is used to interact with the resources supported by MongoDB Atlas. The provider needs to be configured with the proper credentials before it can be used.

MongoDB Atlas Provider

You can use the MongoDB Atlas provider to interact with the resources supported by MongoDB Atlas. The provider needs to be configured with the proper credentials before it can be used.

Use the navigation to the left to read about the available provider resources and data sources.

You may want to consider pinning the provider version to ensure you have a chance to review and prepare for changes. Speaking of changes, see CHANGELOG for current version information.

Example Usage

# Configure the MongoDB Atlas Provider 
provider "mongodbatlas" {
  public_key = var.mongodbatlas_public_key
  private_key  = var.mongodbatlas_private_key
}
# Create the resources

Configure Atlas Programmatic Access

In order to set up authentication with the MongoDB Atlas provider, you must generate a programmatic API key for MongoDB Atlas with the appropriate role and IP access list entries. The MongoDB Atlas documentation contains the most up-to-date instructions for creating and managing your key(s), setting the appropriate role, and IP access.

Role: If unsure of which role level to grant your key, we suggest creating an organization API Key with an Organization Owner role. This ensures that you have sufficient access for all actions.

API Key Access List: Some Atlas API resources such as Cloud Backup Restores, Cloud Backup Snapshots, and Cloud Backup Schedules require an Atlas API Key Access List to utilize these feature. Hence, if using Terraform, or any other programmatic control, to manage these resources you must have the IP address or CIDR block that the connection is coming from added to the Atlas API Key Access List of the Atlas API key you are using. See Resources that require API Key List

Configure MongoDB Atlas for Government

In order to enable the Terraform MongoDB Atlas Provider for use with MongoDB Atlas for Government add is_mongodbgov_cloud = true to your provider configuration:

# Configure the MongoDB Atlas Provider for MongoDB Atlas for Government
provider "mongodbatlas" {
  public_key = var.mongodbatlas_public_key
  private_key  = var.mongodbatlas_private_key
  is_mongodbgov_cloud = true
}
# Create the resources

Also see Atlas for Government Considerations.

Authenticate the Provider

The MongoDB Atlas provider offers a flexible means of providing credentials for authentication. You can use any the following methods:

Environment Variables

You can also provide your credentials via the environment variables, MONGODB_ATLAS_PUBLIC_KEY and MONGODB_ATLAS_PRIVATE_KEY, for your public and private MongoDB Atlas programmatic API key pair respectively:

provider "mongodbatlas" {}

Usage (prefix the export commands with a space to avoid the keys being recorded in OS history):

$  export MONGODB_ATLAS_PUBLIC_KEY="xxxx"
$  export MONGODB_ATLAS_PRIVATE_KEY="xxxx"
$ terraform plan

As an alternative to MONGODB_ATLAS_PUBLIC_KEY and MONGODB_ATLAS_PRIVATE_KEY if you are using MongoDB CLI then MCLI_PUBLIC_API_KEY and MCLI_PRIVATE_API_KEY are also supported.

AWS Secrets Manager

AWS Secrets Manager (AWS SM) helps to manage, retrieve, and rotate database credentials, API keys, and other secrets throughout their lifecycles. See product page and documentation for more details.

In order to enable the Terraform MongoDB Atlas Provider with AWS SM, please follow the below steps:

  1. Create Atlas API Keys and add them as one secret to AWS SM with a raw value. Take note of which AWS Region secret is being stored in. Public Key and Private Key each need to be entered as their own key value pair. See below example:
     {
      "public_key": "secret1",
      "private_key":"secret2"
     }
  1. Create an AWS IAM Role to attach to the AWS STS (Security Token Service) generated short lived API keys. This is required since STS generated API Keys by default have restricted permissions and need to have their permissions elevated in order to authenticate with Terraform. Take note of Role ARN and ensure IAM Role has permission for “sts:AssumeRole”. For example:
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Principal": {
                "AWS": "*"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

In addition, you are required to also attach the AWS Managed policy of SecretsManagerReadWrite to this IAM role.

Note: this policy may be overly broad for many use cases, feel free to adjust accordingly to your organization's needs.

  1. In terminal, store as environmental variables AWS API Keys (while you can also hardcode in config files these will then be stored as plain text in .tfstate file and should be avoided if possible). For example:
export AWS_ACCESS_KEY_ID="secret"
export AWS_SECRET_ACCESS_KEY="secret”
  1. In terminal, use the AWS CLI command: aws sts assume-role --role-arn ROLE_ARN_FROM_ABOVE --role-session-name newSession

Note: AWS STS secrets are short lived by default, use the --duration-seconds flag to specify longer duration as needed

  1. Store each of the 3 new created secrets from AWS STS as environment variables. For example:
export AWS_ACCESS_KEY_ID="ASIAYBYSK3S5FZEKLETV"
export AWS_SECRET_ACCESS_KEY="lgT6kL9lr1fxM6mCEwJ33MeoJ1M6lIzgsiW23FGH"
export AWS_SESSION_TOKEN="IQoXX3+Q"
  1. Add assume_role block with role_arn, secret_name, and AWS region where secret is stored as part of AWS SM. Each of these 3 fields are REQUIRED. For example:
# Configure the MongoDB Atlas Provider to Authenticate with AWS Secrets Manager 
provider "mongodbatlas" {
  assume_role {
    role_arn = "arn:aws:iam::476xxx451:role/mdbsts"
  }
  secret_name           = "mongodbsecret"
  region                = "us-east-2"
  
  aws_access_key_id     = "ASIXXBNEK"
  aws_secret_access_key = "ZUZgVb8XYZWEXXEDURGFHFc5Au"
  aws_session_token     = "IQoXX3+Q="
  sts_endpoint          = "https://sts.us-east-2.amazonaws.com/"
}

Note: aws_access_key_id, aws_secret_access_key, and aws_session_token can also be passed in using environment variables i.e. aws_access_key_id will accept AWS_ACCESS_KEY_ID and TF_VAR_AWS_ACCESS_KEY_ID as a default value in place of value in a terraform file variable. Also sts_endpoint will be generated on behalf of user if not provider.

  1. In terminal, terraform init

Static Credentials

Static credentials can be provided by adding the following attributes in-line in the MongoDB Atlas provider block, either directly or via input variable/local value:

provider "mongodbatlas" {
  public_key = "atlas_public_api_key" #required
  private_key  = "atlas_private_api_key" #required
}

~> IMPORTANT Hard-coding your MongoDB Atlas programmatic API key pair into a Terraform configuration is not recommended. Consider the risks, especially the inadvertent submission of a configuration file containing secrets to a public repository.

Argument Reference

In addition to generic provider arguments (e.g. alias and version), the MongoDB Atlas provider supports the following arguments:

  • public_key - (Optional) This is the public key of your MongoDB Atlas API key pair. It must be provided, but it can also be sourced from the MONGODB_ATLAS_PUBLIC_KEY or MCLI_PUBLIC_API_KEY environment variable.

  • private_key - (Optional) This is the private key of your MongoDB Atlas key pair. It must be provided, but it can also be sourced from the MONGODB_ATLAS_PRIVATE_KEY or MCLI_PRIVATE_API_KEY environment variable.

For more information on configuring and managing programmatic API Keys see the MongoDB Atlas Documentation.

Helpful Links/Information

Upgrade Guide for Terraform MongoDB Atlas 0.4.0

MongoDB Atlas and Terraform Landing Page

Report bugs

Request Features

Support covered by MongoDB Atlas support plans, Developer and above.

Examples from MongoDB and the Community

We have example configurations in our GitHub repo that will help both beginner and more advanced users.

Have a good example you've created and want to share? Let us know the details via an issue or submit a PR of your work to add it to the examples directory in our GitHub repo.