STACKITRCO-187 - Add option iaas API param agent

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"
  }
  ...
}
```

Signed-off-by: Adrian Nackov <adrian.nackov@mail.schwarz>

Author: aeter

docs/data-sources/server.md

@@ -34,6 +34,7 @@ data "stackit_server" "example" {
 ### Read-Only
 
 - `affinity_group` (String) The affinity group the server is assigned to.
+- `agent` (Attributes) STACKIT Server Agent as setup on the server (see [below for nested schema](#nestedatt--agent))
 - `availability_zone` (String) The availability zone of the server.
 - `boot_volume` (Attributes) The boot volume for the server (see [below for nested schema](#nestedatt--boot_volume))
 - `created_at` (String) Date-time when the server was created
@@ -48,6 +49,14 @@ data "stackit_server" "example" {
 - `updated_at` (String) Date-time when the server was updated
 - `user_data` (String) User data that is passed via cloud-init to the server.
 
+<a id="nestedatt--agent"></a>
+### Nested Schema for `agent`
+
+Read-Only:
+
+- `provisioned` (Boolean) Whether a STACKIT Server Agent is provisioned at the server
+
+
 <a id="nestedatt--boot_volume"></a>
 ### Nested Schema for `boot_volume`
 

docs/ephemeral-resources/access_token.md

@@ -404,6 +404,7 @@ import {
 ### Optional
 
 - `affinity_group` (String) The affinity group the server is assigned to.
+- `agent` (Attributes) The STACKIT Server Agent configured for the server (see [below for nested schema](#nestedatt--agent))
 - `availability_zone` (String) The availability zone of the server.
 - `boot_volume` (Attributes) The boot volume for the server (see [below for nested schema](#nestedatt--boot_volume))
 - `desired_status` (String) The desired status of the server resource. Possible values are: `active`, `inactive`, `deallocated`.
@@ -422,6 +423,14 @@ import {
 - `server_id` (String) The server ID.
 - `updated_at` (String) Date-time when the server was updated
 
+<a id="nestedatt--agent"></a>
+### Nested Schema for `agent`
+
+Optional:
+
+- `provisioned` (Boolean) Whether a STACKIT Server Agent should be provisioned at the server
+
+
 <a id="nestedatt--boot_volume"></a>
 ### Nested Schema for `boot_volume`
 

docs/resources/server.md

@@ -34,6 +34,7 @@ type DataSourceModel struct {
 	ServerId          types.String `tfsdk:"server_id"`
 	MachineType       types.String `tfsdk:"machine_type"`
 	Name              types.String `tfsdk:"name"`
+	Agent             types.Object `tfsdk:"agent"`
 	AvailabilityZone  types.String `tfsdk:"availability_zone"`
 	BootVolume        types.Object `tfsdk:"boot_volume"`
 	ImageId           types.String `tfsdk:"image_id"`
@@ -52,6 +53,10 @@ var bootVolumeDataTypes = map[string]attr.Type{
 	"delete_on_termination": basetypes.BoolType{},
 }
 
+var agentDataTypes = map[string]attr.Type{
+	"provisioned": basetypes.BoolType{},
+}
+
 // NewServerDataSource is a helper function to simplify the provider implementation.
 func NewServerDataSource() datasource.DataSource {
 	return &serverDataSource{}
@@ -123,6 +128,16 @@ func (d *serverDataSource) Schema(_ context.Context, _ datasource.SchemaRequest,
 				MarkdownDescription: "Name of the type of the machine for the server. Possible values are documented in [Virtual machine flavors](https://docs.stackit.cloud/products/compute-engine/server/basics/machine-types/)",
 				Computed:            true,
 			},
+			"agent": schema.SingleNestedAttribute{
+				Description: "STACKIT Server Agent as setup on the server",
+				Computed:    true,
+				Attributes: map[string]schema.Attribute{
+					"provisioned": schema.BoolAttribute{
+						Description: "Whether a STACKIT Server Agent is provisioned at the server",
+						Computed:    true,
+					},
+				},
+			},
 			"availability_zone": schema.StringAttribute{
 				Description: "The availability zone of the server.",
 				Computed:    true,
@@ -304,6 +319,18 @@ func mapDataSourceFields(ctx context.Context, serverResp *iaas.Server, model *Da
 		model.BootVolume = types.ObjectNull(bootVolumeDataTypes)
 	}
 
+	if serverResp.Agent != nil {
+		agent, diags := types.ObjectValue(agentDataTypes, map[string]attr.Value{
+			"provisioned": types.BoolPointerValue(serverResp.Agent.Provisioned),
+		})
+		if diags.HasError() {
+			return fmt.Errorf("failed to map agent: %w", core.DiagsToError(diags))
+		}
+		model.Agent = agent
+	} else {
+		model.Agent = types.ObjectNull(agentDataTypes)
+	}
+
 	if serverResp.UserData != nil && len(*serverResp.UserData) > 0 {
 		model.UserData = types.StringValue(string(*serverResp.UserData))
 	}

stackit/internal/services/iaas/server/datasource.go

@@ -41,6 +41,7 @@ func TestMapDataSourceFields(t *testing.T) {
 				ServerId:          types.StringValue("sid"),
 				Name:              types.StringNull(),
 				AvailabilityZone:  types.StringNull(),
+				Agent:             types.ObjectNull(agentTypes),
 				Labels:            types.MapNull(types.StringType),
 				ImageId:           types.StringNull(),
 				NetworkInterfaces: types.ListNull(types.StringType),
@@ -78,7 +79,10 @@ func TestMapDataSourceFields(t *testing.T) {
 							NicId: utils.Ptr("nic2"),
 						},
 					},
-					KeypairName:   utils.Ptr("keypair_name"),
+					KeypairName: utils.Ptr("keypair_name"),
+					Agent: &iaas.ServerAgent{
+						Provisioned: utils.Ptr(true),
+					},
 					AffinityGroup: utils.Ptr("group_id"),
 					CreatedAt:     utils.Ptr(testTimestamp()),
 					UpdatedAt:     utils.Ptr(testTimestamp()),
@@ -101,7 +105,10 @@ func TestMapDataSourceFields(t *testing.T) {
 					types.StringValue("nic1"),
 					types.StringValue("nic2"),
 				}),
-				KeypairName:   types.StringValue("keypair_name"),
+				KeypairName: types.StringValue("keypair_name"),
+				Agent: types.ObjectValueMust(agentTypes, map[string]attr.Value{
+					"provisioned": types.BoolValue(true),
+				}),
 				AffinityGroup: types.StringValue("group_id"),
 				CreatedAt:     types.StringValue(testTimestampValue),
 				UpdatedAt:     types.StringValue(testTimestampValue),
@@ -132,6 +139,7 @@ func TestMapDataSourceFields(t *testing.T) {
 				Labels:            types.MapValueMust(types.StringType, map[string]attr.Value{}),
 				ImageId:           types.StringNull(),
 				NetworkInterfaces: types.ListNull(types.StringType),
+				Agent:             types.ObjectNull(agentTypes),
 				KeypairName:       types.StringNull(),
 				AffinityGroup:     types.StringNull(),
 				UserData:          types.StringNull(),

stackit/internal/services/iaas/server/datasource_test.go

@@ -61,6 +61,7 @@ type Model struct {
 	ServerId          types.String `tfsdk:"server_id"`
 	MachineType       types.String `tfsdk:"machine_type"`
 	Name              types.String `tfsdk:"name"`
+	Agent             types.Object `tfsdk:"agent"`
 	AvailabilityZone  types.String `tfsdk:"availability_zone"`
 	BootVolume        types.Object `tfsdk:"boot_volume"`
 	ImageId           types.String `tfsdk:"image_id"`
@@ -75,6 +76,11 @@ type Model struct {
 	DesiredStatus     types.String `tfsdk:"desired_status"`
 }
 
+// Struct corresponding to Model.Agent
+type agentModel struct {
+	Provisioned types.Bool `tfsdk:"provisioned"`
+}
+
 // Struct corresponding to Model.BootVolume
 type bootVolumeModel struct {
 	Id                  types.String `tfsdk:"id"`
@@ -95,6 +101,11 @@ var bootVolumeTypes = map[string]attr.Type{
 	"id":                    basetypes.StringType{},
 }
 
+// Types corresponding to agentModel
+var agentTypes = map[string]attr.Type{
+	"provisioned": basetypes.BoolType{},
+}
+
 // NewServerResource is a helper function to simplify the provider implementation.
 func NewServerResource() resource.Resource {
 	return &serverResource{}
@@ -163,6 +174,14 @@ func (r *serverResource) ValidateConfig(ctx context.Context, req resource.Valida
 		}
 	}
 
+	var agent = &agentModel{}
+	if !(model.Agent.IsNull() || model.Agent.IsUnknown()) {
+		diags := model.Agent.As(ctx, agent, basetypes.ObjectAsOptions{})
+		if diags.HasError() {
+			return
+		}
+	}
+
 	if model.NetworkInterfaces.IsNull() || model.NetworkInterfaces.IsUnknown() || len(model.NetworkInterfaces.Elements()) < 1 {
 		core.LogAndAddWarning(ctx, &resp.Diagnostics, "No network interfaces configured", "You have no network interfaces configured for this server. This will be a problem when you want to (re-)create this server. Please note that modifying the network interfaces for an existing server will result in a replacement of the resource. We will provide a clear migration path soon.")
 	}
@@ -273,6 +292,23 @@ func (r *serverResource) Schema(_ context.Context, _ resource.SchemaRequest, res
 				Optional: true,
 				Computed: true,
 			},
+			"agent": schema.SingleNestedAttribute{
+				Description: "The STACKIT Server Agent configured for the server",
+				Optional:    true,
+				PlanModifiers: []planmodifier.Object{
+					objectplanmodifier.RequiresReplace(),
+				},
+				Attributes: map[string]schema.Attribute{
+					"provisioned": schema.BoolAttribute{
+						Description: "Whether a STACKIT Server Agent should be provisioned at the server",
+						Optional:    true,
+						Computed:    true,
+						PlanModifiers: []planmodifier.Bool{
+							boolplanmodifier.RequiresReplace(),
+						},
+					},
+				},
+			},
 			"boot_volume": schema.SingleNestedAttribute{
 				Description: "The boot volume for the server",
 				Optional:    true,
@@ -962,6 +998,26 @@ func mapFields(ctx context.Context, serverResp *iaas.Server, model *Model, regio
 		model.NetworkInterfaces = types.ListNull(types.StringType)
 	}
 
+	if serverResp.Agent != nil {
+		// convert agent model
+		var modelAgent = &agentModel{}
+		if !(model.Agent.IsNull() || model.Agent.IsUnknown()) {
+			diags := model.Agent.As(ctx, modelAgent, basetypes.ObjectAsOptions{})
+			if diags.HasError() {
+				return fmt.Errorf("failed to map agent: %w", core.DiagsToError(diags))
+			}
+		}
+		agent, diags := types.ObjectValue(agentTypes, map[string]attr.Value{
+			"provisioned": types.BoolPointerValue(serverResp.Agent.Provisioned),
+		})
+		if diags.HasError() {
+			return fmt.Errorf("failed to map agentModel: %w", core.DiagsToError(diags))
+		}
+		model.Agent = agent
+	} else {
+		model.Agent = types.ObjectNull(agentTypes)
+	}
+
 	if serverResp.BootVolume != nil {
 		// convert boot volume model
 		var bootVolumeModel = &bootVolumeModel{}
@@ -1030,6 +1086,14 @@ func toCreatePayload(ctx context.Context, model *Model) (*iaas.CreateServerPaylo
 		}
 	}
 
+	var agent = &agentModel{}
+	if !(model.Agent.IsNull() || model.Agent.IsUnknown()) {
+		diags := model.Agent.As(ctx, agent, basetypes.ObjectAsOptions{})
+		if diags.HasError() {
+			return nil, fmt.Errorf("convert agent object to struct: %w", core.DiagsToError(diags))
+		}
+	}
+
 	labels, err := conversion.ToStringInterfaceMap(ctx, model.Labels)
 	if err != nil {
 		return nil, fmt.Errorf("converting to Go map: %w", err)
@@ -1051,6 +1115,14 @@ func toCreatePayload(ctx context.Context, model *Model) (*iaas.CreateServerPaylo
 		}
 	}
 
+	var agentPayload *iaas.ServerAgent
+	// it is set and true, adjust payload
+	if !agent.Provisioned.IsNull() && !agent.Provisioned.IsUnknown() {
+		agentPayload = &iaas.ServerAgent{
+			Provisioned: conversion.BoolValueToPointer(agent.Provisioned),
+		}
+	}
+
 	var userData *[]byte
 	if !model.UserData.IsNull() && !model.UserData.IsUnknown() {
 		src := []byte(model.UserData.ValueString())
@@ -1080,6 +1152,7 @@ func toCreatePayload(ctx context.Context, model *Model) (*iaas.CreateServerPaylo
 	return &iaas.CreateServerPayload{
 		AffinityGroup:    conversion.StringValueToPointer(model.AffinityGroup),
 		AvailabilityZone: conversion.StringValueToPointer(model.AvailabilityZone),
+		Agent:            agentPayload,
 		BootVolume:       bootVolumePayload,
 		ImageId:          conversion.StringValueToPointer(model.ImageId),
 		KeypairName:      conversion.StringValueToPointer(model.KeypairName),