Skip to content

Commit 4604103

Browse files
remyleoneremyleone
committed
doc: improve migration guide to v2 with a migration example
1 parent 113e11f commit 4604103

File tree

1 file changed

+63
-9
lines changed

1 file changed

+63
-9
lines changed

‎docs/guides/migration_guide_v2.md

Lines changed: 63 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@ description: |-
66

77
# Migrating from v1 to v2
88

9-
-> **Note:** The version 2 is not released yet but versions `v1.11+` allow you to do a smooth migration to the `v2`. In other words, there will be no breaking change between `v1.11+` and `v2`. The `v2` roadmap is available [here](https://github.com/terraform-providers/terraform-provider-scaleway/issues/125).
9+
-> **Note:** The version 2 is not released yet but versions `v1.11+` allow you to do a smooth migration to the `v2`.
10+
In other words, there will be no breaking change between `v1.11+` and `v2`.
11+
The `v2` roadmap is available [here](https://github.com/terraform-providers/terraform-provider-scaleway/issues/125).
1012

1113
This page guides you through the process of migrating your version 1 resources to their version 2 equivalent.
1214
To prepare the launch of all new Scaleway products, we completely changed the naming of all resources (as well as their attributes) in version 2 of the Terraform provider.
@@ -51,7 +53,8 @@ Below you find an overview of changes in the provider config:
5153
| `token` | `secret_key` |
5254
| `organization` | `organization_id` |
5355

54-
~> **Important:** `access_key` should now only be used for your access key (e.g. `SCWZFD9BPQ4TZ14SM1YS`). Your secret key (previously known as _token_) must be set in `secret_key` (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).
56+
~> **Important:** `access_key` should now only be used for your access key (e.g. `SCWZFD9BPQ4TZ14SM1YS`).
57+
Your secret key (previously known as _token_) must be set in `secret_key` (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).
5558

5659
Below you find an overview of the changes in environment variables:
5760

@@ -66,11 +69,57 @@ Below you find an overview of the changes in environment variables:
6669
| `SCW_REGION` | `SCW_DEFAULT_REGION` |
6770
| `SCW_TOKEN` | `SCW_SECRET_KEY` |
6871

69-
~> **Important:** `SCALEWAY_ACCESS_KEY` was changed to `SCW_ACCESS_KEY`. This should be your access key (e.g. `SCWZFD9BPQ4TZ14SM1YS`). Your secret key (previously known as _token_) must be set in `SCW_SECRET_KEY` (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).
72+
~> **Important:** `SCALEWAY_ACCESS_KEY` was changed to `SCW_ACCESS_KEY`.
73+
This should be your access key (e.g. `SCWZFD9BPQ4TZ14SM1YS`).
74+
Your secret key (previously known as _token_) must be set in `SCW_SECRET_KEY` (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).
75+
76+
Terraform can also read standard Scaleway configuration files.
77+
By doing so, you can use the same configuration between different tools such as the [CLI](https://github.com/scaleway/scaleway-cli) or [Packer](https://www.packer.io/docs/builders/scaleway).
7078

7179
## Resources
7280

73-
All resources are from now on prefixed by `scaleway`, their product category and their product name (`scaleway_{product-category-name}_{product-name}_{resource-name}`). For instances an S3 bucket belongs to the `Storage` product category and is a resource of the `Object` product. Hence it is named: `scaleway_object_bucket`.
81+
All resources are from now on prefixed by `scaleway`, their product category and their product name (`scaleway_{product-category-name}_{product-name}_{resource-name}`).
82+
For instances an S3 bucket belongs to the `Storage` product category and is a resource of the `Object` product.
83+
Hence it is named: `scaleway_object_bucket`.
84+
85+
### How can I migrate from existing code?
86+
87+
Because the resources changed their name, we cannot using automatic state migration.
88+
We will first manually remove the resource from the terraform state and then use [`terraform import`](https://www.terraform.io/docs/import/usage.html) to import existing resources to a renamed resource.
89+
90+
For instance, let's suppose that you have resource in `fr-par-1` such as:
91+
92+
```hcl-terraform
93+
provider "scaleway" {
94+
zone= "fr-par-1"
95+
}
96+
97+
resource scaleway_server main {
98+
name = "foobar"
99+
type = "DEV1-S"
100+
image = "cf44b8f5-77e2-42ed-8f1e-09ed5bb028fc"
101+
}
102+
```
103+
104+
First, let's delete the resource from your terraform state using the [`terraform state`](https://www.terraform.io/docs/commands/state/index.html) command.
105+
You can do it using: `terraform state rm scaleway_server.main`.
106+
107+
Once this is done, refactor your terraform code to:
108+
109+
```hcl-terraform
110+
provider "scaleway" {
111+
zone= "fr-par-1"
112+
}
113+
114+
resource scaleway_instance_server main {
115+
name = "foobar"
116+
type = "DEV1-S"
117+
image = "cf44b8f5-77e2-42ed-8f1e-09ed5bb028fc"
118+
}
119+
```
120+
121+
and run `terraform import scaleway_instance_server.main fr-par-1/11111111-1111-1111-1111-111111111111` where `11111111-1111-1111-1111-111111111111` is the id of your resource.
122+
After importing, you can verify using `terraform apply` that you are in a desired state and that no changes need to be done.
74123

75124
### Instance
76125

@@ -81,7 +130,8 @@ This means that all old instance resources are now prefixed with `scaleway_insta
81130

82131
`scaleway_server` was renamed to `scaleway_instance_server`.
83132

84-
In version 1, attachments of volumes where done on the volume resource. But from now on, this is done on the `scaleway_instance_server` resource.
133+
In version 1, attachments of volumes where done on the volume resource.
134+
From now on, this is done on the `scaleway_instance_server` resource.
85135

86136
Thus, to create a server with a volume attached:
87137

@@ -118,12 +168,14 @@ resource "scaleway_instance_ip" "test_ip" {
118168
`scaleway_volume` was renamed to `scaleway_instance_volume`.
119169
The former attributes can still be used on the new volume resource.
120170

121-
Additionally, from now on, you can also create new volumes based on other volumes or snapshots. For more information check the [new volume `scaleway_instance_volume` resource](../resources/instance_volume.md).
171+
Additionally, from now on, you can also create new volumes based on other volumes or snapshots.
172+
For more information check the [new volume `scaleway_instance_volume` resource](../resources/instance_volume.md).
122173

123174
#### Renamed: `scaleway_ssh_key` -> `scaleway_account_ssk_key`
124175

125176
`scaleway_ssh_key` was renamed to `scaleway_account_ssk_key`
126-
The `key` attribute has been renamed to `public_key`. A `name` required attribute and an `organization_id` optional attribute have been added.
177+
The `key` attribute has been renamed to `public_key`.
178+
A `name` required attribute and an `organization_id` optional attribute have been added.
127179

128180
#### Removed: `scaleway_user_data`
129181

@@ -143,12 +195,14 @@ Tokens should be created in the console.
143195

144196
The `scaleway_volume_attachment` was removed in version 2.
145197

146-
Volumes can in version 2 only be attached on the server resource. The [above example](#scaleway_server-gt-scaleway_instance_server) shows how this works.
198+
Volumes can in version 2 only be attached on the server resource.
199+
The [above example](#scaleway_server-gt-scaleway_instance_server) shows how this works.
147200

148201
### Storage
149202

150203
#### Renamed: `scaleway_bucket` -> `scaleway_object_bucket`
151204

152205
The `scaleway_bucket` was moved to the `object` product in the `storage` product category.
153206

154-
It's behaviour remained the same, but we also added an [`acl` attribute](../resources/object_bucket.md#acl). This attribute takes canned ACLs.
207+
It's behaviour remained the same, but we also added an [`acl` attribute](../resources/object_bucket.md#acl).
208+
This attribute takes canned ACLs.

0 commit comments

Comments
 (0)