doc: Adds `mongodbatlas_api_key_project_assignment` documentation, examples and migration guide #3465

oarbusi · 2025-07-03T14:24:59Z

Description

Adds mongodbatlas_api_key_project_assignment documentation, examples and migration guide.
Also removed the examples that were using the old patterns for API key assignment to projects to avoid customers from referencing those.
This corresponds to the documentation necessary for #3461

Link to any related issue(s): CLOUDP-215112

Type of change:

Bug fix (non-breaking change which fixes an issue). Please, add the "bug" label to the PR.
New feature (non-breaking change which adds functionality). Please, add the "enhancement" label to the PR. A migration guide must be created or updated if the new feature will go in a major version.
Breaking change (fix or feature that would cause existing functionality to not work as expected). Please, add the "breaking change" label to the PR. A migration guide must be created or updated.
This change requires a documentation update
Documentation fix/enhancement

Required Checklist:

I have signed the MongoDB CLA
I have read the contributing guides
I have checked that this change does not generate any credentials and that they are NOT accidentally logged anywhere.
I have added tests that prove my fix is effective or that my feature works per HashiCorp requirements
I have added any necessary documentation (if appropriate)
I have run make fmt and formatted my code
If changes include deprecations or removals I have added appropriate changelog entries.
If changes include removal or addition of 3rd party GitHub actions, I updated our internal document. Reach out to the APIx Integration slack channel to get access to the internal document.

Further comments

github-actions · 2025-07-03T14:25:42Z

APIx bot: a message has been sent to Docs Slack channel

docs/data-sources/api_key_project_assignment.md

docs/guides/project-api-key-migration.md

EspenAlbert · 2025-07-03T15:42:03Z

docs/guides/project-api-key-migration.md

+### Best Practices Before Importing
+- **Backup your Terraform state file** before making any changes.
+- **Review your current usage** of `mongodbatlas_project_api_key` and plan the migration for all affected resources.
+- **Test the migration in a non-production environment** if possible.


[nit] I would remove this

i think this can be a common section that can be referred in every migration doc, instead of "Review your current usage** of mongodbatlas_project_api_key" we can rephrase this to be more generic like "Review your current usage** of deprecate resource or something"

EspenAlbert · 2025-07-03T15:42:57Z

docs/guides/project-api-key-migration.md

+ ```
+2. **Import the existing API key into the API key resource:**
+ ```shell
+ terraform import mongodbatlas_api_key.example <ORG_ID>-<API_KEY_ID>


Can we also support / instead of - to be more consistent?

EspenAlbert · 2025-07-03T15:43:23Z

docs/guides/project-api-key-migration.md

+ ```shell
+ terraform import mongodbatlas_api_key_project_assignment.example <PROJECT_ID>/<API_KEY_ID>
+ ```
+4. **Remove the old resource from the Terraform state:**


Is this a use-case for import and removed block?

I was thinking the same

yes, I have clarified that removed block can be used

EspenAlbert · 2025-07-03T15:44:07Z

docs/guides/project-api-key-migration.md

+A: Existing keys will continue to work, but we recommend following the migration guide to move to the new pattern.
+
+**Q: What if I have many project assignments?**
+A: You can use `for_each` or `count` with `mongodbatlas_api_key_project_assignment` to manage multiple assignments efficiently.


Do we have any examples of this?

I think there's no need, for_each count are terraform features. I added links to the official documentation for this features

docs/guides/project-api-key-migration.md

examples/mongodbatlas_api_key/main.tf

EspenAlbert · 2025-07-03T15:47:06Z

examples/mongodbatlas_api_key/README.md


-Lastly, in MongoDB Atlas, all PAKs are Organization API keys. Once created, a PAK is linked at the organization level with an 'Organization Member' role. However, these Organization API keys can also be assigned to one or more projects within the organization. When a PAK is assigned to a specific project, it essentially takes on the 'Project Owner' role for that particular project. This enables the key to perform operations at the project level, in addition to the organization level. The flexibility of PAKs provides a powerful mechanism for fine-grained access and control, once their functioning is clearly understood. 
+```hcl
+resource "mongodbatlas_api_key" "test" {


I am not sure if we want duplicate main.tf content here

I think it doesn't hurt to have it here IMO

docs/data-sources/api_key_project_assignment.md

docs/data-sources/api_key_project_assignments.md

docs/data-sources/project_api_key.md

docs/guides/project-api-key-migration.md

marcosuma · 2025-07-04T06:27:24Z

docs/guides/project-api-key-migration.md

+}
+```
+
+## Migration using import


