Add support for the wait_for_completed flag to aap_job resource

Letting the user wait on aap_job resources to complete before continuing
creating aap resources. Extra parameters allow the user to tweak the
timeout and poll interval of this wait operation

Author: fincamd

docs/resources/job.md

@@ -4,6 +4,8 @@ description: |-
   Launches an AAP job.
   A job is launched only when the resource is first created or when the resource is changed. The triggers argument can be used to launch a new job based on any arbitrary value.
   This resource always creates a new job in AAP. A destroy will not delete a job created by this resource, it will only remove the resource from the state.
+  Moreover, you can set wait_for_completion to true, then Terraform will wait until this job is created and reaches any final state before continuing. This parameter works in both create and update operations.
+  You can also tweak wait_for_completion_poll_interval_seconds and wait_for_completion_timeout_seconds to control the timeout limit and poll interval.
 ---
 
 # aap_job (Resource)
@@ -14,6 +16,10 @@ A job is launched only when the resource is first created or when the resource i
 
 This resource always creates a new job in AAP. A destroy will not delete a job created by this resource, it will only remove the resource from the state.
 
+Moreover, you can set `wait_for_completion` to true, then Terraform will wait until this job is created and reaches any final state before continuing. This parameter works in both create and update operations.
+
+You can also tweak `wait_for_completion_poll_interval_seconds` and `wait_for_completion_timeout_seconds` to control the timeout limit and poll interval.
+
 -> **Note** To pass an inventory to an aap_job resource, the underlying job template *must* have been conigured to prompt for the inventory on launch.
 
 
