doc: Add user journey considerations in current resource and example documentation #2559

AgustinBettati · 2024-09-05T12:34:52Z

Description

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

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

examples/mongodbatlas_encryption_at_rest_private_endpoint/azure/README.md

github-actions · 2024-09-05T12:58:30Z

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

EspenAlbert · 2024-09-05T13:10:59Z

docs/resources/encryption_at_rest.md

+#### Manage Customer Keys with Azure Key Vault Over Private Endpoints
+It is possible to configure Atlas Encryption at Rest to communicate with Azure Key Vault using Azure Private Link, ensuring that all traffic between Atlas and Key Vault takes place over Azure’s private network interfaces. This requires enabling `azure_key_vault_config.require_private_networking` attribute, together with the configuration of `mongodbatlas_encryption_at_rest_private_endpoint` resource. 
+
+Please review [`mongodbatlas_encryption_at_rest_private_endpoint` resource documentation](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/encryption_at_rest_private_endpoint) and [complete example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_encryption_at_rest_private_endpoint/azure) for details on this functionality.


use relative links:

Suggested change

Please review [`mongodbatlas_encryption_at_rest_private_endpoint` resource documentation](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/encryption_at_rest_private_endpoint) and [complete example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_encryption_at_rest_private_endpoint/azure) for details on this functionality.

Please review [`mongodbatlas_encryption_at_rest_private_endpoint` resource documentation](encryption_at_rest_private_endpoint) and [complete example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_encryption_at_rest_private_endpoint/azure) for details on this functionality.

(see this PR for relative link examples)

Ahh. Maybe this happens since this is generated and the original text lives in the examples directory?

EspenAlbert

LGTM

maastha · 2024-09-05T13:55:13Z

docs/resources/encryption_at_rest.md

