Upgrade Guide for Terraform MongoDB Atlas 0.4.0

As you might have noticed in our announcement blog, we added a lot in the newest version of the Terraform MongoDB Atlas Provider. In order to make the transition to 0.4.0 as smooth as possible, we’ve crafted this short guide to call out a few of the most potentially impactful changes and provide guidance on how to proceed.

Before You Upgrade

Remember to follow any standard, recommended Terraform Provider upgrade procedures, especially ensuring that you backup your Terraform Configuration Files and State Files. We also recommend ensuring you have a backup enabled on your MongoDB Atlas clusters, just to provide an extra layer of safety.

Deprecated Argument Name in the Database User Resource

Having the same argument name with two different contexts in the same resource can be very confusing! Up until now the authentication database argument and the database being assigned a role argument were both named “database_name”.

In order to reduce confusion we’ve deviated a bit from the underlying API and are calling out the authentication database more clearly. Both argument names will work in 0.4.0, but you will get a warning about the deprecated value database_name until you update it. This means you can change your configuration files now and we’ll remove the deprecated option in a future version.

Here’s an example:

Version 0.3.1:

resource "mongodbatlas_database_user" "test" {
    username      = "test-acc-username"
    password      = "test-acc-password"
    project_id    = "<PROJECT-ID>"
    database_name = "admin"

    roles {
        role_name     = "readWrite"
        database_name = "admin"
    }

    roles {
        role_name     = "%s"
        database_name = "admin"
    }
}

Version 0.4.0:

resource "mongodbatlas_database_user" "test" {
    username      = "test-acc-username"
    password      = "test-acc-password"
    project_id    = "<PROJECT-ID>"
    auth_database_name = "admin"

    roles {
        role_name     = "readWrite"
        database_name = "admin"
    }

    roles {
        role_name     = "%s"
        database_name = "admin"
    }
}

Major Change: New IP Whitelist Resource

Previously, the entire Project IP Whitelist was defined in a single Terraform resource, which meant a change to one item in the list would impact all items. Here’s an example:

resource "mongodbatlas_project_ip_whitelist" "test" {
    project_id = <PROJECT-ID>

    whitelist {
      cidr_block = "1.2.3.4/32"
      comment    = "cidr block for tf acc testing"
    }
    whitelist {
      ip_address = "2.3.4.5"
      comment    = "ip address for tf acc testing"
    }
    whitelist {
      cidr_block = "3.4.5.6/32"
      comment    = "cidr block for tf acc testing"
    }
    whitelist {
      ip_address = "4.5.6.7"
      comment    = "ip address for tf acc testing"
    }
 }

In order to enable modifying Project IP Whitelist entries with minimal impact, you will now define each IP whitelist entry as its own resource. Here’s an example:

resource "mongodbatlas_project_ip_whitelist" "test" {
    project_id = <PROJECT-ID>
    cidr_block = "1.2.3.4/32"
    comment    = "cidr block for tf acc testing"
}  
resource "mongodbatlas_project_ip_whitelist" "test2" {
    project_id = <PROJECT-ID>
    ip_address = "2.3.4.5"
    comment    = "ip address for tf acc testing"
}
resource "mongodbatlas_project_ip_whitelist" "test3" {
    project_id = <PROJECT-ID>
    cidr_block = "3.4.5.6/32"
    comment    = "cidr block for tf acc testing"
}
resource "mongodbatlas_project_ip_whitelist" "test4" {
    project_id = <PROJECT-ID>
    ip_address = "4.5.6.7"
    comment    = "ip address for tf acc testing"
}

In order to do this without impacting your current Project IP Whitelist that exists in Atlas, implement the changes in the following order:

1. Remove your Project IP Whitelist from the Terraform state (replace name with the name you gave your resource). This removes it from the state file but not MongoDB Atlas.

$ terraform state rm mongodbatlas_project_ip_whitelist.name

2. Upgrade the provider to 0.4.0.

$ terraform init -upgrade

3. Change your Terraform Configuration file (.tf file) to the new format show above, giving each resource block a unique name.

resource "mongodbatlas_project_ip_whitelist" "test4" {
    project_id = <PROJECT-ID>
    ip_address = "4.5.6.7"
    comment    = "ip address for tf acc testing"
}

4. Import your current Project IP Whitelist entries that exist within Atlas back in, replacing name with your resource name, <PROJECT_ID> with the Atlas Project ID, and with the associated IP address or CIDR block.

$ terraform import mongodbatlas_project_ip_whitelist.name <PROJECT_ID>-<IP-or-CIDR>  

If you’ve configured peering for AWS, this change now enables you to add a Project IP Whitelist resource for an AWS Security Group.

New Resources!

New resources are fully documented with examples in the Terraform MongoDB Atlas Provider documentation located in the Terraform Provider documentation.

Also, be sure to check out the changelog in the GitHub repository for more details.

Upgrading to 0.4.0

Once you’ve read this guide and are confident that you are ready to proceed, the actual upgrade is incredibly easy as the Terraform MongoDB Atlas Provider is officially verified by HashiCorp. All you need to do to upgrade is enter terraform init -upgrade on the command line and Terraform will download and install 0.4.0 automatically.