diff --git a/docs/guides/provider-configuration.md b/docs/guides/provider-configuration.md new file mode 100644 index 0000000000..77eeaeafcd --- /dev/null +++ b/docs/guides/provider-configuration.md @@ -0,0 +1,176 @@ +--- +page_title: "Guide: Provider Configuration" +--- + +# Provider Configuration + +This guide covers authentication and configuration options for the MongoDB Atlas Provider. + +## Authentication Methods + +The MongoDB Atlas provider supports the following authentication methods: + +1. [**Service Account (SA)** - Recommended](#service-account-recommended) +2. [**Programmatic Access Key (PAK)**](#programmatic-access-key) + +Credentials can be provided through (in priority order): + +- AWS Secrets Manager +- Provider attributes +- Environment variables + +The provider uses the first available credentials source. + +### Service Account (Recommended) + +SAs simplify authentication by eliminating the need to create new Atlas-specific user identities and permission credentials. See [Service Accounts Overview](https://www.mongodb.com/docs/atlas/api/service-accounts-overview/) and [MongoDB Atlas Service Account Limits](https://www.mongodb.com/docs/manual/reference/limits/#mongodb-atlas-service-account-limits) for more information. + +To use SA authentication, create an SA in your [MongoDB Atlas organization](https://www.mongodb.com/docs/atlas/configure-api-access/#grant-programmatic-access-to-an-organization) and set the credentials, for example: + +```terraform +provider "mongodbatlas" { + client_id = var.mongodbatlas_client_id + client_secret = var.mongodbatlas_client_secret +} +``` + +**Note:** SAs can't be used with `mongodbatlas_event_trigger` resources because its API doesn't support it yet. + +### Programmatic Access Key + +Generate a PAK with the appropriate [role](https://docs.atlas.mongodb.com/reference/user-roles/). See the [MongoDB Atlas documentation](https://www.mongodb.com/docs/atlas/configure-api-access-org/) for detailed instructions. + +**Role recommendation:** If unsure which role to grant, use an organization API key with the Organization Owner role to ensure sufficient access as in the following example: + +```terraform +provider "mongodbatlas" { + public_key = var.mongodbatlas_public_key + private_key = var.mongodbatlas_private_key +} +``` + +~> **Migrating from PAK to SA:** Update your provider attributes or environment variables to use SA credentials instead of PAK credentials, then run `terraform plan` to verify everything works correctly. + +## AWS Secrets Manager + +The provider supports retrieving credentials from AWS Secrets Manager. See [AWS Secrets Manager documentation](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) for more details. + +### Setup Instructions + +1. **Create secrets in AWS Secrets Manager** + + For SA, create a secret with the following key-value pairs: + - `client_id`: your-client-id + - `client_secret`: your-client-secret + + For PAK, create a secret with the following key-value pairs: + - `public_key`: your-public-key + - `private_key`: your-private-key + +2. **Create an IAM Role** with: + - Permission for `sts:AssumeRole` + - Attached AWS managed policy `SecretsManagerReadWrite` + +3. **Configure AWS credentials** (using AWS CLI or environment variables) + +4. **Assume the role** to obtain STS credentials + + ```shell + aws sts assume-role --role-arn --role-session-name newSession + ``` + +5. **Configure provider with AWS Secrets Manager** + + Using provider attributes: + + ```terraform + provider "mongodbatlas" { + aws_access_key_id = var.aws_access_key_id + aws_secret_access_key = var.aws_secret_access_key + aws_session_token = var.aws_session_token + assume_role = "arn:aws:iam:::role/mdbsts" + secret_name = "mongodbsecret" + region = "us-east-2" + } + ``` + + Alternatively, you can use environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `ASSUME_ROLE_ARN`, `SECRET_NAME`, `AWS_REGION`). + +### Cross-Account and Cross-Region Access + +For cross-account secrets, use the fully qualified ARN for `secret_name`. For cross-region or cross-account access, the `sts_endpoint` parameter is required, for example: + +```terraform +provider "mongodbatlas" { + aws_access_key_id = var.aws_access_key_id + aws_secret_access_key = var.aws_secret_access_key + aws_session_token = var.aws_session_token + assume_role = "arn:aws:iam:::role/mdbsts" + secret_name = "arn:aws:secretsmanager:us-east-1::secret:test789-TO06Hy" + region = "us-east-2" + sts_endpoint = "https://sts.us-east-2.amazonaws.com/" +} +``` + +## Provider Configuration Reference + +### Provider Arguments + +* `client_id` - (Optional) SA Client ID (env: `MONGODB_ATLAS_CLIENT_ID`). +* `client_secret` - (Optional) SA Client Secret (env: `MONGODB_ATLAS_CLIENT_SECRET`). +* `access_token` - (Optional) SA Access Token (env: `MONGODB_ATLAS_ACCESS_TOKEN`). Instead of using Client ID and Client Secret, you can generate and use an SA token directly. See [Generate Service Account Token](https://www.mongodb.com/docs/atlas/api/service-accounts/generate-oauth2-token/#std-label-generate-oauth2-token-atlas) for details. Note: tokens have expiration times. +* `public_key` - (Optional) PAK Public Key (env: `MONGODB_ATLAS_PUBLIC_API_KEY`). +* `private_key` - (Optional) PAK Private Key (env: `MONGODB_ATLAS_PRIVATE_API_KEY`). +* `base_url` - (Optional) MongoDB Atlas Base URL (env: `MONGODB_ATLAS_BASE_URL`). For advanced use cases, you can configure custom API endpoints. +* `realm_base_url` - (Optional) MongoDB Realm Base URL (env: `MONGODB_REALM_BASE_URL`). +* `is_mongodbgov_cloud` - (Optional) Set to `true` to use MongoDB Atlas for Government, a dedicated deployment option for government agencies and contractors requiring FedRAMP compliance. When enabled, the provider uses government-specific API endpoints. Ensure credentials are created in the government environment. See [Atlas for Government Considerations](https://www.mongodb.com/docs/atlas/government/api/#atlas-for-government-considerations) for feature limitations and requirements. + ```terraform + provider "mongodbatlas" { + client_id = var.mongodbatlas_client_id + client_secret = var.mongodbatlas_client_secret + is_mongodbgov_cloud = true + } + ``` +* `assume_role` - (Optional) AWS IAM role configuration for accessing secrets in AWS Secrets Manager. Role ARN env: `ASSUME_ROLE_ARN`. See [AWS Secrets Manager](#aws-secrets-manager) section for details. +* `secret_name` - (Optional) Name of the secret in AWS Secrets Manager (env: `SECRET_NAME`). +* `region` - (Optional) AWS region where the secret is stored (env: `AWS_REGION`). +* `aws_access_key_id` - (Optional) AWS Access Key ID (env: `AWS_ACCESS_KEY_ID`). +* `aws_secret_access_key` - (Optional) AWS Secret Access Key (env: `AWS_SECRET_ACCESS_KEY`). +* `aws_session_token` - (Optional) AWS Session Token (env: `AWS_SESSION_TOKEN`). +* `sts_endpoint` - (Optional) AWS STS endpoint (env: `STS_ENDPOINT`). + +## Credential Priority + +When multiple credentials are provided in the same source, the provider uses this priority order: + +1. Access Token +2. Service Account (SA) +3. Programmatic Access Key (PAK) + +The provider displays a warning when multiple credentials are detected. + +## Supported OS and Architectures + +As per [HashiCorp's recommendations](https://developer.hashicorp.com/terraform/registry/providers/os-arch), the MongoDB Atlas Provider fully supports the following operating system / architecture combinations: + +- Darwin / AMD64 +- Darwin / ARMv8 +- Linux / AMD64 +- Linux / ARMv8 (AArch64/ARM64) +- Linux / ARMv6 +- Windows / AMD64 + +We ship binaries but do not prioritize fixes for the following operating system / architecture combinations: + +- Linux / 386 +- Windows / 386 +- FreeBSD / 386 +- FreeBSD / AMD64 + +## Additional Resources + +- [MongoDB Atlas API Documentation](https://www.mongodb.com/docs/atlas/api/) +- [Service Accounts Overview](https://www.mongodb.com/docs/atlas/api/service-accounts-overview/) +- [Configure API Access](https://www.mongodb.com/docs/atlas/configure-api-access/) +- [Atlas for Government](https://www.mongodb.com/docs/atlas/government/) +- [Terraform Provider Documentation](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs) diff --git a/docs/index.md b/docs/index.md index adeb233c8d..0496159637 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,180 +1,83 @@ # MongoDB Atlas Provider -You can use the MongoDB Atlas provider to interact with the resources supported by [MongoDB Atlas](https://www.mongodb.com/cloud/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. - -See [CHANGELOG](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/master/CHANGELOG.md) for current version information. +The MongoDB Atlas provider is used to interact with the resources supported by [MongoDB Atlas](https://www.mongodb.com/cloud/atlas). The provider needs to be configured with proper credentials before it can be used. ## Example Usage -```terraform -# Configure the MongoDB Atlas Provider -provider "mongodbatlas" { - public_key = var.mongodbatlas_public_key - private_key = var.mongodbatlas_private_key -} -# Create the resources -``` - -### Provider and terraform version constraints - -We recommend that you pin your Atlas [provider version](https://developer.hashicorp.com/terraform/language/providers/requirements#version) to at least the [major version](#versioning-strategy) (e.g. `~> 2.0`) to avoid accidental upgrades to incompatible new versions. Starting on `2.0.0`, the [MongoDB Atlas Provider Versioning Policy](#mongodb-atlas-provider-versioning-policy) ensures that minor and patch versions do not include [Breaking Changes](#definition-of-breaking-changes). - -For Terraform version, we recommend that you use the latest [HashiCorp Terraform Core Version](https://github.com/hashicorp/terraform). For more details see [HashiCorp Terraform Version Compatibility Matrix](#hashicorp-terraform-version-compatibility-matrix). - -## 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](https://docs.atlas.mongodb.com/reference/user-roles/). -The [MongoDB Atlas documentation](https://docs.atlas.mongodb.com/tutorial/manage-programmatic-access/index.html) contains the most up-to-date instructions for creating and managing your key(s), setting the appropriate role, and optionally configuring IP access. +This example shows how to set up the MongoDB Atlas provider and create a cluster: -**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. - -## 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: ```terraform -# 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 + client_id = var.mongodbatlas_client_id + client_secret = var.mongodbatlas_client_secret } -# Create the resources -``` -Also see [`Atlas for Government Considerations`](https://www.mongodb.com/docs/atlas/government/api/#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_API_KEY` and `MONGODB_ATLAS_PRIVATE_API_KEY`, -for your public and private MongoDB Atlas programmatic API key pair respectively: - -```terraform -provider "mongodbatlas" {} -``` - -Usage (prefix the export commands with a space to avoid the keys being recorded in OS history): -```shell -$ export MONGODB_ATLAS_PUBLIC_API_KEY="" -$ export MONGODB_ATLAS_PRIVATE_API_KEY="" -$ terraform plan -``` - -We recommend that you use the `MONGODB_ATLAS_PUBLIC_API_KEY` and `MONGODB_ATLAS_PRIVATE_API_KEY` environment variables because they are compatible with other MongoDB tools, such as Atlas CLI. -You can still use `MONGODB_ATLAS_PUBLIC_KEY` and `MONGODB_ATLAS_PRIVATE_KEY` as alternative keys in your local environment. However, these environment variables are not guaranteed to work across all tools in the MongoDB ecosystem. - -### 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](https://aws.amazon.com/secrets-manager/) and [documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/what-is-systems-manager.html) for more details. +# Create a project +resource "mongodbatlas_project" "this" { + name = "my-project" + org_id = var.org_id +} -In order to enable the Terraform MongoDB Atlas Provider with AWS SM, please follow the below steps: +# Create a cluster +resource "mongodbatlas_advanced_cluster" "this" { + project_id = mongodbatlas_project.this.id + name = "my-cluster" + cluster_type = "REPLICASET" -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" - } -``` -2. 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": [ + replication_specs = [ + { + region_configs = [ { - "Sid": "Statement1", - "Effect": "Allow", - "Principal": { - "AWS": "*" - }, - "Action": "sts:AssumeRole" + region_name = "US_EAST_1" + priority = 7 + provider_name = "AWS" + electable_specs = { + instance_size = "M10" + node_count = 3 + } } - ] + ] + } + ] } ``` -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. +## Authentication -3. 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='' -export AWS_SECRET_ACCESS_KEY='' -``` -4. 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 - -5. Store each of the 3 new created secrets from AWS STS as environment variables (hardcoding secrets into config file with additional risk is also supported). For example: -``` -export AWS_ACCESS_KEY_ID='' -export AWS_SECRET_ACCESS_KEY='' -export AWS_SESSION_TOKEN="" -``` +The MongoDB Atlas provider uses Service Account (SA) as the recommended authentication method. -6. 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: -```terraform -# Configure the MongoDB Atlas Provider to Authenticate with AWS Secrets Manager -provider "mongodbatlas" { - assume_role { - role_arn = "arn:aws:iam:::role/mdbsts" - } - secret_name = "mongodbsecret" - // fully qualified secret_name ARN also supported as input "arn:aws:secretsmanager:af-south-1::secret:test789-TO06Hy" - region = "us-east-2" - - aws_access_key_id = "" - aws_secret_access_key = "" - aws_session_token = "" - 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. +For detailed authentication configuration, see: +- [Service Account (SA)](guides/provider-configuration#service-account-recommended) +- [Programmatic Access Key (PAK)](guides/provider-configuration#programmatic-access-key) +- [AWS Secrets Manager integration](guides/provider-configuration#aws-secrets-manager) -Note: Fully qualified `secret_name` ARN as input is REQUIRED for cross-AWS account secrets. For more detatils see: -* https://aws.amazon.com/blogs/security/how-to-access-secrets-across-aws-accounts-by-attaching-resource-based-policies/ -* https://aws.amazon.com/premiumsupport/knowledge-center/secrets-manager-share-between-accounts/ +## MongoDB Atlas for Government -Note: `sts_endpoint` parameter is REQUIRED for cross-AWS region or cross-AWS account secrets. +MongoDB Atlas for Government is a dedicated deployment option for government agencies and contractors requiring FedRAMP compliance. +For more details on configuration, see the [Provider Configuration Guide](guides/provider-configuration#provider-arguments). -7. In terminal, `terraform init` +## Version Requirements -### Static Credentials +### Provider Version -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: +We recommend pinning your provider version to at least the major version (e.g., `~> 2.0`) to avoid accidental upgrades to incompatible new versions: ```terraform -provider "mongodbatlas" { - public_key = "atlas_public_api_key" #required - private_key = "atlas_private_api_key" #required +terraform { + required_providers { + mongodbatlas = { + source = "mongodb/mongodbatlas" + version = "~> 2.0" + } + } } ``` -~> *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](https://www.terraform.io/docs/configuration/providers.html) -(e.g. `alias` and `version`), the MongoDB Atlas `provider` supports the following arguments: +Starting with version 2.0.0, the [MongoDB Atlas Provider Versioning Policy](#mongodb-atlas-provider-versioning-policy) ensures that minor and patch versions do not include breaking changes. -* `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. +### Terraform Version -* `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](https://docs.atlas.mongodb.com/tutorial/manage-programmatic-access/index.html). +We recommend using the latest [HashiCorp Terraform Core Version](https://github.com/hashicorp/terraform). See the [HashiCorp Terraform Version Compatibility Matrix](#hashicorp-terraform-version-compatibility-matrix) below for supported versions. ## MongoDB Atlas Provider Versioning Policy @@ -247,7 +150,7 @@ We are committed to clear and proactive communication: --- -## [HashiCorp Terraform Version](https://www.terraform.io/downloads.html) Compatibility Matrix +## HashiCorp Terraform Version Compatibility Matrix @@ -267,19 +170,8 @@ For the safety of our users, we require only consuming versions of HashiCorp Ter HashiCorp Terraform versions that are not listed on this table are no longer supported by MongoDB Atlas. For latest HashiCorp Terraform versions see [here](https://endoflife.date/terraform ). ## Supported OS and Architectures -As per [HashiCorp's recommendations](https://developer.hashicorp.com/terraform/registry/providers/os-arch), we fully support the following operating system / architecture combinations: -- Darwin / AMD64 -- Darwin / ARMv8 -- Linux / AMD64 -- Linux / ARMv8 (sometimes referred to as AArch64 or ARM64) -- Linux / ARMv6 -- Windows / AMD64 - -We ship binaries but do not prioritize fixes for the following operating system / architecture combinations: -- Linux / 386 -- Windows / 386 -- FreeBSD / 386 -- FreeBSD / AMD64 + +The MongoDB Atlas Provider supports multiple operating systems and architectures. See the [Provider Configuration Guide](guides/provider-configuration#supported-os-and-architectures) for the complete list of supported platforms. ## Helpful Links/Information