-The [encryption at rest Terraform module](https://registry.terraform.io/modules/terraform-mongodbatlas-modules/encryption-at-rest/mongodbatlas/latest) makes use of this resource and simplifies its use.
-
-After configuring at least one Encryption at Rest provider for the Atlas project, Project Owners can enable Encryption at Rest for each Atlas cluster for which they require encryption. The Encryption at Rest provider does not have to match the cluster cloud service provider.
+After configuring at least one key management provider for an Atlas project, Project Owners can enable customer key management for each Atlas cluster for which they require encryption. For clusters defined in terraform, the `encryption_at_rest_provider` attribute can be used in both `mongodbatlas_advanced_cluster` and `mongodbatlas_cluster` resources. The key management provider does not have to match the cluster cloud service provider.


Should we add this link to the attribute here to make it more clear https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/cluster#encryption_at_rest_provider ?

docs/resources/encryption_at_rest.md

docs/resources/encryption_at_rest_private_endpoint.md

maastha · 2024-09-06T13:51:46Z

docs/resources/encryption_at_rest.md

@@ -23,6 +20,13 @@ See [Encryption at Rest](https://docs.atlas.mongodb.com/security-kms-encryption/

 -> **IMPORTANT NOTE** To disable the encryption at rest with customer key management for a project all existing clusters in the project must first either have encryption at rest for the provider set to none, e.g. `encryption_at_rest_provider = "NONE"`, or be deleted.

+## Enabling Encryption at Rest for existing Atlas cluster
+
+After configuring at least one key management provider for an Atlas project, Project Owners can enable customer key management for each Atlas cluster for which they require encryption. For clusters defined in terraform, the [`encryption_at_rest_provider` attribute](advanced_cluster#encryption_at_rest_provider) can be used in both `mongodbatlas_advanced_cluster` and `mongodbatlas_cluster` resources. The key management provider does not have to match the cluster cloud service provider.


just confirming, is the advanced_cluster#encryption_at_rest_provider link correct? It should work in this current markup doc right?

will confirm once Leo publishs the docs in his testing provider

Confirmed relative path works well once published in registry

docs/resources/encryption_at_rest_private_endpoint.md

maastha

2 small comments, otherwise LGTM

maastha · 2024-09-06T14:15:09Z

docs/resources/encryption_at_rest_private_endpoint.md


 ## Example Usages

+-> **NOTE:** Only Azure Key Vault with Azure Private Link is supported at this time.


Should we also include this in the data source documentation?

no harm in clarifying there as well since cloud_provider is a required attribute for both data sources.

maastha · 2024-09-06T14:16:13Z

docs/resources/encryption_at_rest_private_endpoint.md

@@ -2,15 +2,21 @@

 `mongodbatlas_encryption_at_rest_private_endpoint` provides a resource for managing a private endpoint used for encryption at rest with customer-managed keys. This ensures all traffic between Atlas and customer key management systems take place over private network interfaces.

-~> **IMPORTANT** The Encryption at Rest using Azure Key Vault over Private Endpoints feature is available by request. To request this functionality for you Atlas deployments, contact your Account Manager. 
+~> **IMPORTANT** The Encryption at Rest using Azure Key Vault over Private Endpoints feature is available by request. To request this functionality for your Atlas deployments, contact your Account Manager. 


I think this should also be included in data source doc otherwise I believe users will get error, WDYT?

included 👍

Co-authored-by: maastha <[email protected]>

maastha · 2024-09-06T15:48:43Z

Thanks for addressing all the comments!

…o master (#2569) * update sdk dev (#2490) * chore: Creates TF models & interfaces for new `mongodbatlas_encryption_at_rest_private_endpoint` resource (#2493) * chore: Creates TF models & interfaces for new `mongodbatlas_encryption_at_rest_private_endpoint` data source (#2500) * feat: Updates `mongodbatlas_encryption_at_rest` resource to use new `azure_key_vault_config.require_private_networking` field (#2509) * chore: Creates TF models & interfaces for `mongodbatlas_encryption_at_rest_private_endpoints` plural data source (#2502) * feat: Implements `mongodbatlas_encryption_at_rest_private_endpoint` resource (#2512) * wip - implementing CRUD * include changelog entry * small adjustments * supporting state transition logic * implement acceptance test * add unit testing for state transitions * handle return error message if failed status is present * add acceptance test transitioning for public to private network * improve messaging for failed status * fix prechecks * use global const for resource name * avoid hardcoded value * adjust state transition logic for delete * adjusting target version in migration test to 1.19.0 * adjust default refresh to 30 seconds for quicker response * feat: Implements `mongodbatlas_encryption_at_rest_private_endpoint` singular data source (#2527) * implement singular data source * including changelog entry * doc: Updates existing documentation for `mongodbatlas_encryption_at_rest` resource to be auto-generated (#2529) * doc: Include example for new `mongodbatlas_encryption_at_rest_private_endpoint` resource (#2540) * Include example for ear with private endpoint * fix example * adjust readme * Update examples/mongodbatlas_encryption_at_rest_private_endpoint/azure/README.md Co-authored-by: maastha <[email protected]> * Update examples/mongodbatlas_encryption_at_rest_private_endpoint/azure/README.md Co-authored-by: maastha <[email protected]> * add example cli command * make use of variables to make value of resource id more compact --------- Co-authored-by: maastha <[email protected]> * feat: Implements new `mongodbatlas_encryption_at_rest_private_endpoints` data source (#2536) * temporary change to cloud provider access and getting latest sdk * implements plural data source * adapted cloud provider access with latest changes from dev preview * fix unit test * adding changelog entry * add changes to verify plural data source in basic test case * doc adjust to cloud_provider attribute * feat: Implements new `mongodbatlas_encryption_at_rest` singular data source & adds `valid` attribute for cloud provider configs in the resource (#2538) * fix: Adds error message handling to `mongodbatlas_encryption_at_rest_private_endpoint` resource (#2544) * doc: Adds documentation for new `encryption_at_rest_private_endpoint` resource and data sources (#2547) * adding documentation for encryption_at_rest_private_endpoint resource and data sources * align generated docs * minor typo fix * Adjust description of project_id to make it more concise * align note stating feature is available by request as defined in general docs * chore: Adopt latest changes from master into ear private endpoint dev branch to adopt latest SDK (#2549) * test: Reduce instance size and use of provisioned disk iops for test that verifies transition for symmetric to asymmetric configuration (#2503) * doc: Include changelog entries to mention 2 new guides (#2506) * add entry for 2 new guides * add link * chore: Updates examples link in index.md for v1.18.0 release * chore: Updates CHANGELOG.md header for v1.18.0 release * doc: Update Atlas SP db_role_to_execute info. (#2508) * (DOCSP-41590) Updating Atlas SP db_role_to_execute info. * Update docs/resources/stream_connection.md Co-authored-by: kanchana-mongodb <[email protected]> --------- Co-authored-by: kanchana-mongodb <[email protected]> * doc: Contributing Guidelines Updates (#2494) * Contributing Guidelines Updates * Update README.md * Update README.md * Update contributing/README.md Co-authored-by: kyuan-mongodb <[email protected]> --------- Co-authored-by: kyuan-mongodb <[email protected]> * test: Simply migration test checks after 1.18.0 release and adjust version constraint in advanced_cluster examples uing new schema (#2510) * doc: Add references to the terraform modules in the resources documentations (#2513) * add references to the modules in the resources documentations * fix pr comments * chore: Bump hashicorp/setup-terraform from 3.1.1 to 3.1.2 (#2515) Bumps [hashicorp/setup-terraform](https://github.com/hashicorp/setup-terraform) from 3.1.1 to 3.1.2. - [Release notes](https://github.com/hashicorp/setup-terraform/releases) - [Changelog](https://github.com/hashicorp/setup-terraform/blob/main/CHANGELOG.md) - [Commits](hashicorp/setup-terraform@651471c...b9cd54a) --- updated-dependencies: - dependency-name: hashicorp/setup-terraform dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore: Add mention of support ticket when opening a pull request (#2507) * Add mention of creating support ticket when opening PR * rephrasing to avoid mention of priority * including suggestion * doc: Updates`mongodbatlas_advanced_cluster` ISS migration guide & resource doc with expected 500 error on update (#2525) * chore: Updates mongodbatlas_advanced_cluster tests to expect temporary SERVICE_UNAVAILABLE error when migrating from old to new schema (#2523) * doc: Fixes wordings in the new advanced_cluster sharding guide. (#2524) * chore: Updates examples link in index.md for v1.18.1 release * chore: Updates CHANGELOG.md header for v1.18.1 release * chore: upgrades go SDK from `v20240805001` to `v20240805002` (#2534) * chore: Updates to Go 1.23 (#2535) * update asdf TF version * update to Go 1.23 * update linter * update golang-ci linter * disable Go telemetry * revert TF change * chore: Bump go.mongodb.org/atlas from 0.36.0 to 0.37.0 (#2532) Bumps [go.mongodb.org/atlas](https://github.com/mongodb/go-client-mongodb-atlas) from 0.36.0 to 0.37.0. - [Release notes](https://github.com/mongodb/go-client-mongodb-atlas/releases) - [Changelog](https://github.com/mongodb/go-client-mongodb-atlas/blob/master/CHANGELOG.md) - [Commits](mongodb/go-client-mongodb-atlas@v0.36.0...v0.37.0) --- updated-dependencies: - dependency-name: go.mongodb.org/atlas dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore: Bump github.com/hashicorp/hcl/v2 from 2.21.0 to 2.22.0 (#2530) Bumps [github.com/hashicorp/hcl/v2](https://github.com/hashicorp/hcl) from 2.21.0 to 2.22.0. - [Release notes](https://github.com/hashicorp/hcl/releases) - [Changelog](https://github.com/hashicorp/hcl/blob/main/CHANGELOG.md) - [Commits](hashicorp/hcl@v2.21.0...v2.22.0) --- updated-dependencies: - dependency-name: github.com/hashicorp/hcl/v2 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * update asdf TF version to 1.9.5 (#2537) * chore: Changes deprecation message for labels attribute (#2542) * chore: Upgrades go SDK from `v20240805002` to `v20240805003` (#2545) * major version update calling gomajor tool * manual change to reincorporate v20240530005 * reverts temp changes in cloud provider resources, fixes sdk versions in new implementations --------- Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: svc-apix-bot <[email protected]> Co-authored-by: lmkerbey-mdb <[email protected]> Co-authored-by: kanchana-mongodb <[email protected]> Co-authored-by: Zuhair Ahmed <[email protected]> Co-authored-by: kyuan-mongodb <[email protected]> Co-authored-by: rubenVB01 <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: maastha <[email protected]> Co-authored-by: Marco Suma <[email protected]> Co-authored-by: Espen Albert <[email protected]> Co-authored-by: Leo Antoli <[email protected]> Co-authored-by: Oriol <[email protected]> * doc: Adds documentation & examples for `mongodbatlas_encryption_at_rest` singular data source (#2543) * chore: Enables `mongodbatlas_encryption_at_rest` (Azure) tests to run in CI (#2551) * chore: Adds `mongodbatlas_encryption_at_rest_private_endpoint` acceptance test using azapi to approve private endpoint & check ACTIVE status (#2558) * doc: Add user journey considerations in current resource and example documentation (#2559) * minor typo fix * improve initial description in ear * adjust ear docs with mention of azure private link * private link doc adjustments * improve example * improve example * add mention in ear examples about policies * add note on update operation * link adjustments and add header for handling existing clusters * add note on private endpoint * add note in data sources * Update docs/resources/encryption_at_rest_private_endpoint.md Co-authored-by: maastha <[email protected]> * add clarification of preview flag for data sources --------- Co-authored-by: maastha <[email protected]> * update project_ip_addresses action * address doc comment --------- Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: Agustin Bettati <[email protected]> Co-authored-by: svc-apix-bot <[email protected]> Co-authored-by: lmkerbey-mdb <[email protected]> Co-authored-by: kanchana-mongodb <[email protected]> Co-authored-by: Zuhair Ahmed <[email protected]> Co-authored-by: kyuan-mongodb <[email protected]> Co-authored-by: rubenVB01 <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Marco Suma <[email protected]> Co-authored-by: Espen Albert <[email protected]> Co-authored-by: Leo Antoli <[email protected]> Co-authored-by: Oriol <[email protected]>

AgustinBettati added 8 commits September 5, 2024 11:31

minor typo fix

06659b1

improve initial description in ear

ee7577a

adjust ear docs with mention of azure private link

1a21548

private link doc adjustments

58995b4

improve example

00d0a24

improve example

4a5916d

add mention in ear examples about policies

fea1224

add note on update operation

b2aff91

AgustinBettati commented Sep 5, 2024

View reviewed changes

examples/mongodbatlas_encryption_at_rest_private_endpoint/azure/README.md Show resolved Hide resolved

AgustinBettati marked this pull request as ready for review September 5, 2024 12:58

AgustinBettati requested review from a team as code owners September 5, 2024 12:58

EspenAlbert reviewed Sep 5, 2024

View reviewed changes

EspenAlbert approved these changes Sep 5, 2024

View reviewed changes

davidhou17 approved these changes Sep 5, 2024

View reviewed changes

maastha reviewed Sep 5, 2024

View reviewed changes

AgustinBettati added 2 commits September 6, 2024 09:51

link adjustments and add header for handling existing clusters

f879a7c

add note on private endpoint

78daa0c

maastha reviewed Sep 6, 2024

View reviewed changes

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

maastha approved these changes Sep 6, 2024

View reviewed changes

maastha reviewed Sep 6, 2024

View reviewed changes

AgustinBettati and others added 3 commits September 6, 2024 17:21

add note in data sources

f776a8f

Update docs/resources/encryption_at_rest_private_endpoint.md

4e8526f

Co-authored-by: maastha <[email protected]>

add clarification of preview flag for data sources

6ff7c0f

AgustinBettati merged commit eab27cf into CLOUDP-246459-ear-kms-dev Sep 6, 2024
35 checks passed

AgustinBettati deleted the CLOUDP-267666 branch September 6, 2024 16:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: Add user journey considerations in current resource and example documentation #2559

doc: Add user journey considerations in current resource and example documentation #2559

AgustinBettati commented Sep 5, 2024

github-actions bot commented Sep 5, 2024

EspenAlbert Sep 5, 2024

EspenAlbert Sep 5, 2024

EspenAlbert left a comment

maastha Sep 5, 2024

AgustinBettati Sep 6, 2024

maastha Sep 6, 2024

AgustinBettati Sep 6, 2024

AgustinBettati Sep 6, 2024 •

edited

Loading

maastha left a comment

maastha Sep 6, 2024

AgustinBettati Sep 6, 2024

maastha Sep 6, 2024

AgustinBettati Sep 6, 2024

maastha commented Sep 6, 2024


		## Example Usages

		-> NOTE: Only Azure Key Vault with Azure Private Link is supported at this time.

doc: Add user journey considerations in current resource and example documentation #2559

doc: Add user journey considerations in current resource and example documentation #2559

Conversation

AgustinBettati commented Sep 5, 2024

Description

Type of change:

Required Checklist:

Further comments

github-actions bot commented Sep 5, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

EspenAlbert left a 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

AgustinBettati Sep 6, 2024 • edited Loading

Choose a reason for hiding this comment

maastha left a 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

maastha commented Sep 6, 2024

AgustinBettati Sep 6, 2024 •

edited

Loading