|
| 1 | +--- |
| 2 | +page_title: "Migration Guide: Stream Instance to Stream Workspace" |
| 3 | +--- |
| 4 | + |
| 5 | +# Migration Guide: Stream Instance to Stream Workspace |
| 6 | + |
| 7 | +**Objective**: This guide explains how to replace the deprecated `mongodbatlas_stream_instance` resource with the `mongodbatlas_stream_workspace` resource. For data source migrations, refer to the [output changes](#output-changes) section. |
| 8 | + |
| 9 | +## Why do we have both `mongodbatlas_stream_instance` and `mongodbatlas_stream_workspace` resources? |
| 10 | + |
| 11 | +Both `mongodbatlas_stream_instance` and `mongodbatlas_stream_workspace` resources currently allow customers to manage MongoDB Atlas Stream Processing workspaces. Initially, only `mongodbatlas_stream_instance` existed. However, MongoDB Atlas has evolved its terminology and API to use "workspace" instead of "instance" for stream processing environments. To align with this change and provide a clearer, more consistent naming convention, we created the `mongodbatlas_stream_workspace` resource as a direct replacement. |
| 12 | + |
| 13 | +## If I am using `mongodbatlas_stream_instance`, why should I move to `mongodbatlas_stream_workspace`? |
| 14 | + |
| 15 | +The `mongodbatlas_stream_workspace` resource provides the exact same functionality as `mongodbatlas_stream_instance` but with updated terminology that aligns with MongoDB Atlas's current naming conventions. This change provides: |
| 16 | + |
| 17 | +1. **Consistent Terminology**: Aligns with MongoDB Atlas's current documentation and UI terminology |
| 18 | +2. **Future-Proof**: New stream processing features will be developed using the workspace terminology |
| 19 | +3. **Clearer Intent**: The term "workspace" better describes the stream processing environment |
| 20 | + |
| 21 | +To maintain consistency with MongoDB Atlas's terminology and ensure you're using the most current resource names, we recommend migrating to `mongodbatlas_stream_workspace`. The `mongodbatlas_stream_instance` resource is deprecated and will be removed in future major versions of the provider. |
| 22 | + |
| 23 | +## How should I move to `mongodbatlas_stream_workspace`? |
| 24 | + |
| 25 | +To move from `mongodbatlas_stream_instance` to `mongodbatlas_stream_workspace` we offer two alternatives: |
| 26 | +1. [(Recommended) Use the `moved` block](#migration-using-the-moved-block-recommended) |
| 27 | +2. [Manually use the import command with the `mongodbatlas_stream_workspace` resource](#migration-using-import) |
| 28 | + |
| 29 | +### Best Practices Before Migrating |
| 30 | + |
| 31 | +Before doing any migration, create a backup of your [Terraform state file](https://developer.hashicorp.com/terraform/cli/commands/state). |
| 32 | + |
| 33 | +## Migration using the Moved block (recommended) |
| 34 | + |
| 35 | +This is our recommended method to migrate from `mongodbatlas_stream_instance` to `mongodbatlas_stream_workspace`. The [moved block](https://developer.hashicorp.com/terraform/language/moved) is a Terraform feature that allows to move between resource types. It's conceptually similar to running `removed` and `import` commands separately but it brings the convenience of doing it in one step. |
| 36 | + |
| 37 | +**Prerequisites:** |
| 38 | + - Terraform version 1.8 or later is required, more information in the [State Move page](https://developer.hashicorp.com/terraform/plugin/framework/resources/state-move). |
| 39 | + - MongoDB Atlas Provider version 2.1 or later is required. |
| 40 | + |
| 41 | +The basic experience when using the `moved` block is as follows: |
| 42 | +1. Before starting, run `terraform plan` to make sure that there are no planned changes. |
| 43 | +2. Add the `mongodbatlas_stream_workspace` resource definition. |
| 44 | +3. Comment out or delete the `mongodbatlas_stream_instance` resource definition. |
| 45 | +4. Update the references from your previous stream instance resource: `mongodbatlas_stream_instance.this.XXXX` to the new `mongodbatlas_stream_workspace.this.XXX`. |
| 46 | + - Change `instance_name` to `workspace_name` in your references |
| 47 | + - Double check [output-changes](#output-changes) to ensure the underlying configuration stays unchanged. |
| 48 | +5. Add the `moved` block to your configuration file, e.g.: |
| 49 | +```terraform |
| 50 | +moved { |
| 51 | + from = mongodbatlas_stream_instance.this |
| 52 | + to = mongodbatlas_stream_workspace.this |
| 53 | +} |
| 54 | +``` |
| 55 | +6. Run `terraform plan` and make sure that there are no planned changes, only the moved block should be shown. This is an example output of a successful plan: |
| 56 | +```text |
| 57 | + # mongodbatlas_stream_instance.this has moved to mongodbatlas_stream_workspace.this |
| 58 | + resource "mongodbatlas_stream_workspace" "this" { |
| 59 | + workspace_name = "my-workspace" |
| 60 | + # (6 unchanged attributes hidden) |
| 61 | + } |
| 62 | +
|
| 63 | + Plan: 0 to add, 0 to change, 0 to destroy. |
| 64 | +``` |
| 65 | + |
| 66 | +7. Run `terraform apply` to apply the changes. The `mongodbatlas_stream_instance` resource will be removed from the Terraform state and the `mongodbatlas_stream_workspace` resource will be added. |
| 67 | +8. Hashicorp recommends to keep the move block in your configuration file to help track the migrations, however you can delete the `moved` block from your configuration file without any adverse impact. |
| 68 | + |
| 69 | +## Migration using import |
| 70 | + |
| 71 | +**Note**: We recommend the [`moved` block](#migration-using-the-moved-block-recommended) method as it's more convenient and less error-prone. |
| 72 | + |
| 73 | +This method uses [Terraform native tools](https://developer.hashicorp.com/terraform/language/import/generating-configuration) and works if you: |
| 74 | +1. Have an existing stream workspace without any Terraform configuration and want to import and manage it with Terraform. |
| 75 | +2. Have existing `mongodbatlas_stream_instance` resource(s) but you can't use the [recommended approach](#migration-using-the-moved-block-recommended). |
| 76 | + |
| 77 | +The process works as follow: |
| 78 | +1. If you have an existing `mongodbatlas_stream_instance` resource, remove it from your configuration and delete it from the state file, e.g.: `terraform state rm mongodbatlas_stream_instance.this`. |
| 79 | +2. Find the import IDs of the stream workspaces you want to migrate: `{PROJECT_ID}-{WORKSPACE_NAME}`, such as `664619d870c247237f4b86a6-my-workspace` |
| 80 | +3. Import it using the `terraform import` command, e.g.: `terraform import mongodbatlas_stream_workspace.this 664619d870c247237f4b86a6-my-workspace`. |
| 81 | +4. Run `terraform plan -generate-config-out=stream_workspace.tf`. This should generate a `stream_workspace.tf` file. |
| 82 | +5. Update the references from your previous stream instance resource: `mongodbatlas_stream_instance.this.XXXX` to the new `mongodbatlas_stream_workspace.this.XXX`. |
| 83 | + - Change `instance_name` to `workspace_name` in your references |
| 84 | + - Double check [output-changes](#output-changes) to ensure the underlying configuration stays unchanged. |
| 85 | +6. Run `terraform apply`. You should see the resource(s) imported. |
| 86 | + |
| 87 | +## Main Changes Between `mongodbatlas_stream_instance` and `mongodbatlas_stream_workspace` |
| 88 | + |
| 89 | +The primary change is the field name for identifying the stream processing workspace: |
| 90 | + |
| 91 | +1. **Field Name**: `instance_name` is replaced with `workspace_name` |
| 92 | +2. **Resource Name**: `mongodbatlas_stream_instance` becomes `mongodbatlas_stream_workspace` |
| 93 | +3. **Data Source Names**: |
| 94 | + - `mongodbatlas_stream_instance` becomes `mongodbatlas_stream_workspace` |
| 95 | + - `mongodbatlas_stream_instances` becomes `mongodbatlas_stream_workspaces` |
| 96 | + |
| 97 | +All other functionality remains identical. |
| 98 | + |
| 99 | +### Example 1: Old Configuration (`mongodbatlas_stream_instance`) |
| 100 | + |
| 101 | +```terraform |
| 102 | +resource "mongodbatlas_stream_instance" "this" { |
| 103 | + project_id = var.project_id |
| 104 | + instance_name = "my-stream-workspace" |
| 105 | + data_process_region = { |
| 106 | + region = "VIRGINIA_USA" |
| 107 | + cloud_provider = "AWS" |
| 108 | + } |
| 109 | +} |
| 110 | +
|
| 111 | +data "mongodbatlas_stream_instance" "this" { |
| 112 | + project_id = var.project_id |
| 113 | + instance_name = mongodbatlas_stream_instance.this.instance_name |
| 114 | +} |
| 115 | +
|
| 116 | +data "mongodbatlas_stream_instances" "all" { |
| 117 | + project_id = var.project_id |
| 118 | +} |
| 119 | +``` |
| 120 | + |
| 121 | +### Example 2: New Configuration (`mongodbatlas_stream_workspace`) |
| 122 | + |
| 123 | +```terraform |
| 124 | +resource "mongodbatlas_stream_workspace" "this" { |
| 125 | + project_id = var.project_id |
| 126 | + workspace_name = "my-stream-workspace" |
| 127 | + data_process_region = { |
| 128 | + region = "VIRGINIA_USA" |
| 129 | + cloud_provider = "AWS" |
| 130 | + } |
| 131 | +} |
| 132 | +
|
| 133 | +data "mongodbatlas_stream_workspace" "this" { |
| 134 | + project_id = var.project_id |
| 135 | + workspace_name = mongodbatlas_stream_workspace.this.workspace_name |
| 136 | +} |
| 137 | +
|
| 138 | +data "mongodbatlas_stream_workspaces" "all" { |
| 139 | + project_id = var.project_id |
| 140 | +} |
| 141 | +``` |
| 142 | + |
| 143 | +### Output Changes |
| 144 | + |
| 145 | +The only change in outputs is the field name: |
| 146 | +- **Field Name Change**: |
| 147 | + - Before: `mongodbatlas_stream_instance.this.instance_name` |
| 148 | + - After: `mongodbatlas_stream_workspace.this.workspace_name` |
| 149 | + |
| 150 | +All other attributes (`project_id`, `data_process_region`, `stream_config`, `hostnames`, etc.) remain exactly the same. |
| 151 | + |
| 152 | +## Complete Migration Example with Moved Block |
| 153 | + |
| 154 | +Here's a complete example showing the migration process: |
| 155 | + |
| 156 | +### Step 1: Original Configuration |
| 157 | +```terraform |
| 158 | +resource "mongodbatlas_stream_instance" "example" { |
| 159 | + project_id = var.project_id |
| 160 | + instance_name = "my-workspace" |
| 161 | + data_process_region = { |
| 162 | + region = "VIRGINIA_USA" |
| 163 | + cloud_provider = "AWS" |
| 164 | + } |
| 165 | +} |
| 166 | +
|
| 167 | +output "stream_hostnames" { |
| 168 | + value = mongodbatlas_stream_instance.example.hostnames |
| 169 | +} |
| 170 | +``` |
| 171 | + |
| 172 | +### Step 2: Add Moved Block and New Resource |
| 173 | +```terraform |
| 174 | +# Add the moved block |
| 175 | +moved { |
| 176 | + from = mongodbatlas_stream_instance.example |
| 177 | + to = mongodbatlas_stream_workspace.example |
| 178 | +} |
| 179 | +
|
| 180 | +# Replace with new resource (note: instance_name becomes workspace_name) |
| 181 | +resource "mongodbatlas_stream_workspace" "example" { |
| 182 | + project_id = var.project_id |
| 183 | + workspace_name = "my-workspace" |
| 184 | + data_process_region = { |
| 185 | + region = "VIRGINIA_USA" |
| 186 | + cloud_provider = "AWS" |
| 187 | + } |
| 188 | +} |
| 189 | +
|
| 190 | +# Update output references |
| 191 | +output "stream_hostnames" { |
| 192 | + value = mongodbatlas_stream_workspace.example.hostnames |
| 193 | +} |
| 194 | +``` |
| 195 | + |
| 196 | +### Step 3: Apply and Clean Up |
| 197 | +After running `terraform apply`, you can optionally remove the `moved` block: |
| 198 | + |
| 199 | +```terraform |
| 200 | +resource "mongodbatlas_stream_workspace" "example" { |
| 201 | + project_id = var.project_id |
| 202 | + workspace_name = "my-workspace" |
| 203 | + data_process_region = { |
| 204 | + region = "VIRGINIA_USA" |
| 205 | + cloud_provider = "AWS" |
| 206 | + } |
| 207 | +} |
| 208 | +
|
| 209 | +output "stream_hostnames" { |
| 210 | + value = mongodbatlas_stream_workspace.example.hostnames |
| 211 | +} |
| 212 | +``` |
0 commit comments