STACKITRCO-187 - Add option iaas API param agent

[aeter]

Adds a terraform stackit_server option for the iaas ( create server ) API param: "agent": {"provisioned": true}

ref STACKITRCO-187

ref: stackitcloud/stackit-cli#1213

---

Tests:

• ran make fmt, make generate-docs

• ran unit tests

[~/terraform-provider-stackit] go test stackit/internal/services/iaas/server/*
ok      command-line-arguments  15.005s
[~/terraform-provider-stackit] make test
...
ok      github.com/stackitcloud/terraform-provider-stackit/stackit/internal/services/iaas/server       15.006s  coverage: 33.0% of statements
...
[~/terraform-provider-stackit]

• Tested: with a locally-configured terraform - tested by adding, changing, deleting agent-related parts of the below main.tf ** Tested without providing agent inside main.tf (the result had "agent" = null /* object */)

** Tested with setting agent = { provisioning = true } (and then ran the stackit-cli command for checking if the agent was created successfully and able to run commands, stackit -y server command create --server-id=3fdac6ea-3885-441c-b473-bc94ca570ca8 --project-id=c904f41c-2f8c-4edb-b966-e87d65f10b64 --template-name=RunShellScript --params script='echo hello').

** Tested when setting agent = { provisioning = true } and then set it to false - verified the server was deleted and recreated again with the new value.

[~] cat main.tf
provider "stackit" {
  # Configuration options
  service_account_key_path = "/home/debian/terraform_dev/.terraform_key.json"
  default_region = "eu01"
}

resource "stackit_network_interface" "server_nic" {
  project_id = "c904f41c-2f8c-4edb-b966-e87d65f10b64"
  network_id = "97c5dde4-cb9d-49b8-be55-9cdf0c3795e1"
}

resource "stackit_server" "myserver1" {
    project_id = "c904f41c-2f8c-4edb-b966-e87d65f10b64"
    name = "terraformtestserver1"
    boot_volume = {
        size = 64
        source_type = "image"
        source_id = "21466190-b904-4267-8bf3-1be4323f4ffb"
        delete_on_termination = true
    }
    availability_zone = "eu01-1"
    agent = {
        provisioned = true
    }
    machine_type = "t1.1"
    network_interfaces = [ stackit_network_interface.server_nic.network_interface_id ]
}

data "stackit_server" "myserver1_data" {
   project_id = "c904f41c-2f8c-4edb-b966-e87d65f10b64"
   server_id  = stackit_server.myserver1.server_id
}

output "server_info_from_data" {
  value = data.stackit_server.myserver1_data
}

[~] terraform apply -auto-approve  ## this is without `agent` set in the config
...
server_info_from_data = {
  "affinity_group" = tostring(null)
  "agent" = null /* object */
  "availability_zone" = "eu01-1"
  ...
}
...

[~] terraform apply -auto-approve  ## this is with `agent = { provisioned = true }` set in the config
...
server_info_from_data = {
  "affinity_group" = tostring(null)
  "agent" = {
    "provisioned" = true
  }
  "availability_zone" = "eu01-1"
  "boot_volume" = {
    "delete_on_termination" = true
    "id" = "673021e5-2a90-4482-8ffa-e0485c7588bd"
  }
  ...
}

Description

relates to STACKITRCO-187

Checklist

• Issue was linked above
• Code format was applied: make fmt
• Examples were added / adjusted (see examples/ directory)
• Docs are up-to-date: make generate-docs (will be checked by CI)
• Unit tests got implemented or updated
• Acceptance tests got implemented or updated (see e.g. here)
• Unit tests are passing: make test (will be checked by CI)
• No linter issues: make lint (will be checked by CI)

[github-actions]

This PR was marked as stale after 7 days of inactivity and will be closed after another 7 days of further inactivity. If this PR should be kept open, just add a comment, remove the stale label or push new commits to it.

[cgoetz-inovex]

lgtm besides the docs

[rubenhoenle]

The acceptance tests don't include your new field yet:

https://github.com/stackitcloud/terraform-provider-stackit/blob/44312a8ebc5b9da9af0608d845b2b733ea349851/stackit/internal/services/iaas/testdata/resource-volume-max.tf

https://github.com/stackitcloud/terraform-provider-stackit/blob/44312a8ebc5b9da9af0608d845b2b733ea349851/stackit/internal/services/iaas/iaas_acc_test.go

Could you also adjust them please?

[aeter]

I cannot run the acceptance tests (if I do, it probably costs money). I did not want to add code to files I cannot test.
If this is a strong requirement for this PR, how can I do this?

[rubenhoenle]

Yes it is, we won't accept this without properly adjusted Acc tests.

[rubenhoenle]

Since you're working at STACKIT it shouldn't be a problem for you I hope? 😅

[aeter]

It seems like you should be using go-vcr or similar for such integration tests - recording/hardcoding API responses. The way they are written right now - it seems like they belong to an internal CI server, maybe even at the repo of a QA team. stackit-cli doesn't have them. The tests themselves and surely are useful - but how can you ask open source contributors to run them? How much does a sample run cost?

[aeter]

Once you have reached an agreement of a right implementation, I'll update/run the acceptance tests and update the PR.

[rubenhoenle]

Here's what the API docs say about the "provisioned" server agent field: https://docs.api.stackit.cloud/documentation/iaas/version/v2#tag/Servers/operation/v2CreateServer

When false the agent IS NOT installed. When true the agent IS installed. When its not set the result depend on the used image and its default provisioning setting.

Since this is not trivial to solve, we as the STACKIT Developer Tools team decided that the default value for the "provisioned" field should be false. Could you please adjust your implementation to respect that decision? 😅

[aeter]

To be sure I understand it right:

