Generated: 2026-01-27 Purpose: Quick reference for developers and Copilot agents to understand the internal Terraform provider implementation (internal/provider/). Read this file before making changes to provider code.

Overview ✨

This folder contains the implementation of the Terraform provider nubes (resources and data-sources) and the HTTP client used to interact with the Taffy/Deck API.

Primary responsibilities:

Define provider schema and configuration (provider.go).
Implement resources (*_resource.go) and data-sources (*_data_source.go).
Encapsulate HTTP interactions in client_impl.go (NubesClient) and helper types.
Implement polling/wait logic and operation submission patterns used across resources.

Files (short mapping)

provider.go — Provider factory, Metadata, Schema, and lists of Resources/DataSources.
client_impl.go — NubesClient implementation: request helpers, polling (WaitForInstanceReady, WaitForOperation), instance state retrieval, and operation submission.
edge_resource.go / edge_data_source.go — Edge Gateway resource and data-source implementations.
vm_resource.go — VM resource implementation (create/read/update/delete/import and operation waiting, waitForVMOperationAndInstanceStatus).
vapp_resource.go / vapp_data_source.go — vApp resource and data-source.
vdc_resource.go / vdc_data_source.go — vDC resource and data-source.
organization_resource.go — Organization resource implementation.
postgres_resource.go / pgadmin_resource.go — Postgres and PgAdmin resources.
s3bucket_resource.go — S3 bucket resource.
quick_start_resource.go — QuickStart resource (helper for full-stack installs).
tubulus_resource.go / tubulus_ai.go — Tubulus resource (AI integrations). Contains askGemini usage.

Key Patterns & Conventions 🔧

Resource lifecycle methods follow Terraform SDK conventions: Metadata, Schema, Configure, Create, Read, Update, Delete, ImportState.
Creation pattern:
- Submit a create operation (via NubesClient helpers) -> wait for operation state -> wait for instance readiness (if applicable) -> apply post-creation steps (VIP, DNS, FW).
Operation polling:
- Each resource implements waitForOperationAndInstanceStatus style helpers (e.g., VM uses specialized waitForVMOperationAndInstanceStatus) that poll Deck API for operation completion using GetInstanceOperation / GetInstanceState.
Parameter submission:
- Before Create, resources collect a model (e.g., VMResourceModel) and call submitVMOperationParams / submitOperationParams which uses instanceOperationCfsParams mapping to Deck's svcOperationCfsParamId.
Error handling:
- If operation stage dtFinish is null or the stage is stuck on [PROCESS], functions return a timeout/error and propagate to Terraform user.

Important Types & Functions (by file)

provider.go

New(version string) func() provider.Provider — Provider factory used by Terraform to instantiate provider.
NubesProvider (type) — implements provider hooks: Metadata, Schema, Configure.
Resources() and DataSources() — lists of registered resources and data-sources.

client_impl.go

type NubesClient struct — HTTP client wrapper; holds base URL, token provider, logger.
GetOperationId(ctx, serviceId, opName) — Resolve operation numeric ID by name.
CreateInstance(ctx, displayName, serviceId, svcOperationId, params) — Creates instance and returns UIDs.
WaitForInstanceReady, WaitForOperation — Polling helpers.
GetInstanceStateDetails, GetInstanceOperation — low-level getters for state & operation details.
Post, postInstance helpers — handle posting and optionally returning Location/ID from Location header.

vm_resource.go

NewVMResource() — resource constructor.
VMResource and VMResourceModel — model for user-specified parameters and mapping.
Create — builds request model, submits params, runs operation (watching for Firewall stage and others), and treats partial success carefully.
waitForVMOperationAndInstanceStatus — VM-specific wait logic (parses stages and handles FW timeouts).

edge_resource.go & edge_data_source.go

NewEdgeResource(), NewEdgeDataSource() — constructors.
EdgeResourceModel, readInstance, submitOperationParams, waitForOperationAndInstanceStatus — same patterns applied for Edge resource.

tubulus_resource.go & tubulus_ai.go

Integrates AI flows (Gemini) with resource flow.
askGemini — helper which calls AI integration for instruction parsing.

How to build the provider locally (developer workflow) ⚙️

Build the provider binary:

# At repo root
go build -o terraform-provider-nubes ./

Make it available to Terraform for local testing:

# Option A: plugin dir
mkdir -p ~/.terraform.d/plugins/local/terraform-provider-nubes
cp terraform-provider-nubes ~/.terraform.d/plugins/local/terraform-provider-nubes/
# Option B: use plugin-dir during init
terraform init -plugin-dir=./ (not recommended if you have mixed plugins)

Run an example config:

cd examples/quick_start
terraform init
terraform apply -var="token=<YOUR_TOKEN>" -auto-approve

Useful commands during development:

go vet, golangci-lint run (if configured), go test ./....
Use tools/har/* scripts to replay HAR-based scenarios when testing resource behavior.

Note: Examples might perform destructive operations against live environment — prefer dev account and -auto-approve only when you expect the run.

Acceptance / Integration Tests

Use tests/ scenarios to validate create/modify/delete flows.
Manual acceptance: run an example on a dev account, inspect instances and operations via Deck API.
Test idempotency: apply the same config twice and ensure plan shows no changes.

Conventions for Agents and Contributors

ALWAYS read /home/naeel/terra/REPO_CONTENTS.md and this file before making changes to provider code.
When adding a resource:
- Add a new *_resource.go and a *_data_source.go if discovery is required.
- Implement Create / Read / Update / Delete / import if supported.
- Add tests in tests/ and examples in examples/.

Next steps I can take ✅

Generate a function-level index (per-file exported functions and short signatures) as a machine-readable YAML/JSON for other agents.
Add internal/provider/DEVELOPMENT.md with a checklist and make targets for build and acceptance test steps.

If you want the function-level JSON index and a DEVELOPMENT.md, say "code-level" and I'll create them and commit to the repo.