Skip to content

Commit 232fb16

Browse files
h3adexh3adex
committed
feat: implement advanced search options for images
1 parent 4b670ee commit 232fb16

9 files changed

Lines changed: 927 additions & 55 deletions

File tree

‎docs/data-sources/image.md‎

Lines changed: 80 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,29 +4,95 @@ page_title: "stackit_image Data Source - stackit"
44
subcategory: ""
55
description: |-
66
Image datasource schema. Must have a region specified in the provider configuration.
7+
~> Important: When using the name, name_regex, or filter attributes to select images dynamically, be aware that image IDs may change frequently. Each OS patch or update results in a new unique image ID. If this data source is used to populate fields like boot_volume.source_id in a server resource, it may cause Terraform to detect changes and recreate the associated resource.
8+
To avoid unintended updates or resource replacements:
9+
Prefer using a static image_id to pin a specific image version.If you accept automatic image updates but wish to suppress resource changes, use a lifecycle block to ignore relevant changes. For example:
10+
11+
resource "stackit_server" "example" {
12+
boot_volume = {
13+
size = 64
14+
source_type = "image"
15+
source_id = data.stackit_image.latest.id
16+
}
17+
18+
lifecycle {
19+
ignore_changes = [boot_volume[0].source_id]
20+
}
21+
}
722
---
823

924
# stackit_image (Data Source)
1025

1126
Image datasource schema. Must have a `region` specified in the provider configuration.
1227

28+
~> Important: When using the `name`, `name_regex`, or `filter` attributes to select images dynamically, be aware that image IDs may change frequently. Each OS patch or update results in a new unique image ID. If this data source is used to populate fields like `boot_volume.source_id` in a server resource, it may cause Terraform to detect changes and recreate the associated resource.
29+
30+
To avoid unintended updates or resource replacements:
31+
- Prefer using a static `image_id` to pin a specific image version.
32+
- If you accept automatic image updates but wish to suppress resource changes, use a `lifecycle` block to ignore relevant changes. For example:
33+
34+
```hcl
35+
resource "stackit_server" "example" {
36+
boot_volume = {
37+
size = 64
38+
source_type = "image"
39+
source_id = data.stackit_image.latest.id
40+
}
41+
42+
lifecycle {
43+
ignore_changes = [boot_volume[0].source_id]
44+
}
45+
}
46+
```
47+
1348
## Example Usage
1449

1550
```terraform
16-
data "stackit_image" "example" {
51+
data "stackit_image" "default" {
1752
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
1853
image_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
1954
}
55+
56+
data "stackit_image" "name_match" {
57+
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
58+
name = "Ubuntu 22.04"
59+
}
60+
61+
data "stackit_image" "name_regex_latest" {
62+
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
63+
name_regex = "^Ubuntu .*"
64+
}
65+
66+
data "stackit_image" "name_regex_oldest" {
67+
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
68+
name_regex = "^Ubuntu .*"
69+
sort_ascending = true
70+
}
71+
72+
data "stackit_image" "filter_distro_version" {
73+
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
74+
filter = {
75+
distro = "debian"
76+
version = "11"
77+
}
78+
}
2079
```
2180

2281
<!-- schema generated by tfplugindocs -->
2382
## Schema
2483

2584
### Required
2685

27-
- `image_id` (String) The image ID.
2886
- `project_id` (String) STACKIT project ID to which the image is associated.
2987

