From 05e1f61fa155b481207fc3457c99709ab8095db9 Mon Sep 17 00:00:00 2001 From: andreaangiolillo Date: Tue, 8 Aug 2023 14:19:39 +0100 Subject: [PATCH 01/10] feat: add githooks --- .githooks/pre-commit | 31 +++++++++++++++++++++++++++++++ GNUmakefile | 6 ++++++ 2 files changed, 37 insertions(+) create mode 100644 .githooks/pre-commit diff --git a/.githooks/pre-commit b/.githooks/pre-commit new file mode 100644 index 0000000000..ad7e3102a3 --- /dev/null +++ b/.githooks/pre-commit @@ -0,0 +1,31 @@ +#!/usr/bin/env bash + +STAGED_GO_FILES=$(git diff --cached --name-only | grep ".go$" | grep -v "mock") + +for FILE in ${STAGED_GO_FILES} +do + gofmt -w -s "${FILE}" + goimports -w "${FILE}" + git add "${FILE}" +done + +if [[ -n "${STAGED_GO_FILES}" ]]; then + set -o errexit + make fix-lint + make lint + set +o errexit + for FILE in ${STAGED_GO_FILES} + do + git add "${FILE}" + done +fi + +STAGED_TF_FILES=$(git diff --cached --name-only | grep ".tf$") +if [ -n "$STAGED_TF_FILES" ]; then + make tflint +fi + +STAGED_WEBSITES_FILES=$(git diff --cached --name-only | grep "website/") +if [ -n "$STAGED_WEBSITES_FILES" ]; then + make make website-lint +fi \ No newline at end of file diff --git a/GNUmakefile b/GNUmakefile index 72fa1d99eb..3c89d7b9c7 100644 --- a/GNUmakefile +++ b/GNUmakefile @@ -124,3 +124,9 @@ tflint: fmtcheck .PHONY: tf-validate tf-validate: fmtcheck @scripts/tf-validate.sh + +.PHONY: link-git-hooks +link-git-hooks: ## Install git hooks + @echo "==> Installing all git hooks..." + find .git/hooks -type l -exec rm {} \; + find .githooks -type f -exec ln -sf ../../{} .git/hooks/ \; From 9e23665d767e94bf75808e8a8b90aea446acc349 Mon Sep 17 00:00:00 2001 From: andreaangiolillo Date: Tue, 8 Aug 2023 14:22:13 +0100 Subject: [PATCH 02/10] fixes --- .githooks/pre-commit | 0 1 file changed, 0 insertions(+), 0 deletions(-) mode change 100644 => 100755 .githooks/pre-commit diff --git a/.githooks/pre-commit b/.githooks/pre-commit old mode 100644 new mode 100755 From 1106456eef5554b52d70236ba504adfa7eb2cd7b Mon Sep 17 00:00:00 2001 From: andreaangiolillo Date: Tue, 8 Aug 2023 14:22:51 +0100 Subject: [PATCH 03/10] Update pre-commit --- .githooks/pre-commit | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.githooks/pre-commit b/.githooks/pre-commit index ad7e3102a3..7f1bc8a94d 100755 --- a/.githooks/pre-commit +++ b/.githooks/pre-commit @@ -11,7 +11,7 @@ done if [[ -n "${STAGED_GO_FILES}" ]]; then set -o errexit - make fix-lint + make lint-fix make lint set +o errexit for FILE in ${STAGED_GO_FILES} From 823b2a34696a95339d1fb8d570a3948429dc094a Mon Sep 17 00:00:00 2001 From: andreaangiolillo Date: Tue, 8 Aug 2023 14:29:25 +0100 Subject: [PATCH 04/10] Update pre-commit --- .githooks/pre-commit | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/.githooks/pre-commit b/.githooks/pre-commit index 7f1bc8a94d..4c2171253c 100755 --- a/.githooks/pre-commit +++ b/.githooks/pre-commit @@ -1,7 +1,8 @@ #!/usr/bin/env bash -STAGED_GO_FILES=$(git diff --cached --name-only | grep ".go$" | grep -v "mock") +STAGED_GO_FILES=$(git diff --cached --name-only | grep ".go$") +echo "Formatting go files" for FILE in ${STAGED_GO_FILES} do gofmt -w -s "${FILE}" @@ -22,10 +23,12 @@ fi STAGED_TF_FILES=$(git diff --cached --name-only | grep ".tf$") if [ -n "$STAGED_TF_FILES" ]; then + echo "Checking the format of Terraform files" make tflint fi STAGED_WEBSITES_FILES=$(git diff --cached --name-only | grep "website/") if [ -n "$STAGED_WEBSITES_FILES" ]; then - make make website-lint + echo "Checking the format of website files" + make website-lint fi \ No newline at end of file From 8c3ff07853907786f5ef51c82d34023433ac9d7f Mon Sep 17 00:00:00 2001 From: andreaangiolillo Date: Tue, 8 Aug 2023 15:07:59 +0100 Subject: [PATCH 05/10] Update pre-commit --- .githooks/pre-commit | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.githooks/pre-commit b/.githooks/pre-commit index 4c2171253c..44f4adf85a 100755 --- a/.githooks/pre-commit +++ b/.githooks/pre-commit @@ -31,4 +31,4 @@ STAGED_WEBSITES_FILES=$(git diff --cached --name-only | grep "website/") if [ -n "$STAGED_WEBSITES_FILES" ]; then echo "Checking the format of website files" make website-lint -fi \ No newline at end of file +fi From 2d6908a09f7ed1fd1167eb93a7bf42e5af2e635e Mon Sep 17 00:00:00 2001 From: andreaangiolillo Date: Tue, 8 Aug 2023 15:56:47 +0100 Subject: [PATCH 06/10] Adding Development Setup to CONTRIBUTING.md --- CONTRIBUTING.md | 252 +++++++++++++++++++++++++++++++++++++++++++ README.md | 281 ++---------------------------------------------- 2 files changed, 258 insertions(+), 275 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7abd9bfe0a..3d8f13ea82 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,3 +44,255 @@ Examples: ## Documentation Best Practises 1. In our documentation, when a resource field allows a maximum of only one item, we do not format that field as an array. Instead, we create a subsection specifically for this field. Within this new subsection, we enumerate all the attributes of the field. Let's illustrate this with an example: [cloud_backup_schedule.html.markdown](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/master/website/docs/r/cloud_backup_schedule.html.markdown?plain=1#L207) + +## Development Setup +### Prerequisite Tools + +- [Git](https://git-scm.com/) +- [Go (at least Go 1.20)](https://golang.org/dl/) + +### Environment + +- Fork the repository. +- Clone your forked repository locally. +- We use Go Modules to manage dependencies, so you can develop outside your `$GOPATH`. +- We use [golangci-lint](https://github.com/golangci/golangci-lint) to lint our code, you can install it locally via `make setup`. + + +### Building +- Enter the provider directory +- Run `make tools` to install the needed tools for the provider +- Run `link-git-hooks` to install githooks +- Run `make build` to build the binary in the `./bin` directory: +- Use the local provider binary in the `./bin` folder: + - Create the following `dev.trfc` file inside your directory + ```terraform + provider_installation { + + dev_overrides { + "mongodb/mongodbatlas" = "/Users/yourUser/terraform-provider-mongodbatlas/bin" # path to the provider binary + } + + direct {} + } + ``` + - Define the env var `TF_CLI_CONFIG_FILE` in your console session + ```bash + export TF_CLI_CONFIG_FILE=PATH/TO/dev.trfc + ``` +- Run `terraform init` to inizialize terraform +- Run `terraform apply` to use terraform with the local binary + +For more explained information about plugin override check [Development Overrides for Provider Developers](https://www.terraform.io/docs/cli/config/config-file.html#development-overrides-for-provider-developers) + +### Testing the Provider + +In order to test the provider, you can run `make test`. You can use [meta-arguments](https://www.terraform.io/docs/configuration/providers.html) such as `alias` and `version`. The following arguments are supported in the MongoDB Atlas `provider` block: + +* `public_key` - (Optional) This is the MongoDB Atlas API public_key. It must be + provided, but it can also be sourced from the `MONGODB_ATLAS_PUBLIC_KEY` + environment variable. + +* `private_key` - (Optional) This is the MongoDB Atlas private_key. It must be + provided, but it can also be sourced from the `MONGODB_ATLAS_PRIVATE_KEY` + environment variable. + +~> **Notice:** If you do not have a `public_key` and `private_key` you must create a programmatic API key to configure the provider (see [Creating Programmatic API key](#Programmatic-API-key)). If you already have one, you can continue with [Configuring environment variables](#Configuring-environment-variables) + +### Running the acceptance test + +#### Programmatic API key + +It's necessary to generate and configure an API key for your organization for the acceptance test to succeed. To grant programmatic access to an organization or project using only the [API](https://docs.atlas.mongodb.com/api/) you need to know: + + 1. The programmatic API key has two parts: a Public Key and a Private Key. To see more details on how to create a programmatic API key visit https://docs.atlas.mongodb.com/configure-api-access/#programmatic-api-keys. + + 1. The programmatic API key must be granted roles sufficient for the acceptance test to succeed. The Organization Owner and Project Owner roles should be sufficient. You can see the available roles at https://docs.atlas.mongodb.com/reference/user-roles. + + 1. You must [configure Atlas API Access](https://docs.atlas.mongodb.com/configure-api-access/) for your programmatic API key. You should allow API access for the IP address from which the acceptance test runs. + +#### Configuring environment variables + +You must also configure the following environment variables before running the test: + +##### MongoDB Atlas env variables +```bash +export MONGODB_ATLAS_PROJECT_ID= +export MONGODB_ATLAS_ORG_ID= +export MONGODB_ATLAS_PUBLIC_KEY= +export MONGODB_ATLAS_PRIVATE_KEY= + +# This env variable is optional and allow you to run terraform with a custom server +export MONGODB_ATLAS_BASE_URL= +``` + +- For `Authentication database user` resource configuration: + ```bash + $ export MONGODB_ATLAS_DB_USERNAME= + ``` + +- For `Project(s)` resource configuration: + ```bash + $ export MONGODB_ATLAS_TEAMS_IDS= + $ export MONGODB_ATLAS_API_KEYS_IDS= + ``` +~> **Notice:** It should be at least one team id up to 3 teams ids depending of acceptance testing using separator comma like this `teamId1,teamdId2,teamId3`. + +- For skip acceptances testing that requires additional credentials such as AWS, AZURE and GCP: + ```bash + export SKIP_TEST_EXTERNAL_CREDENTIALS=TRUE + ``` + +- For `Federated Settings` resource configuration: + ```bash + $ export MONGODB_ATLAS_FEDERATION_SETTINGS_ID= + $ export ONGODB_ATLAS_FEDERATED_ORG_ID= + $ export MONGODB_ATLAS_FEDERATED_PROJECT_ID= + $ export MONGODB_ATLAS_FEDERATED_GROUP_ID= + $ export MONGODB_ATLAS_FEDERATED_ROLE_MAPPING_ID= + $ export MONGODB_ATLAS_FEDERATED_OKTA_IDP_ID= + $ export MONGODB_ATLAS_FEDERATED_SSO_URL= + $ export MONGODB_ATLAS_FEDERATED_ISSUER_URI= + ``` +~> **Notice:** For more information about the Federation configuration resource, see: https://www.mongodb.com/docs/atlas/reference/api/federation-configuration/ + +##### AWS env variables + +- For `Network Peering` resource configuration: + ```bash + $ export AWS_ACCOUNT_ID= + $ export AWS_VPC_ID= + $ export AWS_VPC_CIDR_BLOCK= + $ export AWS_REGION= + $ export AWS_SUBNET_ID= + $ export AWS_SECURITY_GROUP_ID= + ``` +~> **Notice:** For more information about the Network Peering resource, see: https://docs.atlas.mongodb.com/reference/api/vpc/ + +- For `Encryption at Rest` resource configuration: + ```bash + $ export AWS_ACCESS_KEY_ID= + $ export AWS_SECRET_ACCESS_KEY= + $ export AWS_CUSTOMER_MASTER_KEY_ID= + $ export AWS_REGION= + + $ export AWS_ACCESS_KEY_ID_UPDATED= + $ export AWS_SECRET_ACCESS_KEY_UPDATED= + $ export AWS_CUSTOMER_MASTER_KEY_ID_UPDATED= + $ export AWS_REGION_UPDATED= + ``` +~> **Notice:** For more information about the Encryption at Rest resource, see: https://docs.atlas.mongodb.com/reference/api/encryption-at-rest/ + +- For `Private Endpoint Link` resource configuration: + ```bash + $ export AWS_ACCESS_KEY_ID= + $ export AWS_SECRET_ACCESS_KEY= + $ export AWS_CUSTOMER_MASTER_KEY_ID= + $ export AWS_REGION= + $ export AWS_VPC_ID= + $ export AWS_SUBNET_ID= + $ export AWS_SECURITY_GROUP_ID= + ``` +~> **Notice:** For more information about the PrivateLink (for AWS only), see: https://docs.atlas.mongodb.com/reference/api/encryption-at-rest/https://docs.atlas.mongodb.com/reference/api/private-endpoint/ + +##### AZURE env variables + +- For `Network Peering` resource configuration: + ```bash + $ export AZURE_DIRECTORY_ID= + $ export AZURE_SUBSCRIPTION_ID= + $ export AZURE_RESOURCE_GROUP_NAME= + $ export AZURE_VNET_NAME= + ``` +~> **Notice:** For more information about the Network Peering resource, see: https://docs.atlas.mongodb.com/reference/api/vpc/ + + +- For Encryption at Rest resource configuration: + ```bash + export AZURE_CLIENT_ID= + export AZURE_SUBSCRIPTION_ID= + export AZURE_RESOURCE_GROUP_NAME= + export AZURE_SECRET= + export AZURE_KEY_VAULT_NAME= + export AZURE_KEY_IDENTIFIER= + export AZURE_TENANT_ID= + export AZURE_DIRECTORY_ID= + + export AZURE_CLIENT_ID_UPDATED= + export AZURE_RESOURCE_GROUP_NAME_UPDATED= + export AZURE_SECRET_UPDATED= + export AZURE_KEY_VAULT_NAME_UPDATED= + export AZURE_KEY_IDENTIFIER_UPDATED= + ``` +~> **Notice:** For more information about the Encryption at Rest resource, see: https://docs.atlas.mongodb.com/reference/api/encryption-at-rest/ + +##### GCP env variables +- For `Network Peering` resource configuration: + ```bash + $export GCP_PROJECT_ID= + ``` +~> **Notice:** For more information about the Network Peering resource, see: https://docs.atlas.mongodb.com/reference/api/vpc/ + + +- For Encryption at Rest resource configuration: + ```bash + $ export GCP_SERVICE_ACCOUNT_KEY= + $ export GCP_KEY_VERSION_RESOURCE_ID= + ``` +~> **Notice:** For more information about the Encryption at Rest resource, see: https://docs.atlas.mongodb.com/reference/api/encryption-at-rest/ + + +#### Run Acceptance tests +**Notice:** Acceptance tests create real resources, and often cost money to run. Please note in any PRs made if you are unable to pay to run acceptance tests for your contribution. We will accept "best effort" implementations of acceptance tests in this case and run them for you on our side. This may delay the contribution but we do not want your contribution blocked by funding. +- Run `make testacc` + + + +### Testing Atlas Provider Versions that are NOT hosted on Terraform Registry (i.e. pre-release versions) +To test development / pre-release versions of the Terraform Atlas Provider that are not hosted on the Terraform Registry, you will need to create a [Terraform Provider Network Mirror](https://developer.hashicorp.com/terraform/internals/provider-network-mirror-protocol). + +The provider network mirror protocol is an optional protocol which you can implement to provide an alternative installation source for Terraform providers, regardless of their origin registries. Terraform uses network mirrors only if you activate them explicitly in the CLI configuration's `provider_installation` block. When enabled, a network mirror can serve providers belonging to any registry hostname, which can allow an organization to serve all of the Terraform providers they intend to use from an internal server, rather than from each provider's origin registry. + +To do this you can: +- Create a versions.tf file in a new directory with an existing live version from Terraform Registry. For example this can include: + ```terraform + terraform { + required_providers { + mongodbatlas = { + source = "mongodb/mongodbatlas" + } + } + required_version = ">= 0.13" + } + ``` + +- Use `terraform init` to create required file structures + +- `mkdir` a `tf_cache` sub-directory and `cd` into that directory + +- Create a .terraformrc file and insert below (modify accordingly to your own local path directory): + ```terraform + provider_installation { + filesystem_mirror { + path = "C:\Users\ZuhairAhmed\Desktop\Tenant_Upgrade\tf_cache" + include = ["registry.terraform.io/hashicorp/*"] + } + direct { + exclude = ["registry.terraform.io/hashicorp/*"] + } + } + plugin_cache_dir = "C:\Users\ZuhairAhmed\Desktop\Tenant_Upgrade\tf_cache" + disable_checkpoint=true + ``` +- `cd` back up to original directory and `mv` the `.terraform/providers/registry.terraform.io` directory to `tf_cache` + +- Create required environment variables (modify accordingly to your own local path directory): + ```bash + export TF_PLUGIN_CACHE_DIR=/mnt/c/Users/ZuhairAhmed/Desktop/Tenant_Upgrade/tf_cache + export TF_CLI_CONFIG_FILE=/mnt/c/Users/ZuhairAhmed/Desktop/Tenant_Upgrade/tf_cache/terraform.rc + ``` +- Delete the `.terraform` and `.terraform.lock.hcl` directories altogether. At this point you should only have the `tf_cache` directory and the `versions.tf` config file remaining. + +- Next in the `tf_cache` directory replace existing terraform provider core files (Terraform Atlas Provider version binary, `CHANGELOG.md`, `LICENSE`, and `README.md`) with the version you seek to test locally. Make sure to keep folder structure the same. + +- Lastly, in the terminal run `terraform init` again and this time terraform will pull provider version from `tf_cache` network mirror. You can confirm this by noting the `Terraform has been successfully initialized! Using mongodb/mongodbatlas Vx.x.x from the shared cache directory` message. diff --git a/README.md b/README.md index 62be64d71d..897515dd59 100644 --- a/README.md +++ b/README.md @@ -33,283 +33,11 @@ In order to use and/or test beta resources and datasources in this provider you' ```bash export MONGODB_ATLAS_ENABLE_BETA = true ``` - -## Developing the Provider - -If you wish to work on the provider, you'll first need [Go](https://golang.org/doc/install) installed on your machine (please check the [requirements](#Requirements) before proceeding). - -Note: This project uses [Go Modules](https://blog.golang.org/using-go-modules) making it safe to work with it outside of your existing [GOPATH](https://golang.org/doc/code.html#GOPATH). The instructions that follow assume a directory in your home directory outside of the standard GOPATH (i.e $HOME/development/terraform-providers/). - -Clone repository to: `$HOME/development/terraform-providers/` - -```bash -mkdir -p $HOME/development/terraform-providers/; cd $HOME/development/terraform-providers/ -git clone git@github.com:mongodb/terraform-provider-mongodbatlas -... -``` - -Enter the provider directory and run `make tools`. This will install the needed tools for the provider. - -```bash -make tools -``` - -To compile the provider, run `make build`. This will build the provider and put its binary in the ./bin directory. - -```bash -make build -... -# ./bin/terraform-provider-mongodbatlas -... -``` - -### Using development provider in Terraform 0.14+ -From terraform version 0.14, we can override provider use for development purposes. - -Just create a `.trfc` file to hold the configuration to override terraform local configuration - -```terraform -provider_installation { - - dev_overrides { - "mongodb/mongodbatlas" = "[PATH THAT CONTAINS CUSTOM PLUGIN]" - } - - direct {} -} -``` - -and set the env var `TF_CLI_CONFIG_FILE` like this: -`export TF_CLI_CONFIG_FILE=PATH/TO/dev.trfc` - -For more explained information about "plugin override" check [Development Overrides for Provider Developers](https://www.terraform.io/docs/cli/config/config-file.html#development-overrides-for-provider-developers) - -### Testing the Provider - -In order to test the provider, you can run `make test`. You can use [meta-arguments](https://www.terraform.io/docs/configuration/providers.html) such as `alias` and `version`. The following arguments are supported in the MongoDB Atlas `provider` block: - -* `public_key` - (Optional) This is the MongoDB Atlas API public_key. It must be - provided, but it can also be sourced from the `MONGODB_ATLAS_PUBLIC_KEY` - environment variable. - -* `private_key` - (Optional) This is the MongoDB Atlas private_key. It must be - provided, but it can also be sourced from the `MONGODB_ATLAS_PRIVATE_KEY` - environment variable. - -~> **Notice:** If you do not have a `public_key` and `private_key` you must create a programmatic API key to configure the provider (see [Creating Programmatic API key](#Programmatic-API-key)). If you already have one, you can continue with [Configuring environment variables](#Configuring-environment-variables) - -#### Testing Atlas Provider Versions that are NOT hosted on Terraform Registry (i.e. pre-release versions) -To test development / pre-release versions of the Terraform Atlas Provider that are not hosted on the Terraform Registry, you will need to create a [Terraform Provider Network Mirror](https://developer.hashicorp.com/terraform/internals/provider-network-mirror-protocol). - -The provider network mirror protocol is an optional protocol which you can implement to provide an alternative installation source for Terraform providers, regardless of their origin registries. Terraform uses network mirrors only if you activate them explicitly in the CLI configuration's `provider_installation` block. When enabled, a network mirror can serve providers belonging to any registry hostname, which can allow an organization to serve all of the Terraform providers they intend to use from an internal server, rather than from each provider's origin registry. - -To do this you can: -1. Create a versions.tf file in a new directory with an existing live version from Terraform Registry. For example this can include: -``` -terraform { - required_providers { - mongodbatlas = { - source = "mongodb/mongodbatlas" - } - } - required_version = ">= 0.13" -} -``` - -2. Use `terraform init` to create required file structures - -3. `mkdir` a “tf_cache” sub-directory and `cd` into that directory - -4. Create a .terraformrc file and insert below (modify accordingly to your own local path directory): -``` -provider_installation { - filesystem_mirror { - path = "C:\Users\ZuhairAhmed\Desktop\Tenant_Upgrade\tf_cache" - include = ["registry.terraform.io/hashicorp/*"] - } - direct { - exclude = ["registry.terraform.io/hashicorp/*"] - } -} -plugin_cache_dir = "C:\Users\ZuhairAhmed\Desktop\Tenant_Upgrade\tf_cache" -disable_checkpoint=true -``` -5. `cd` back up to original directory and `mv` the “.terraform/providers/registry.terraform.io” directory to “tf_cache” - -6. Create required environment variables (modify accordingly to your own local path directory): -``` -export TF_PLUGIN_CACHE_DIR=/mnt/c/Users/ZuhairAhmed/Desktop/Tenant_Upgrade/tf_cache -export TF_CLI_CONFIG_FILE=/mnt/c/Users/ZuhairAhmed/Desktop/Tenant_Upgrade/tf_cache/terraform.rc -``` -7. Delete the .terraform and .terraform.lock.hcl directories altogether. At this point you should only have the “tf_cache” directory and the “versions.tf” config file remaining. - -9. Next in the “tf_cache” directory replace existing terraform provider core files (Terraform Atlas Provider version binary, CHANGELOG.md, LICENSE, and README.md) with the version you seek to test locally. Make sure to keep folder structure the same. - -8. Lastly, in the terminal run `terraform init` again and this time terraform will pull provider version from tf_cache network mirror. You can confirm this by noting the “Terraform has been successfully initialized! Using mongodb/mongodbatlas Vx.x.x from the shared cache directory” message. - -#### Logs -To help with dubbing issues, you can turn on Logs with `export TF_LOG=TRACE`. Note: this is very noisy. +### Logs +To help with issues, you can turn on Logs with `export TF_LOG=TRACE`. Note: this is very noisy. To export logs to file, you can use `export TF_LOG_PATH=terraform.log` -### Running the acceptance test - -#### Programmatic API key - -It's necessary to generate and configure an API key for your organization for the acceptance test to succeed. To grant programmatic access to an organization or project using only the [API](https://docs.atlas.mongodb.com/api/) you need to know: - - 1. The programmatic API key has two parts: a Public Key and a Private Key. To see more details on how to create a programmatic API key visit https://docs.atlas.mongodb.com/configure-api-access/#programmatic-api-keys. - - 1. The programmatic API key must be granted roles sufficient for the acceptance test to succeed. The Organization Owner and Project Owner roles should be sufficient. You can see the available roles at https://docs.atlas.mongodb.com/reference/user-roles. - - 1. You must [configure Atlas API Access](https://docs.atlas.mongodb.com/configure-api-access/) for your programmatic API key. You should allow API access for the IP address from which the acceptance test runs. - -#### Configuring environment variables - -You must also configure the following environment variables before running the test: - -##### MongoDB Atlas env variables -```sh -export MONGODB_ATLAS_PROJECT_ID= -export MONGODB_ATLAS_ORG_ID= -export MONGODB_ATLAS_PUBLIC_KEY= -export MONGODB_ATLAS_PRIVATE_KEY= - -# This env variable is optional and allow you to run terraform with a custom server -export MONGODB_ATLAS_BASE_URL= -``` - -- For `Authentication database user` resource configuration: -```sh -$ export MONGODB_ATLAS_DB_USERNAME= -``` - -- For `Project(s)` resource configuration: -```sh -$ export MONGODB_ATLAS_TEAMS_IDS= -$ export MONGODB_ATLAS_API_KEYS_IDS= -``` -~> **Notice:** It should be at least one team id up to 3 teams ids depending of acceptance testing using separator comma like this `teamId1,teamdId2,teamId3`. - -- For skip acceptances testing that requires additional credentials such as AWS, AZURE and GCP: -```sh -export SKIP_TEST_EXTERNAL_CREDENTIALS=TRUE -``` - -- For `Federated Settings` resource configuration: -```sh -$ export MONGODB_ATLAS_FEDERATION_SETTINGS_ID= -$ export ONGODB_ATLAS_FEDERATED_ORG_ID= -$ export MONGODB_ATLAS_FEDERATED_PROJECT_ID= -$ export MONGODB_ATLAS_FEDERATED_GROUP_ID= -$ export MONGODB_ATLAS_FEDERATED_ROLE_MAPPING_ID= -$ export MONGODB_ATLAS_FEDERATED_OKTA_IDP_ID= -$ export MONGODB_ATLAS_FEDERATED_SSO_URL= -$ export MONGODB_ATLAS_FEDERATED_ISSUER_URI= -``` -~> **Notice:** For more information about the Federation configuration resource, see: https://www.mongodb.com/docs/atlas/reference/api/federation-configuration/ - -##### AWS env variables - -- For `Network Peering` resource configuration: -```sh -$ export AWS_ACCOUNT_ID= -$ export AWS_VPC_ID= -$ export AWS_VPC_CIDR_BLOCK= -$ export AWS_REGION= -$ export AWS_SUBNET_ID= -$ export AWS_SECURITY_GROUP_ID= -``` -~> **Notice:** For more information about the Network Peering resource, see: https://docs.atlas.mongodb.com/reference/api/vpc/ - -- For `Encryption at Rest` resource configuration: -```sh -$ export AWS_ACCESS_KEY_ID= -$ export AWS_SECRET_ACCESS_KEY= -$ export AWS_CUSTOMER_MASTER_KEY_ID= -$ export AWS_REGION= - -$ export AWS_ACCESS_KEY_ID_UPDATED= -$ export AWS_SECRET_ACCESS_KEY_UPDATED= -$ export AWS_CUSTOMER_MASTER_KEY_ID_UPDATED= -$ export AWS_REGION_UPDATED= -``` -~> **Notice:** For more information about the Encryption at Rest resource, see: https://docs.atlas.mongodb.com/reference/api/encryption-at-rest/ - -- For `Private Endpoint Link` resource configuration: -```sh -$ export AWS_ACCESS_KEY_ID= -$ export AWS_SECRET_ACCESS_KEY= -$ export AWS_CUSTOMER_MASTER_KEY_ID= -$ export AWS_REGION= -$ export AWS_VPC_ID= -$ export AWS_SUBNET_ID= -$ export AWS_SECURITY_GROUP_ID= -``` -~> **Notice:** For more information about the PrivateLink (for AWS only), see: https://docs.atlas.mongodb.com/reference/api/encryption-at-rest/https://docs.atlas.mongodb.com/reference/api/private-endpoint/ - -##### AZURE env variables - -- For `Network Peering` resource configuration: -```sh -$ export AZURE_DIRECTORY_ID= -$ export AZURE_SUBSCRIPTION_ID= -$ export AZURE_RESOURCE_GROUP_NAME= -$ export AZURE_VNET_NAME= -``` -~> **Notice:** For more information about the Network Peering resource, see: https://docs.atlas.mongodb.com/reference/api/vpc/ - - -- For Encryption at Rest resource configuration: -```sh -export AZURE_CLIENT_ID= -export AZURE_SUBSCRIPTION_ID= -export AZURE_RESOURCE_GROUP_NAME= -export AZURE_SECRET= -export AZURE_KEY_VAULT_NAME= -export AZURE_KEY_IDENTIFIER= -export AZURE_TENANT_ID= -export AZURE_DIRECTORY_ID= - -export AZURE_CLIENT_ID_UPDATED= -export AZURE_RESOURCE_GROUP_NAME_UPDATED= -export AZURE_SECRET_UPDATED= -export AZURE_KEY_VAULT_NAME_UPDATED= -export AZURE_KEY_IDENTIFIER_UPDATED= -``` -~> **Notice:** For more information about the Encryption at Rest resource, see: https://docs.atlas.mongodb.com/reference/api/encryption-at-rest/ - -##### GCP env variables -- For `Network Peering` resource configuration: -```sh -$export GCP_PROJECT_ID= -``` -~> **Notice:** For more information about the Network Peering resource, see: https://docs.atlas.mongodb.com/reference/api/vpc/ - - -- For Encryption at Rest resource configuration: -```sh -$ export GCP_SERVICE_ACCOUNT_KEY= -$ export GCP_KEY_VERSION_RESOURCE_ID= -``` -~> **Notice:** For more information about the Encryption at Rest resource, see: https://docs.atlas.mongodb.com/reference/api/encryption-at-rest/ - - -In order to run the full suite of Acceptance tests, run ``make testacc``. - -~> **Notice:** Acceptance tests create real resources, and often cost money to run. Please note in any PRs made if you are unable to pay to run acceptance tests for your contribution. We will accept "best effort" implementations of acceptance tests in this case and run them for you on our side. This may delay the contribution but we do not want your contribution blocked by funding. - -``` -$ make testacc -``` -### Running the integration tests - -The integration tests helps the validation for resources interacting with third party providers (AWS, Azure or Google Cloud) using terratest [environment setup details](integrationtesting/README.md) - -``` - cd integrationtesting - go test -tags=integration -``` ## 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: @@ -328,7 +56,10 @@ We ship binaries but do not prioritize fixes for the following operating system ## Troubleshooting -See [Troubleshooting](website/docs/troubleshooting.html.markdown) +See [Troubleshooting](website/docs/troubleshooting.html.markdown). + +## Developing the Provider +See [CONTRIBUTIg.md](./CONTRIBUTING.md). ### Autoclose stale issues and PRs From e1dc71c3c824ab2b21e20437399bb8c7bdf60dfa Mon Sep 17 00:00:00 2001 From: andreaangiolillo Date: Tue, 8 Aug 2023 16:10:32 +0100 Subject: [PATCH 07/10] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 897515dd59..ebd9398012 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,7 @@ We ship binaries but do not prioritize fixes for the following operating system See [Troubleshooting](website/docs/troubleshooting.html.markdown). ## Developing the Provider -See [CONTRIBUTIg.md](./CONTRIBUTING.md). +See [CONTRIBUTING.md](./CONTRIBUTING.md). ### Autoclose stale issues and PRs From cec1d8922b47ef90b4d15c7efb4280b32d833644 Mon Sep 17 00:00:00 2001 From: andreaangiolillo Date: Tue, 8 Aug 2023 16:21:43 +0100 Subject: [PATCH 08/10] Update CONTRIBUTING.md --- CONTRIBUTING.md | 106 ++++++++++++++++++++++-------------------------- 1 file changed, 48 insertions(+), 58 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3d8f13ea82..2fa48faa1d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,49 +1,5 @@ -Contributing ---------------------------- - # Contributing -## Workflow - -MongoDB welcomes community contributions! If you’re interested in making a contribution to Terraform MongoDB Atlas provider, please follow the steps below before you start writing any code: - -1. Sign the [contributor's agreement](http://www.mongodb.com/contributor). This will allow us to review and accept contributions. -1. Read the [Terraform contribution guidelines](https://www.terraform.io/docs/extend/community/contributing.html) and the [README](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/master/README.md) in this repo -1. Reach out by filing an [issue](https://github.com/mongodb/terraform-provider-mongodbatlas/issues) to discuss your proposed contribution, be it a bug fix or feature/other improvements. - -After the above 3 steps are completed and we've agreed on a path forward: -1. Fork the repository on GitHub -1. Create a branch with a name that briefly describes your submission -1. Implement your feature, improvement or bug fix, ensuring it adheres to the [Terraform Plugin Best Practices](https://www.terraform.io/docs/extend/best-practices/index.html) -1. Ensure you follow the [Terraform Plugin Testing requirements](https://www.terraform.io/docs/extend/testing/index.html). -1. Add comments around your new code that explain what's happening -1. Commit and push your changes to your branch then submit a pull request against the current release branch, not master. The naming scheme of the branch is `release-staging-v#.#.#`. Note: There will only be one release branch at a time. -1. A repo maintainer will review the your pull request, and may either request additional changes or merge the pull request. - -## PR Title Format -We use [*Conventional Commits*](https://www.conventionalcommits.org/): -- `fix: description of the PR`: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning). -- `chore: description of the PR`: the commit includes a technical or preventative maintenance task that is necessary for managing the product or the repository, but it is not tied to any specific feature or user story (this correlates with PATCH in Semantic Versioning). -- `doc: description of the PR`: The commit adds, updates, or revises documentation that is stored in the repository (this correlates with PATCH in Semantic Versioning). -- `test: description of the PR`: The commit enhances, adds to, revised, or otherwise changes the suite of automated tests for the product (this correlates with PATCH in Semantic Versioning). -- `security: description of the PR`: The commit improves the security of the product or resolves a security issue that has been reported (this correlates with PATCH in Semantic Versioning). -- `refactor: description of the PR`: The commit refactors existing code in the product, but does not alter or change existing behavior in the product (this correlates with Minor in Semantic Versioning). -- `perf: description of the PR`: The commit improves the performance of algorithms or general execution time of the product, but does not fundamentally change an existing feature (this correlates with Minor in Semantic Versioning). -- `ci: description of the PR`: The commit makes changes to continuous integration or continuous delivery scripts or configuration files (this correlates with Minor in Semantic Versioning). -- `revert: description of the PR`: The commit reverts one or more commits that were previously included in the product, but were accidentally merged or serious issues were discovered that required their removal from the main branch (this correlates with Minor in Semantic Versioning). -- `style: description of the PR`: The commit updates or reformats the style of the source code, but does not otherwise change the product implementation (this correlates with Minor in Semantic Versioning). -- `feat: description of the PR`: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning). -- `deprecate: description of the PR`: The commit deprecates existing functionality, but does not remove it from the product (this correlates with MINOR in Semantic Versioning). -- `BREAKING CHANGE`: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type. -Examples: - - `fix!: description of the ticket` - - If the PR has `BREAKING CHANGE`: in its description is a breaking change -- `remove!: description of the PR`: The commit removes a feature from the product. Typically features are deprecated first for a period of time before being removed. Removing a feature is a breaking change (correlating with MAJOR in Semantic Versioning). - - -## Documentation Best Practises - -1. In our documentation, when a resource field allows a maximum of only one item, we do not format that field as an array. Instead, we create a subsection specifically for this field. Within this new subsection, we enumerate all the attributes of the field. Let's illustrate this with an example: [cloud_backup_schedule.html.markdown](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/master/website/docs/r/cloud_backup_schedule.html.markdown?plain=1#L207) ## Development Setup ### Prerequisite Tools @@ -57,8 +13,6 @@ Examples: - Clone your forked repository locally. - We use Go Modules to manage dependencies, so you can develop outside your `$GOPATH`. - We use [golangci-lint](https://github.com/golangci/golangci-lint) to lint our code, you can install it locally via `make setup`. - - ### Building - Enter the provider directory - Run `make tools` to install the needed tools for the provider @@ -85,6 +39,14 @@ Examples: For more explained information about plugin override check [Development Overrides for Provider Developers](https://www.terraform.io/docs/cli/config/config-file.html#development-overrides-for-provider-developers) +### Open a Pull Request +- Sign the [contributor's agreement](http://www.mongodb.com/contributor). This will allow us to review and accept contributions. +- Implement your feature, improvement or bug fix, ensuring it adheres to the [Terraform Plugin Best Practices](https://www.terraform.io/docs/extend/best-practices/index.html). +- Make sure that the PR title follows [*Conventional Commits*](https://www.conventionalcommits.org/). +- Add comments around your new code that explain what's happening. +- Commit and push your changes to your branch then submit a pull request against the `master` branch. +- A repo maintainer will review the your pull request, and may either request additional changes or merge the pull request. + ### Testing the Provider In order to test the provider, you can run `make test`. You can use [meta-arguments](https://www.terraform.io/docs/configuration/providers.html) such as `alias` and `version`. The following arguments are supported in the MongoDB Atlas `provider` block: @@ -105,26 +67,27 @@ In order to test the provider, you can run `make test`. You can use [meta-argume It's necessary to generate and configure an API key for your organization for the acceptance test to succeed. To grant programmatic access to an organization or project using only the [API](https://docs.atlas.mongodb.com/api/) you need to know: - 1. The programmatic API key has two parts: a Public Key and a Private Key. To see more details on how to create a programmatic API key visit https://docs.atlas.mongodb.com/configure-api-access/#programmatic-api-keys. + - The programmatic API key has two parts: a Public Key and a Private Key. To see more details on how to create a programmatic API key visit https://docs.atlas.mongodb.com/configure-api-access/#programmatic-api-keys. - 1. The programmatic API key must be granted roles sufficient for the acceptance test to succeed. The Organization Owner and Project Owner roles should be sufficient. You can see the available roles at https://docs.atlas.mongodb.com/reference/user-roles. + - The programmatic API key must be granted roles sufficient for the acceptance test to succeed. The Organization Owner and Project Owner roles should be sufficient. You can see the available roles at https://docs.atlas.mongodb.com/reference/user-roles. - 1. You must [configure Atlas API Access](https://docs.atlas.mongodb.com/configure-api-access/) for your programmatic API key. You should allow API access for the IP address from which the acceptance test runs. + - You must [configure Atlas API Access](https://docs.atlas.mongodb.com/configure-api-access/) for your programmatic API key. You should allow API access for the IP address from which the acceptance test runs. #### Configuring environment variables You must also configure the following environment variables before running the test: ##### MongoDB Atlas env variables -```bash -export MONGODB_ATLAS_PROJECT_ID= -export MONGODB_ATLAS_ORG_ID= -export MONGODB_ATLAS_PUBLIC_KEY= -export MONGODB_ATLAS_PRIVATE_KEY= +- Required env variables: + ```bash + export MONGODB_ATLAS_PROJECT_ID= + export MONGODB_ATLAS_ORG_ID= + export MONGODB_ATLAS_PUBLIC_KEY= + export MONGODB_ATLAS_PRIVATE_KEY= -# This env variable is optional and allow you to run terraform with a custom server -export MONGODB_ATLAS_BASE_URL= -``` + # This env variable is optional and allow you to run terraform with a custom server + export MONGODB_ATLAS_BASE_URL= + ``` - For `Authentication database user` resource configuration: ```bash @@ -243,7 +206,7 @@ export MONGODB_ATLAS_BASE_URL= #### Run Acceptance tests -**Notice:** Acceptance tests create real resources, and often cost money to run. Please note in any PRs made if you are unable to pay to run acceptance tests for your contribution. We will accept "best effort" implementations of acceptance tests in this case and run them for you on our side. This may delay the contribution but we do not want your contribution blocked by funding. +~> **Notice:** Acceptance tests create real resources, and often cost money to run. Please note in any PRs made if you are unable to pay to run acceptance tests for your contribution. We will accept "best effort" implementations of acceptance tests in this case and run them for you on our side. This may delay the contribution but we do not want your contribution blocked by funding. - Run `make testacc` @@ -296,3 +259,30 @@ To do this you can: - Next in the `tf_cache` directory replace existing terraform provider core files (Terraform Atlas Provider version binary, `CHANGELOG.md`, `LICENSE`, and `README.md`) with the version you seek to test locally. Make sure to keep folder structure the same. - Lastly, in the terminal run `terraform init` again and this time terraform will pull provider version from `tf_cache` network mirror. You can confirm this by noting the `Terraform has been successfully initialized! Using mongodb/mongodbatlas Vx.x.x from the shared cache directory` message. + + + +## Documentation Best Practises + +- In our documentation, when a resource field allows a maximum of only one item, we do not format that field as an array. Instead, we create a subsection specifically for this field. Within this new subsection, we enumerate all the attributes of the field. Let's illustrate this with an example: [cloud_backup_schedule.html.markdown](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/master/website/docs/r/cloud_backup_schedule.html.markdown?plain=1#L207) + + +## PR Title Format +We use [*Conventional Commits*](https://www.conventionalcommits.org/): +- `fix: description of the PR`: a commit of the type fix patches a bug in your codebase (this correlates with PATCH in Semantic Versioning). +- `chore: description of the PR`: the commit includes a technical or preventative maintenance task that is necessary for managing the product or the repository, but it is not tied to any specific feature or user story (this correlates with PATCH in Semantic Versioning). +- `doc: description of the PR`: The commit adds, updates, or revises documentation that is stored in the repository (this correlates with PATCH in Semantic Versioning). +- `test: description of the PR`: The commit enhances, adds to, revised, or otherwise changes the suite of automated tests for the product (this correlates with PATCH in Semantic Versioning). +- `security: description of the PR`: The commit improves the security of the product or resolves a security issue that has been reported (this correlates with PATCH in Semantic Versioning). +- `refactor: description of the PR`: The commit refactors existing code in the product, but does not alter or change existing behavior in the product (this correlates with Minor in Semantic Versioning). +- `perf: description of the PR`: The commit improves the performance of algorithms or general execution time of the product, but does not fundamentally change an existing feature (this correlates with Minor in Semantic Versioning). +- `ci: description of the PR`: The commit makes changes to continuous integration or continuous delivery scripts or configuration files (this correlates with Minor in Semantic Versioning). +- `revert: description of the PR`: The commit reverts one or more commits that were previously included in the product, but were accidentally merged or serious issues were discovered that required their removal from the main branch (this correlates with Minor in Semantic Versioning). +- `style: description of the PR`: The commit updates or reformats the style of the source code, but does not otherwise change the product implementation (this correlates with Minor in Semantic Versioning). +- `feat: description of the PR`: a commit of the type feat introduces a new feature to the codebase (this correlates with MINOR in Semantic Versioning). +- `deprecate: description of the PR`: The commit deprecates existing functionality, but does not remove it from the product (this correlates with MINOR in Semantic Versioning). +- `BREAKING CHANGE`: a commit that has a footer BREAKING CHANGE:, or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type. +Examples: + - `fix!: description of the ticket` + - If the PR has `BREAKING CHANGE`: in its description is a breaking change +- `remove!: description of the PR`: The commit removes a feature from the product. Typically features are deprecated first for a period of time before being removed. Removing a feature is a breaking change (correlating with MAJOR in Semantic Versioning). From 3d97e2194d1281954bf1203d2542d966e5bfa191 Mon Sep 17 00:00:00 2001 From: andreaangiolillo Date: Tue, 8 Aug 2023 16:28:30 +0100 Subject: [PATCH 09/10] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ebd9398012..c42c753abf 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ See [Troubleshooting](website/docs/troubleshooting.html.markdown). ## Developing the Provider See [CONTRIBUTING.md](./CONTRIBUTING.md). -### Autoclose stale issues and PRs +## Autoclose stale issues and PRs - After 30 days of no activity (no comments or commits on an issue/PR) we automatically tag it as "stale" and add a message: ```This issue/PR has gone 30 days without any activity and meets the project's definition of "stale". This will be auto-closed if there is no new activity over the next 30 days. If the issue is still relevant and active, you can simply comment with a "bump" to keep it open, or add the label "not_stale". Thanks for keeping our repository healthy!``` - After 30 more days of no activity we automatically close the issue/PR. From d8a3aabfe37044d62bb66fd33cefc565c14ff5bf Mon Sep 17 00:00:00 2001 From: andreaangiolillo Date: Tue, 8 Aug 2023 16:35:06 +0100 Subject: [PATCH 10/10] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c42c753abf..4dd2db3395 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ In order to use and/or test beta resources and datasources in this provider you' ```bash export MONGODB_ATLAS_ENABLE_BETA = true ``` -### Logs +## Logs To help with issues, you can turn on Logs with `export TF_LOG=TRACE`. Note: this is very noisy. To export logs to file, you can use `export TF_LOG_PATH=terraform.log`