Remember the "Does this work for modules"? And I think this doesn't, right?

in any case we need an example specific for modules

Because the old resource corresponds to 2 resources, moved block is not possible and this wouldn't work for modules because import is needed. Will add a "Does this work for modules" section

Have added migration path for modules and example for modules in 0a856bd and b40d686
let me know what you think

docs/resources/api_key_project_assignment.md

marcosuma · 2025-07-04T06:34:39Z

examples/mongodbatlas_api_key/create-and-assign-pak-together/main.tf

@@ -1,16 +0,0 @@
-
-# Create Programmatic API Key + Assign Programmatic API Key to Project


question: shouldn't we still have these examples but just migrated to the new approach?

I think having the old pattern examples will be confusing and can lead to customers referencing those even if we now recommend the new pattern. Removing them and only having a single (new example) is better

got it, but aren't we removing the examples on how to use mongodbatlas_access_list_api_key ?

good point, I have added that back to the api_key example in 669bb50

examples/mongodbatlas_api_key/README.md

marcosuma · 2025-07-04T12:11:50Z

docs/guides/project-api-key-migration.md

+
+While this is not our recommended approach, you can still continue to use the `mongodbatlas_project_api_key` resource. If you are creating a new configuration, use the `mongodbatlas_api_key_project_assignment` resource.
+
+## Does this work for modules?


Thanks for the section, but I would remove it from here and put this text into "## Migration using Modules"

Makes sense, done in dc0790b

docs/data-sources/project_api_key.md

docs/data-sources/project_api_keys.md

docs/guides/project-api-key-migration.md

Co-authored-by: Leo Antoli <430982+lantoli@users.noreply.github.com>

AgustinBettati · 2025-07-04T14:24:13Z

docs/guides/project-api-key-migration.md

+
+## Main Changes Between Patterns
+
+| Old Pattern (`mongodbatlas_project_api_key`) | New Pattern (`mongodbatlas_api_key` + `mongodbatlas_api_key_project_assignment`) |


nit: This table is hard to read when using https://registry.terraform.io/tools/doc-preview, might be worthing just putting as sub titles

changed in e0ba552

AgustinBettati · 2025-07-04T14:26:23Z

docs/guides/project-api-key-migration.md

+5. **Remove the old resource block from your configuration**
+6. **Run `terraform plan` to review the changes.**
+ - Ensure that Terraform does not plan to delete or recreate your API keys or assignments.
+ - **Note:** After import, Terraform may show an in-place update for attributes like `org_id` on the `mongodbatlas_api_key` resource. This is expected and only updates the Terraform state to match your configuration; it does not change the actual resource in Atlas. You can safely apply this change.


just curious is this something we can fix in api_key import?

I think we could but not sure if it would be considered as a breaking change or not. To fix it we would need to change the behavior of the Read. If you see the import of the api_key resource, the encoded Id attribute is set, and then on the Read, more attributes are set but not org_id, so when the terraform apply after the import is done, a change is detected. e.g.

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols: ~ update in-place Terraform will perform the following actions: # module.api_key_assignment.mongodbatlas_api_key.this will be updated in-place ~ resource "mongodbatlas_api_key" "this" { ~ description = "Legacy module-managed API Key" -> "Module-managed API Key" id = "YXBpX2tleV9pZA==:Njg2N2E1ODg2YTdlOGQ0M2Q2ZTdlODFl-b3JnX2lk:NjBkZGY1NWMyN2E1YTIwOTU1YTcwN2Q3" + org_id = "60ddf55c27a5a20955a707d7" # (3 unchanged attributes hidden) } Plan: 0 to add, 1 to change, 0 to destroy.

open to discuss if this change is worth doing now

if org_id will be set every time in Read() then this would be a breaking change as it would result in non-empty plans right?

marcosuma · 2025-07-04T15:42:29Z

docs/guides/project-api-key-migration.md

