tf_provider/docs/50_history/02_tubulus_stabilization.md

02. Tubulus Stabilization & The "Iron Logic" of Polling

Date: 2026-01-27 Operator: GitHub Copilot (Gemini 3 Pro) Task: Fix Tubulus Creation and Polling

The Problem

The nubes_tubulus_instance resource was unstable:

1. Timeouts: Operations would finish, but the provider kept waiting until the hard timeout.
2. Bad Requests: Valid inputs (empty maps) were rejected by the API.
3. Terraform Errors: "Provider returned invalid result object" (Unknown values) after Apply.

The Investigation (HAR Analysis)

We analyzed 14 HAR files covering various scenarios (Success, Failure, Fast, Slow). Key finding: The API has a strict contract regarding dtFinish.

• dtFinish appears exactly when the operation ends.
• Waiting for status="COMPLETED" or similar text fields is unreliable.
• isSuccessful is only valid after dtFinish is present.

The Solution

1. Refactored Polling (waitForOperationAndInstanceStatus):

   • Implemented strict check: If dtFinish != nil, stop waiting.
   • If isSuccessful is true -> Success. Else -> Error.
   • Removed arbitrary sleeps and secondary status checks.

2. Fixed Parameter Submission (submitOperationParams):

   • Restored logic to send "{}" for empty map/json types.
   • Added fallback mapping using SvcOperationCfsParam key.

3. Fixed Instance Reading (readInstance):

   • Added ?fields=...explainedStatus to GET request to ensure status is returned.
   • Updated InstanceResponse struct to match API wrapper {"instance": {...}}.

4. Fixed Terraform State (Create):

   • Explicitly set all Unknown computed fields to Null at the end of resource creation to satisfy Terraform's safety checks.

Outcome

Test 014 (Lifecycle Create) passed successfully in 33 seconds.

Directives for Future

• DO NOT TOUCH tubulus_resource.go polling logic. It is based on hard evidence.
• Always check dtFinish for Nubes operations.