88+
### Optional
89+
90+
- `filter` (Attributes) Additional filtering options based on image properties. Can be used independently or in conjunction with `name` or `name_regex`. (see [below for nested schema](#nestedatt--filter))
91+
- `image_id` (String) Image ID to fetch directly
92+
- `name` (String) Exact image name to match. Optionally applies a `filter` block to further refine results in case multiple images share the same name. The first match is returned, optionally sorted by name in ascending order. Cannot be used together with `name_regex`.
93+
- `name_regex` (String) Regular expression to match against image names. Optionally applies a `filter` block to narrow down results when multiple image names match the regex. The first match is returned, optionally sorted by name in ascending order. Cannot be used together with `name`.
94+
- `sort_ascending` (Boolean) If set to `true`, images are sorted in ascending lexicographical order by image name (such as `Ubuntu 18.04`, `Ubuntu 20.04`, `Ubuntu 22.04`) before selecting the first match. Defaults to `false` (descending such as `Ubuntu 22.04`, `Ubuntu 20.04`, `Ubuntu 18.04`).
95+
3096
### Read-Only
3197

3298
- `checksum` (Attributes) Representation of an image checksum. (see [below for nested schema](#nestedatt--checksum))
@@ -36,10 +102,21 @@ data "stackit_image" "example" {
36102
- `labels` (Map of String) Labels are key-value string pairs which can be attached to a resource container
37103
- `min_disk_size` (Number) The minimum disk size of the image in GB.
38104
- `min_ram` (Number) The minimum RAM of the image in MB.
39-
- `name` (String) The name of the image.
40105
- `protected` (Boolean) Whether the image is protected.
41106
- `scope` (String) The scope of the image.
42107

108+
<a id="nestedatt--filter"></a>
109+
### Nested Schema for `filter`
110+
111+
Optional:
112+
113+
- `distro` (String) Filter images by operating system distribution. For example: `ubuntu`, `ubuntu-arm64`, `debian`, `rhel`, etc.
114+
- `os` (String) Filter images by operating system type, such as `linux` or `windows`.
115+
- `secure_boot` (Boolean) Filter images with Secure Boot support. Set to `true` to match images that support Secure Boot.
116+
- `uefi` (Boolean) Filter images based on UEFI support. Set to `true` to match images that support UEFI.
117+
- `version` (String) Filter images by OS distribution version, such as `22.04`, `11`, or `9.1`.
118+
119+
43120
<a id="nestedatt--checksum"></a>
44121
### Nested Schema for `checksum`
45122

‎docs/resources/server.md‎

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,11 @@ description: |-
77
Example Usage
88
With key pair
99
10+
data "stackit_image" "image" {
11+
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
12+
name = "Ubuntu 22.04"
13+
}
14+
1015
resource "stackit_key_pair" "keypair" {
1116
name = "example-key-pair"
1217
public_key = chomp(file("path/to/id_rsa.pub"))
@@ -17,7 +22,7 @@ description: |-
1722
boot_volume = {
1823
size = 64
1924
source_type = "image"
20-
source_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
25+
source_id = data.stackit_image.image.id
2126
}
2227
name = "example-server"
2328
machine_type = "g1.1"
@@ -28,13 +33,18 @@ description: |-
2833
2934
Boot from volume
3035
36+
data "stackit_image" "image" {
37+
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
38+
name = "Ubuntu 22.04"
39+
}
40+
3141
resource "stackit_server" "boot-from-volume" {
3242
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
3343
name = "example-server"
3444
boot_volume = {
3545
size = 64
3646
source_type = "image"
37-
source_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
47+
source_id = data.stackit_image.image.id
3848
}
3949
availability_zone = "eu01-1"
4050
machine_type = "g1.1"
@@ -44,12 +54,17 @@ description: |-
4454
4555
Boot from existing volume
4656
57+
data "stackit_image" "image" {
58+
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
59+
name = "Ubuntu 22.04"
60+
}
61+
4762
resource "stackit_volume" "example-volume" {
4863
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
4964
size = 12
5065
source = {
5166
type = "image"
52-
id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
67+
id = data.stackit_image.image.id
5368
}
5469
name = "example-volume"
5570
availability_zone = "eu01-1"
@@ -185,6 +200,11 @@ Server resource schema. Must have a region specified in the provider configurati
185200

186201
### With key pair
187202
```terraform
203+
data "stackit_image" "image" {
204+
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
205+
name = "Ubuntu 22.04"
206+
}
207+
188208
resource "stackit_key_pair" "keypair" {
189209
name = "example-key-pair"
190210
public_key = chomp(file("path/to/id_rsa.pub"))
@@ -195,7 +215,7 @@ resource "stackit_server" "user-data-from-file" {
195215
boot_volume = {
196216
size = 64
197217
source_type = "image"
198-
source_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
218+
source_id = data.stackit_image.image.id
199219
}
200220
name = "example-server"
201221
machine_type = "g1.1"
@@ -207,13 +227,18 @@ resource "stackit_server" "user-data-from-file" {
207227

208228
### Boot from volume
209229
```terraform
230+
data "stackit_image" "image" {
231+
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
232+
name = "Ubuntu 22.04"
233+
}
234+
210235
resource "stackit_server" "boot-from-volume" {
211236
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
212237
name = "example-server"
213238
boot_volume = {
214239
size = 64
215240
source_type = "image"
216-
source_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
241+
source_id = data.stackit_image.image.id
217242
}
218243
availability_zone = "eu01-1"
219244
machine_type = "g1.1"
@@ -224,12 +249,17 @@ resource "stackit_server" "boot-from-volume" {
224249

225250
### Boot from existing volume
226251
```terraform
252+
data "stackit_image" "image" {
253+
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
254+
name = "Ubuntu 22.04"
255+
}
256+
227257
resource "stackit_volume" "example-volume" {
228258
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
229259
size = 12
230260
source = {
231261
type = "image"
232-
id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
262+
id = data.stackit_image.image.id
233263
}
234264
name = "example-volume"
235265
availability_zone = "eu01-1"

‎examples/data-sources/stackit_image/data-source.tf‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,28 @@
1-
data "stackit_image" "example" {
1+
data "stackit_image" "default" {
22
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
33
image_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
44
}
5+
6+
data "stackit_image" "name_match" {
7+
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
8+
name = "Ubuntu 22.04"
9+
}
10+
11+
data "stackit_image" "name_regex_latest" {
12+
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
13+
name_regex = "^Ubuntu .*"
14+
}
15+
16+
data "stackit_image" "name_regex_oldest" {
17+
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
18+
name_regex = "^Ubuntu .*"
19+
sort_ascending = true
20+
}
21+
22+
data "stackit_image" "filter_distro_version" {
23+
project_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
24+
filter = {
25+
distro = "debian"
26+
version = "11"
27+
}
28+
}

0 commit comments

Comments
 (0)