@@ -118,6 +124,9 @@ output "job_xyz" {
 - `extra_vars` (String) Extra Variables. Must be provided as either a JSON or YAML string.
 - `inventory_id` (Number) Identifier for the inventory where job should be created in. If not provided, the job will be created in the default inventory.
 - `triggers` (Map of String) Map of arbitrary keys and values that, when changed, will trigger a creation of a new Job on AAP. Use 'terraform taint' if you want to force the creation of a new job without changing this value.
+- `wait_for_completion` (Boolean) When this is set to `true`, Terraform will wait until this aap_job resource is created, reaches any final status and then, proceeds with the following resource operation
+- `wait_for_completion_poll_interval_seconds` (Number) Sets the poll interval in seconds to wait between aap_job status updates. Default value of `5.0`
+- `wait_for_completion_timeout_seconds` (Number) Sets the maximum amount of seconds Terraform will wait before timing out the updates, and the job creation will fail. Default value of `120`
 
 ### Read-Only
 

internal/provider/job_resource.go

@@ -7,12 +7,16 @@ import (
 	"fmt"
 	"net/http"
 	"path"
+	"time"
 
 	"github.com/ansible/terraform-provider-aap/internal/provider/customtypes"
 	"github.com/hashicorp/terraform-plugin-framework/attr"
 	"github.com/hashicorp/terraform-plugin-framework/diag"
 	"github.com/hashicorp/terraform-plugin-framework/resource"
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema/booldefault"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema/float64default"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema/int64default"
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema/int64planmodifier"
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema/planmodifier"
 	"github.com/hashicorp/terraform-plugin-framework/types"
@@ -31,14 +35,17 @@ type JobAPIModel struct {
 
 // JobResourceModel maps the resource schema data.
 type JobResourceModel struct {
-	TemplateID    types.Int64                      `tfsdk:"job_template_id"`
-	Type          types.String                     `tfsdk:"job_type"`
-	URL           types.String                     `tfsdk:"url"`
-	Status        types.String                     `tfsdk:"status"`
-	InventoryID   types.Int64                      `tfsdk:"inventory_id"`
-	ExtraVars     customtypes.AAPCustomStringValue `tfsdk:"extra_vars"`
-	IgnoredFields types.List                       `tfsdk:"ignored_fields"`
-	Triggers      types.Map                        `tfsdk:"triggers"`
+	TemplateID                    types.Int64                      `tfsdk:"job_template_id"`
+	Type                          types.String                     `tfsdk:"job_type"`
+	URL                           types.String                     `tfsdk:"url"`
+	Status                        types.String                     `tfsdk:"status"`
+	InventoryID                   types.Int64                      `tfsdk:"inventory_id"`
+	ExtraVars                     customtypes.AAPCustomStringValue `tfsdk:"extra_vars"`
+	IgnoredFields                 types.List                       `tfsdk:"ignored_fields"`
+	Triggers                      types.Map                        `tfsdk:"triggers"`
+	WaitForCompletion             types.Bool                       `tfsdk:"wait_for_completion"`
+	WaitForCompletionPollInterval types.Float64                    `tfsdk:"wait_for_completion_poll_interval_seconds"`
+	WaitForCompletionTimeout      types.Int64                      `tfsdk:"wait_for_completion_timeout_seconds"`
 }
 
 // JobResource is the resource implementation.
@@ -61,6 +68,46 @@ func NewJobResource() resource.Resource {
 	return &JobResource{}
 }
 
+func waitForJobToReachAnyFinalStatus(client ProviderHTTPClient, model JobResourceModel, diagnostics diag.Diagnostics) error {
+	isFinalStatus := func(status string) bool {
+		finalStatuses := map[string]bool{
+			"new":        false,
+			"pending":    false,
+			"waiting":    false,
+			"running":    false,
+			"successful": true,
+			"failed":     true,
+			"error":      true,
+			"canceled":   true,
+		}
+		result, isPresent := finalStatuses[status]
+		return isPresent && result
+	}
+
+	pollInterval := time.Duration(model.WaitForCompletionPollInterval.ValueFloat64()) * time.Second
+	timeout := time.Duration(model.WaitForCompletionTimeout.ValueInt64()) * time.Second
+	startTime := time.Now()
+	for {
+		responseBody, err := client.Get(model.URL.ValueString())
+		diagnostics.Append(model.ParseHttpResponse(responseBody)...)
+		if err != nil {
+			return fmt.Errorf("error fetching job status: %s", err)
+		}
+
+		fmt.Printf("Job ID: %s, Current Status: %s\n", model.TemplateID, model.Status.ValueString())
+
+		if isFinalStatus(model.Status.ValueString()) {
+			return nil
+		}
+
+		if time.Since(startTime) > timeout {
+			return fmt.Errorf("polling timeout reached for job ID: %s", model.TemplateID)
+		}
+
+		time.Sleep(pollInterval)
+	}
+}
+
 // Metadata returns the resource type name.
 func (r *JobResource) Metadata(_ context.Context, req resource.MetadataRequest, resp *resource.MetadataResponse) {
 	resp.TypeName = req.ProviderTypeName + "_job"
@@ -132,14 +179,39 @@ func (r *JobResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *
 				Computed:    true,
 				Description: "The list of properties set by the user but ignored on server side.",
 			},
+			"wait_for_completion": schema.BoolAttribute{
+				Optional: true,
+				Computed: true,
+				Default:  booldefault.StaticBool(false),
+				Description: "When this is set to `true`, Terraform will wait until this aap_job resource is created, reaches " +
+					"any final status and then, proceeds with the following resource operation",
+			},
+			"wait_for_completion_poll_interval_seconds": schema.Float64Attribute{
+				Optional:    true,
+				Computed:    true,
+				Default:     float64default.StaticFloat64(5.0),
+				Description: "Sets the poll interval in seconds to wait between aap_job status updates. Default value of `5.0`",
+			},
+			"wait_for_completion_timeout_seconds": schema.Int64Attribute{
+				Optional: true,
+				Computed: true,
+				Default:  int64default.StaticInt64(120),
+				Description: "Sets the maximum amount of seconds Terraform will wait before timing out the updates, " +
+					"and the job creation will fail. Default value of `120`",
+			},
 		},
 		MarkdownDescription: "Launches an AAP job.\n\n" +
 			"A job is launched only when the resource is first created or when the " +
 			"resource is changed. The " + "`triggers`" + " argument can be used to " +
 			"launch a new job based on any arbitrary value.\n\n" +
 			"This resource always creates a new job in AAP. A destroy will not " +
 			"delete a job created by this resource, it will only remove the resource " +
-			"from the state.",
+			"from the state.\n\n" +
+			"Moreover, you can set `wait_for_completion` to true, then Terraform will " +
+			"wait until this job is created and reaches any final state before continuing. " +
+			"This parameter works in both create and update operations.\n\n" +
+			"You can also tweak `wait_for_completion_poll_interval_seconds` and " +
+			"`wait_for_completion_timeout_seconds` to control the timeout limit and poll interval.",
 	}
 }
 
@@ -157,6 +229,15 @@ func (r *JobResource) Create(ctx context.Context, req resource.CreateRequest, re
 		return
 	}
 
+	// If the job was configured to wait for completion, start polling the job status
+	// and wait for it to complete before marking the resource as created
+	if data.WaitForCompletion.ValueBool() {
+		waitForJobToReachAnyFinalStatus(r.client, data, resp.Diagnostics)
+		if resp.Diagnostics.HasError() {
+			return
+		}
+	}
+
 	// Save updated data into Terraform state
 	resp.Diagnostics.Append(resp.State.Set(ctx, &data)...)
 	if resp.Diagnostics.HasError() {
@@ -210,6 +291,15 @@ func (r *JobResource) Update(ctx context.Context, req resource.UpdateRequest, re
 		return
 	}
 
+	// If the job was configured to wait for completion, start polling the job status
+	// and wait for it to complete before marking the resource as created
+	if data.WaitForCompletion.ValueBool() {
+		waitForJobToReachAnyFinalStatus(r.client, data, resp.Diagnostics)
+		if resp.Diagnostics.HasError() {
+			return
+		}
+	}
+
 	// Save updated data into Terraform state
 	resp.Diagnostics.Append(resp.State.Set(ctx, &data)...)
 	if resp.Diagnostics.HasError() {

internal/provider/job_resource_test.go

@@ -100,6 +100,17 @@ func TestJobResourceCreateRequestBody(t *testing.T) {
 			},
 			expected: []byte(`{"inventory": 3}`),
 		},
+		{
+			name: "wait_for_completed parameters",
+			input: JobResourceModel{
+				InventoryID:                   basetypes.NewInt64Value(3),
+				TemplateID:                    types.Int64Value(1),
+				WaitForCompletion:             basetypes.NewBoolValue(true),
+				WaitForCompletionPollInterval: basetypes.NewFloat64Value(2.0),
+				WaitForCompletionTimeout:      basetypes.NewInt64Value(60),
+			},
+			expected: []byte(`{"inventory":3}`),
+		},
 	}
 
 	for _, tc := range testTable {