+terraform import 'module.<module_name>.mongodbatlas_api_key.<name>' <ORG_ID>-<API_KEY_ID>
+terraform import 'module.<module_name>.mongodbatlas_api_key_project_assignment.<name>' <PROJECT_ID>/<API_KEY_ID>


Some customers who have platform and app teams have very distinct responsibilities. App teams, who would be the ones having to run this comment, don't have access to import capabilities. I think this should be converted into adding the import block in the configuration rather than as a command. I believe that should work

I am also very worried that this is the only suggestion we can make. Imagine a very big customer with hundreds of app teams, each team is expected to do that if they want to migrate to our recommended approach. That's never going to happen.

is the project_assignment an idempotent type of resource? What I mean is: if mongodbatlas_api_key_project_assignment is being created in TF but that assignment already exists, will it fail? or simply succeed? if that's the case we could recommend a moved from project_api_key to api_key and then the mongodbatlas_api_key_project_assignment would be defined as "new" resources

added explicit mention of import block throughout the doc in ec95e5f.

davidhou17

LGTM % nits

docs/resources/api_key_project_assignment.md

templates/resources/api_key_project_assignment.md.tmpl

maastha · 2025-07-07T15:29:11Z

docs/guides/project-api-key-migration.md

@@ -0,0 +1,229 @@
+---
+page_title: "Migration Guide: Project API Key to API Key + Assignment"


Suggested change

page_title: "Migration Guide: Project API Key to API Key + Assignment"

page_title: "Migration Guide: Project API Key to API Key + Project Assignment"

maastha · 2025-07-07T15:33:29Z

docs/guides/project-api-key-migration.md

+### Best Practices Before Importing
+- **Backup your Terraform state file** before making any changes.
+- **Review your current usage** of `mongodbatlas_project_api_key` and plan the migration for all affected resources.
+- **Test the migration in a non-production environment** if possible.


i think this can be a common section that can be referred in every migration doc, instead of "Review your current usage** of mongodbatlas_project_api_key" we can rephrase this to be more generic like "Review your current usage** of deprecate resource or something"

maastha · 2025-07-07T15:46:58Z

docs/guides/project-api-key-migration.md

+5. **Remove the old resource block from your configuration**
+6. **Run `terraform plan` to review the changes.**
+ - Ensure that Terraform does not plan to delete or recreate your API keys or assignments.
+ - **Note:** After import, Terraform may show an in-place update for attributes like `org_id` on the `mongodbatlas_api_key` resource. This is expected and only updates the Terraform state to match your configuration; it does not change the actual resource in Atlas. You can safely apply this change.


if org_id will be set every time in Read() then this would be a breaking change as it would result in non-empty plans right?

oarbusi added 5 commits July 3, 2025 15:17

delete old examples

937a5aa

example

8b4c7fc

api_key_project_assignment docs

c8f3890

migration guide and notes on old resource

cac625f

format

cf4a06a

oarbusi marked this pull request as ready for review July 3, 2025 14:25

oarbusi requested review from a team as code owners July 3, 2025 14:25

format

ac4cc44

oarbusi mentioned this pull request Jul 3, 2025

feat: Adds new mongodbatlas_api_key_project_assignment resource #3461

Open

13 tasks

oarbusi added 2 commits July 3, 2025 16:55

doc

dce4f2b

remove referende of old example

4f30f80

EspenAlbert reviewed Jul 3, 2025

View reviewed changes

docs/data-sources/api_key_project_assignment.md Outdated Show resolved Hide resolved

EspenAlbert reviewed Jul 3, 2025

View reviewed changes

docs/guides/project-api-key-migration.md Outdated Show resolved Hide resolved

EspenAlbert reviewed Jul 3, 2025

View reviewed changes

docs/guides/project-api-key-migration.md Outdated Show resolved Hide resolved

EspenAlbert reviewed Jul 3, 2025

View reviewed changes

docs/guides/project-api-key-migration.md Outdated Show resolved Hide resolved

EspenAlbert reviewed Jul 3, 2025

View reviewed changes

examples/mongodbatlas_api_key/main.tf Outdated Show resolved Hide resolved

EspenAlbert reviewed Jul 3, 2025

View reviewed changes

marcosuma reviewed Jul 4, 2025

View reviewed changes

docs/data-sources/api_key_project_assignment.md Outdated Show resolved Hide resolved