• By the previous code, so far, the param always has defaulted to null. (I think) I keep it as it has always been. Like - don't send any agent-related param to the API.
• Currently (by my code) the param has 3 states: null, false, true. Default remains null.

It seems like you want to be even more explicit - and to always default the param to false, without a null state (thus - to not use any image default agent provisioning) .
OK. I'll update the code (cannot do it today, I also need to re-test it all).

[rubenhoenle]

@btotev-schwarz We decided to use a default value (false) as the Developer Tools team and maintainers of this Terraform provider for the following reason: The API in it's current state is not declarative-friendly.

If one decides to not send a "provisioned" flag for a server POST request, the "provisioned" flag in the response can either be true or false in the response, but you can't know beforehand. This is not at all compatible with declarative tools like Terraform IMO. Making this work in Terraform will always require some kind of workarounds and I'm not willing to accept this.

• agent provisioning property is read only, so if you change it, the server need to be recreated (RequiresReplace)

Don't mix up read-only fields and fields marked as RequiresReplace. agent.provisioned can't be read-only because the user has to be able to set a value for it in his Terraform configuration. But it has to be marked as RequiresReplace because the server update endpoint doesn't allow updating the "provisioned" flag of an existing server.

[aeter]

I'm sorry, you'll think I'm stubborn to continue the discussion and propose some technical solution. I know my code in the PR needs adjustments. I know the IaaS API itself probably could use a better design for this parameter (to use strings, like "yes", "no", "image-default" instead of a bool). I'll follow whatever you guys decide (product owners, terraform team).

A small question: is the below solution (keeping the current API model) harder to maintain for the team and harder/unintuitive for the users? Sorry from taking your time with it.

 // If the user omits "agent" and the API returns nothing, Terraform sees null in the config and null in the state. No changes are detected.
// If the API returns {"provisioned": true}, UseStateForUnknown() will copy that object into the plan. Terraform will respect the API's default.
    return schema.Schema{
        Attributes: map[string]schema.Attribute{
            "agent": schema.SingleNestedAttribute{
                // allow user to omit it, or API to set it.
                Optional: true,
                Computed: true,
                
                // If user omits it, keep the old value
                PlanModifiers: []planmodifier.Object{
                    objectplanmodifier.UseStateForUnknown(),
                },

                Attributes: map[string]schema.Attribute{
                    "provisioned": schema.BoolAttribute{
                        Optional: true, // Can be set 
                        Computed: true, // But the API might fill it too.
                        
                        // If user changes this value, force recreation (Immutable behavior)
                        PlanModifiers: []planmodifier.Bool{
                            boolplanmodifier.RequiresReplace(),
                        },
                    },
                },
            },
        },
    } 

It seems the "provisioned" flag is not returned from the API at all when the agent: provisioned: ... was not set during image creation. The above will work whether nothing is returned or true/false is returned.

[~/stackit-cli] stackit curl -X GET -H "Content-Type: application/json" https://iaas.api.stackit.cloud/v
2/projects/c904f41c-2f8c-4edb-b966-e87d65f10b64/regions/eu01/servers/5c013c9e-edc0-49a0-ba11-3c971f113bd
5
{
  "availabilityZone": "eu01-m",
  "bootVolume": {
    "deleteOnTermination": true,
    "id": "8af61d89-41cc-49cb-946c-bc75e0cb74c6"
  },
  "createdAt": "2026-01-22T10:30:10Z",
  "id": "5c013c9e-edc0-49a0-ba11-3c971f113bd5",
  "labels": {},
  "launchedAt": "2026-01-22T10:31:37Z",
  "machineType": "t1.1",
  "metadata": {},
  "name": "test2",
  "powerStatus": "RUNNING",
  "status": "ACTIVE",
  "updatedAt": "2026-01-22T10:31:37Z",
  "volumes": [
    "8af61d89-41cc-49cb-946c-bc75e0cb74c6"
  ]
}

If you're interested, I can provide further testing with creating a resource with the current code and modifying it (true/false/missing). Sorry for the interruption.

[rubenhoenle]

Is UseStateForUnknown() a workaround or officially supported plan modifier for such cases (https://developer.hashicorp.com/terraform/plugin/framework/resources/plan-modification#usestateforunknown)?

Of course UseStateForUnknown()is a officially supported plan modifier, that's not up for discussion. But in this case I consider using it a workaround, because it wouldn't be needed at all with a declarative-friendly API design. We have decided that we as the Developer Tools team don't have the capacity at the moment to handle such API design failures somehow in our products.

Only because an API design works for the portal, that doesn't mean we have to stick with the same behavior in the Developer Tools (Terraform provider, CLI, ...). The portal isn't a declarative IaC tool which keeps a state, the Terraform provider is. This is why I also don't count in the argument that every touchpoint should integrate this feature the same way - that's only possible if the API matches the requirements of these touchpoints. Which isn't the case here.

The question for me is not if we technically can integrate the API behavior 1:1 in the Terraform provider - of course it's possible. The question for me is if it makes sense. And that's still not the case here from my perspective.

Furthermore, I think that this would be the correct way to go in a Terraform configuration. See the example below.

data "stackit_image" "example" {
  project_id = var.project_id
  image_id   = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

resource "stackit_server" "boot-from-volume" {
  project_id = var.project_id
  name       = "example-server"
  boot_volume = {
    size        = 64
    source_type = "image"
    source_id   = stackit_image.example.image_id
  }
  agent = {
    # This way you still have the same behavior. In a declarative manner. 
    # This can be included in the examples and users will be happy.

    # option 1
    provisioned = stackit_image.example.agent.provision_by_default
    # option 2
    # provisioned = stackit_image.example.agent.supported
  }
  availability_zone = "eu01-1"
  machine_type      = "g2i.1"
  keypair_name      = "example-keypair"
}