Skip to content

Commit 642c837

Browse files
marceljkmarceljk
authored
feat(iaas): provide migration guide for the deprecated fields from network_area resource (#1134)
1 parent 90fe355 commit 642c837

3 files changed

Lines changed: 200 additions & 4 deletions

File tree

‎docs/resources/network_area.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,78 @@ import {
2828
}
2929
```
3030

31+
## Migration of IaaS resources from versions <= v0.78.1
32+
33+
The release of the STACKIT IaaS API v2 provides a lot of new features, but also includes some breaking changes
34+
(when coming from v1 of the STACKIT IaaS API) which must be somehow represented on Terraform side. The
35+
`stackit_network_area` resource deprecated some fields. See the example below how to migrate your resources.
36+
37+
### Migration: Network area resource (stackit_network_area)
38+
39+
**Configuration for <= v0.78.1**
40+
41+
```terraform
42+
resource "stackit_network_area" "example" {
43+
organization_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
44+
name = "my-network-area"
45+
transfer_network = "192.168.1.0/24" # transfer_network field got deprecated for provider versions > v0.74.0, use the new "stackit_network_area_region" resource instead
46+
network_ranges = [
47+
{
48+
prefix = "192.168.0.0/25" # network_ranges field got deprecated for provider versions > v0.74.0, use the new "stackit_network_area_region" resource instead
49+
}
50+
]
51+
default_nameservers = ["8.8.8.8"] # default_nameservers field got deprecated for provider versions > v0.74.0, use the new "stackit_network_area_region" resource instead
52+
default_prefix_length = 25 # default_prefix_length field got deprecated for provider versions > v0.74.0, use the new "stackit_network_area_region" resource instead
53+
max_prefix_length = 29 # max_prefix_length field got deprecated for provider versions > v0.74.0, use the new "stackit_network_area_region" resource instead
54+
min_prefix_length = 24 # min_prefix_length field got deprecated for provider versions > v0.74.0, use the new "stackit_network_area_region" resource instead
55+
}
56+
```
57+
The previous configuration has some deprecated fields.
58+
59+
**Configuration for > v0.78.1**
60+
61+
To migrate from a previous state, you need to modify your configuration like this:
62+
63+
```terraform
64+
resource "stackit_network_area" "example" {
65+
organization_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
66+
name = "my-network-area"
67+
# remove all the deprecated fields
68+
}
69+
70+
# Add the new resource "stackit_network_area_region" and configure it with all the deprecated values from the "stackit_network_area" resource
71+
resource "stackit_network_area_region" "example" {
72+
organization_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
73+
network_area_id = stackit_network_area.example.network_area_id
74+
region = "eu01"
75+
ipv4 = {
76+
transfer_network = "192.168.1.0/24"
77+
network_ranges = [
78+
{
79+
prefix = "192.168.0.0/25"
80+
}
81+
]
82+
default_nameservers = ["8.8.8.8"]
83+
default_prefix_length = 25
84+
max_prefix_length = 29
85+
min_prefix_length = 24
86+
}
87+
}
88+
89+
# Add this import for "stackit_network_area_region" to migrate from the previous configuration
90+
import {
91+
to = stackit_network_area_region.example
92+
id = "${stackit_network_area.example.id},eu01"
93+
}
94+
```
95+
96+
After modifying the configuration, run `$ terraform plan` to check what terraform will do.
97+
The changes should trigger an update in-place for the existing "stackit_network_area" where the deprecated fields will be removed and the resource "stackit_network_area_region" should be imported.
98+
It shouldn't trigger any recreation. If terraform wants to recreate any of the resources, verify that you are using the provider version > v0.78.1 and have everything defined correctly.
99+
100+
When everything looks good, run `$ terraform apply` to apply these changes.
101+
When the run is completed, you can remove the import-block. Run `$ terraform plan` to verify that the infrastructure matches the configuration.
102+
31103
<!-- schema generated by tfplugindocs -->
32104
## Schema
33105

‎stackit/internal/services/iaas/networkarea/resource.go‎

Lines changed: 39 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ var (
5757
_ resource.ResourceWithConfigure = &networkAreaResource{}
5858
_ resource.ResourceWithImportState = &networkAreaResource{}
5959
_ resource.ResourceWithValidateConfig = &networkAreaResource{}
60+
_ resource.ResourceWithModifyPlan = &networkAreaResource{}
6061
)
6162

6263
type Model struct {
@@ -83,7 +84,12 @@ type Model struct {
8384

8485
// Deprecated: Will be removed in May 2026. Only introduced to make the IaaS v1 -> v2 API migration non-breaking in the Terraform provider. LegacyMode checks if any of the deprecated fields are set which now relate to the network area region API resource.
8586
func (model *Model) LegacyMode() bool {
86-
return !model.NetworkRanges.IsNull() || model.NetworkRanges.IsUnknown() || !model.TransferNetwork.IsNull() || model.TransferNetwork.IsUnknown() || !model.DefaultNameservers.IsNull() || model.DefaultNameservers.IsUnknown() || model.DefaultPrefixLength != types.Int64Value(int64(defaultValueDefaultPrefixLength)) || model.MinPrefixLength != types.Int64Value(int64(defaultValueMinPrefixLength)) || model.MaxPrefixLength != types.Int64Value(int64(defaultValueMaxPrefixLength))
87+
return !model.NetworkRanges.IsNull() || model.NetworkRanges.IsUnknown() ||
88+
!model.TransferNetwork.IsNull() || model.TransferNetwork.IsUnknown() ||
89+
!model.DefaultNameservers.IsNull() || model.DefaultNameservers.IsUnknown() ||
90+
(model.DefaultPrefixLength != types.Int64Value(int64(defaultValueDefaultPrefixLength)) && model.DefaultPrefixLength.IsUnknown()) ||
91+
(model.MinPrefixLength != types.Int64Value(int64(defaultValueMinPrefixLength)) && model.MinPrefixLength.IsUnknown()) ||
92+
(model.MaxPrefixLength != types.Int64Value(int64(defaultValueMaxPrefixLength)) && model.MaxPrefixLength.IsUnknown())
8793
}
8894

8995
// Struct corresponding to Model.NetworkRanges[i]
@@ -109,6 +115,38 @@ type networkAreaResource struct {
109115
resourceManagerClient *resourcemanager.APIClient
110116
}
111117

118+
func (r *networkAreaResource) ModifyPlan(ctx context.Context, req resource.ModifyPlanRequest, resp *resource.ModifyPlanResponse) { // nolint:gocritic // function signature required by Terraform
119+
// If the resource is being created, do nothing.
120+
if req.State.Raw.IsNull() {
121+
return
122+
}
123+
124+
var state, plan Model
125+
req.State.Get(ctx, &state)
126+
req.Plan.Get(ctx, &plan)
127+
128+
// Check if transferNetwork was set before and is changed to a different value
129+
if !plan.TransferNetwork.IsNull() && !state.TransferNetwork.IsNull() &&
130+
plan.TransferNetwork.ValueString() != state.TransferNetwork.ValueString() {
131+
// Trigger replace
132+
resp.RequiresReplace.Append(path.Root("transfer_network"))
133+
}
134+
135+
// Check if no transferNetwork was set before and transferNetwork is added now
136+
if !plan.TransferNetwork.IsNull() && state.TransferNetwork.IsNull() {
137+
// Trigger replace
138+
resp.RequiresReplace.Append(path.Root("transfer_network"))
139+
}
140+
141+
// Check if deprecated fields were set before and are now removed
142+
if !state.TransferNetwork.IsNull() && !state.NetworkRanges.IsNull() && plan.TransferNetwork.IsNull() && plan.NetworkRanges.IsNull() {
143+
resp.Diagnostics.AddWarning("Deprecated fields removed",
144+
fmt.Sprintf("You are removing deprecated fields from this resource. They will only be removed from the terraform state.\n"+
145+
"For a complete migration, please import `stackit_network_area_region` with the ID `%s,eu01`.\n"+
146+
"If you don't import the resource, you may run into issues.", state.Id.ValueString()))
147+
}
148+
}
149+
112150
// Metadata returns the resource type name.
113151
func (r *networkAreaResource) Metadata(_ context.Context, req resource.MetadataRequest, resp *resource.MetadataResponse) {
114152
resp.TypeName = req.ProviderTypeName + "_network_area"
@@ -242,9 +280,6 @@ func (r *networkAreaResource) Schema(_ context.Context, _ resource.SchemaRequest
242280
DeprecationMessage: deprecationMsg,
243281
Description: "Classless Inter-Domain Routing (CIDR) for configuration of network area for region `eu01`.",
244282
Optional: true,
245-
PlanModifiers: []planmodifier.String{
246-
stringplanmodifier.RequiresReplace(),
247-
},
248283
},
249284
// Deprecated: Will be removed in May 2026. Only kept to make the IaaS v1 -> v2 API migration non-breaking in the Terraform provider.
250285
"default_prefix_length": schema.Int64Attribute{

‎templates/resources/network_area.md.tmpl‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
# generated by https://github.com/hashicorp/terraform-plugin-docs
3+
page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}"
4+
subcategory: ""
5+
description: |-
6+
{{ .Description | trimspace }}
7+
---
8+
9+
# {{.Name}} ({{.Type}})
10+
11+
{{ .Description | trimspace }}
12+
13+
## Example Usage
14+
15+
{{ tffile (printf "examples/resources/%s/resource.tf" .Name) }}
16+
17+
## Migration of IaaS resources from versions <= v0.78.1
18+
19+
The release of the STACKIT IaaS API v2 provides a lot of new features, but also includes some breaking changes
20+
(when coming from v1 of the STACKIT IaaS API) which must be somehow represented on Terraform side. The
21+
`stackit_network_area` resource deprecated some fields. See the example below how to migrate your resources.
22+
23+
### Migration: Network area resource (stackit_network_area)
24+
25+
**Configuration for <= v0.78.1**
26+
27+
```terraform
28+
resource "stackit_network_area" "example" {
29+
organization_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
30+
name = "my-network-area"
31+
transfer_network = "192.168.1.0/24" # transfer_network field got deprecated for provider versions > v0.74.0, use the new "stackit_network_area_region" resource instead
32+
network_ranges = [
33+
{
34+
prefix = "192.168.0.0/25" # network_ranges field got deprecated for provider versions > v0.74.0, use the new "stackit_network_area_region" resource instead
35+
}
36+
]
37+
default_nameservers = ["8.8.8.8"] # default_nameservers field got deprecated for provider versions > v0.74.0, use the new "stackit_network_area_region" resource instead
38+
default_prefix_length = 25 # default_prefix_length field got deprecated for provider versions > v0.74.0, use the new "stackit_network_area_region" resource instead
39+
max_prefix_length = 29 # max_prefix_length field got deprecated for provider versions > v0.74.0, use the new "stackit_network_area_region" resource instead
40+
min_prefix_length = 24 # min_prefix_length field got deprecated for provider versions > v0.74.0, use the new "stackit_network_area_region" resource instead
41+
}
42+
```
43+
The previous configuration has some deprecated fields.
44+
45+
**Configuration for > v0.78.1**
46+
47+
To migrate from a previous state, you need to modify your configuration like this:
48+
49+
```terraform
50+
resource "stackit_network_area" "example" {
51+
organization_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
52+
name = "my-network-area"
53+
# remove all the deprecated fields
54+
}
55+
56+
# Add the new resource "stackit_network_area_region" and configure it with all the deprecated values from the "stackit_network_area" resource
57+
resource "stackit_network_area_region" "example" {
58+
organization_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
59+
network_area_id = stackit_network_area.example.network_area_id
60+
region = "eu01"
61+
ipv4 = {
62+
transfer_network = "192.168.1.0/24"
63+
network_ranges = [
64+
{
65+
prefix = "192.168.0.0/25"
66+
}
67+
]
68+
default_nameservers = ["8.8.8.8"]
69+
default_prefix_length = 25
70+
max_prefix_length = 29
71+
min_prefix_length = 24
72+
}
73+
}
74+
75+
# Add this import for "stackit_network_area_region" to migrate from the previous configuration
76+
import {
77+
to = stackit_network_area_region.example
78+
id = "${stackit_network_area.example.id},eu01"
79+
}
80+
```
81+
82+
After modifying the configuration, run `$ terraform plan` to check what terraform will do.
83+
The changes should trigger an update in-place for the existing "stackit_network_area" where the deprecated fields will be removed and the resource "stackit_network_area_region" should be imported.
84+
It shouldn't trigger any recreation. If terraform wants to recreate any of the resources, verify that you are using the provider version > v0.78.1 and have everything defined correctly.
85+
86+
When everything looks good, run `$ terraform apply` to apply these changes.
87+
When the run is completed, you can remove the import-block. Run `$ terraform plan` to verify that the infrastructure matches the configuration.
88+
89+
{{ .SchemaMarkdown | trimspace }}

0 commit comments

Comments
 (0)