marcosuma reviewed Jul 4, 2025

View reviewed changes

docs/data-sources/api_key_project_assignments.md Outdated Show resolved Hide resolved

marcosuma reviewed Jul 4, 2025

View reviewed changes

docs/data-sources/project_api_key.md Outdated Show resolved Hide resolved

marcosuma reviewed Jul 4, 2025

View reviewed changes

docs/guides/project-api-key-migration.md Show resolved Hide resolved

marcosuma reviewed Jul 4, 2025

View reviewed changes

docs/guides/project-api-key-migration.md Show resolved Hide resolved

marcosuma reviewed Jul 4, 2025

View reviewed changes

docs/resources/api_key_project_assignment.md Outdated Show resolved Hide resolved

marcosuma reviewed Jul 4, 2025

View reviewed changes

examples/mongodbatlas_api_key/README.md Show resolved Hide resolved

oarbusi added 7 commits July 4, 2025 09:39

espen comments

c7db025

remove duplicated

d8a750e

fix example

098f8ee

marco comments

2771500

example seo

846cafa

module example and migration path

0a856bd

module example and migration path

b40d686

marcosuma reviewed Jul 4, 2025

View reviewed changes

oarbusi added 2 commits July 4, 2025 15:14

comment

dc0790b

attach access list to api key in the example

669bb50

lantoli reviewed Jul 4, 2025

View reviewed changes

docs/data-sources/project_api_key.md Outdated Show resolved Hide resolved

lantoli reviewed Jul 4, 2025

View reviewed changes

docs/data-sources/project_api_keys.md Outdated Show resolved Hide resolved

remove unnecessary space

24fc1f8

lantoli reviewed Jul 4, 2025

View reviewed changes

docs/guides/project-api-key-migration.md Outdated Show resolved Hide resolved

lantoli approved these changes Jul 4, 2025

View reviewed changes

oarbusi and others added 2 commits July 4, 2025 15:45

gen doc

a0f0377

Update docs/guides/project-api-key-migration.md

13aab93

Co-authored-by: Leo Antoli <430982+lantoli@users.noreply.github.com>

AgustinBettati reviewed Jul 4, 2025

View reviewed changes

marcosuma reviewed Jul 4, 2025

View reviewed changes

oarbusi added 2 commits July 7, 2025 09:56

import block

ec95e5f

table change

e0ba552

davidhou17 approved these changes Jul 7, 2025

View reviewed changes

docs/resources/api_key_project_assignment.md Outdated Show resolved Hide resolved

templates/resources/api_key_project_assignment.md.tmpl Outdated Show resolved Hide resolved

pr comments

aaea05c

maastha reviewed Jul 7, 2025

View reviewed changes

		@@ -1,16 +0,0 @@

		# Create Programmatic API Key + Assign Programmatic API Key to Project


		While this is not our recommended approach, you can still continue to use the `mongodbatlas_project_api_key` resource. If you are creating a new configuration, use the `mongodbatlas_api_key_project_assignment` resource.

		## Does this work for modules?


		## Main Changes Between Patterns

		\| Old Pattern (`mongodbatlas_project_api_key`) \| New Pattern (`mongodbatlas_api_key` + `mongodbatlas_api_key_project_assignment`) \|

		terraform import 'module.<module_name>.mongodbatlas_api_key.<name>' <ORG_ID>-<API_KEY_ID>
		terraform import 'module.<module_name>.mongodbatlas_api_key_project_assignment.<name>' <PROJECT_ID>/<API_KEY_ID>

		@@ -0,0 +1,229 @@
		---
		page_title: "Migration Guide: Project API Key to API Key + Assignment"

doc: Adds mongodbatlas_api_key_project_assignment documentation, examples and migration guide #3465

Are you sure you want to change the base?

doc: Adds mongodbatlas_api_key_project_assignment documentation, examples and migration guide #3465

Conversation

oarbusi commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change:

Required Checklist:

Further comments

github-actions bot commented Jul 3, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidhou17 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

doc: Adds `mongodbatlas_api_key_project_assignment` documentation, examples and migration guide #3465

doc: Adds `mongodbatlas_api_key_project_assignment` documentation, examples and migration guide #3465

oarbusi commented Jul 3, 2025 •

edited

Loading