tf_provider/internal/provider/README.md

Internal Provider — Code-level Index & Developer Guide

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 🔧

1. Resource lifecycle methods follow Terraform SDK conventions: Metadata, Schema, Configure, Create, Read, Update, Delete, ImportState.
2. 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).
3. Operation polling:
   • Each resource implements waitForOperationAndInstanceStatus style helpers (e.g., VM uses specialized waitForVMOperationAndInstanceStatus) that poll Deck API for operation completion using GetInstanceOperation / GetInstanceState.
4. Parameter submission:
   • Before Create, resources collect a model (e.g., VMResourceModel) and call submitVMOperationParams / submitOperationParams which uses instanceOperationCfsParams mapping to Deck's svcOperationCfsParamId.
5. 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) ⚙️

1. Build the provider binary:

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

2. 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)

3. Run an example config:

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

4. 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.