How fpt-corp/terraform-provider-fptcloud works
1. This repository is a Go-based Terraform provider for Fptcloud. Its core role is to translate Terraform resource/data-source operations into Fptcloud API calls, and then map API responses back into Terraform state.
2. The top-level entrypoint is main.go, which bootstraps the provider defined under fptcloud/. The provider package is the central integration boundary with Terraform and is split into provider wiring plus compatibility support (provider.go, provider_tf6.go).
3. The architecture is organized by domain rather than by layer. Each major Fptcloud product area has its own package under fptcloud/, with the usual trio of concerns:
- service layer for API interaction,
- resource implementations for create/read/update/delete,
- data sources for read-only lookups,
- plus schema/model files where needed.
Examples include VPC, subnet, instance, floating IP, security group, storage, object storage, load balancer v2, Kubernetes/DFKE/MFKE, SSH, tagging, and database.
4. A shared commons/ package provides cross-cutting infrastructure used by all domains. It contains the API client, path helpers, shared errors, constants, reusable list/filter/sort utilities, and test helpers. This is the main internal boundary between provider logic and HTTP/API plumbing.
5. The data flow is consistent across domains:
Terraform config -> provider schema -> domain resource/data source -> domain service -> shared API client -> Fptcloud API.
Read paths also include response-to-model conversion and flattening back into Terraform state. List-style APIs are normalized through the commons/data-list helpers for filtering, sorting, and schema/value handling.
6. Networking and compute are split into their own provider areas. VPC, subnet, instance, floating IP, instance group, and security group/security-group-rule each live in dedicated packages, reflecting separate lifecycle boundaries in the cloud platform. Some packages expose both resources and data sources, while others are read-only or only resource-oriented.
7. Storage is represented by two distinct subsystems:
- fptcloud/storage and fptcloud/storage-policy for block/storage policy-related resources and data sources,
- fptcloud/object-storage for S3-like bucket, ACL, lifecycle, CORS, versioning, static website, sub-user, and access-key management.
These packages indicate separate API surfaces and state models.
8. The load balancer v2 area is a self-contained subsystem with resources and data sources for load balancers, listeners, pools, certificates, L7 policies, and L7 rules. It also has its own shared model/schema/service files, suggesting a more complex API shape than simpler resources.
9. Kubernetes-related functionality is split across dfke, mfke, and related storage-policy packages. These packages include resource definitions, state handling, tenancy/defaults/validation helpers, and some specialized service logic, indicating more orchestration-heavy flows than basic CRUD resources.
10. Documentation is generated and organized around Terraform surface area. docs/resources and docs/data-sources mirror the provider’s exposed objects, while examples/ contains one example directory per resource/data source. This is an important architectural clue: the repo is designed to keep implementation, documentation, and user examples aligned package-by-package.
11. Testing is layered into unit tests and acceptance tests. The README shows acceptance tests are driven against a real/local API endpoint using environment variables such as FPTCLOUD_API_URL, FPTCLOUD_REGION, FPTCLOUD_TENANT_NAME, FPTCLOUD_TOKEN, and VPC_ID. This means external API connectivity is part of the real integration path, not mocked away everywhere.
12. Build and delivery are automated through GitHub Actions, GoReleaser, and quality tooling. The repository includes workflows for tests, Sonar analysis, and release, plus standard Go linting and module management. That makes the operational boundary clear: source code is in Go, distribution is via Terraform provider release artifacts, and CI validates both code quality and provider behavior.
Main entry points: provider.go Provider · client.go API client · vpc VPC · subnet Subnet
Components 18
Runtime
Terraform provider bootstrap and integration boundary.
- main.go · Provider executable entrypoint.
main.go - Provider · Terraform provider wiring and TF6 compatibility boundary.
fptcloud/provider.go - TF6 compat · Terraform framework compatibility support.
fptcloud/provider_tf6.go
Shared Core
Cross-cutting API/client and utility code used by all domains.
- API client · Shared client and API path helpers for Fptcloud requests.
commons/client.go - List utils · Filtering, sorting, schema, and value helpers for list-style APIs.
commons/data-list - Errors · Common error types and handling helpers.
commons/errors.go
Provider Domains
Major Fptcloud product areas implemented as domain packages.
- VPC · Virtual network resources, data sources, schemas, and service boundary.
fptcloud/vpc - Subnet · Subnet resources and lookups.
fptcloud/subnet - Compute · Instances, images, flavors, floating IPs, instance groups, SSH keys, and security groups.
fptcloud/instance - Storage · Block storage and storage policy APIs.
fptcloud/storage - Object storage · Bucket, ACL, lifecycle, CORS, versioning, sub-user, and access-key management.
fptcloud/object-storage - Load balancer v2 · Load balancer, listener, pool, certificate, L7 policy, and rule management.
fptcloud/load_balancer_v2 - Kubernetes · DFKE and MFKE resources, state, tenancy, defaults, and validation flows.
fptcloud/dfke - Database · Database resources and flavor lookups.
fptcloud/database - Tagging · Tagging resources and dependency handling.
fptcloud/tagging
Delivery
Documentation, examples, and CI/release automation.
- Docs · Terraform-facing resource and data-source documentation.
docs - Examples · One example directory per resource and data source.
examples - CI / release · GitHub Actions, GoReleaser, linting, and release automation.
.github/workflows
Connections 28
- main.go → Provider: bootstraps · main.go initializes the provider package.
- Provider → TF6 compat: compat · Provider wiring delegates to TF6 compatibility support.
- Provider → API client: uses · Provider-managed resources call through the shared API client.
- Provider → VPC: registers · Provider exposes VPC resources and data sources.
- Provider → Subnet: registers · Provider exposes subnet resources and data sources.
- Provider → Compute: registers · Provider exposes compute-related domains.
- Provider → Storage: registers · Provider exposes block storage surface area.
- Provider → Object storage: registers · Provider exposes object storage surface area.
- Provider → Load balancer v2: registers · Provider exposes load balancer v2 resources and data sources.
- Provider → Kubernetes: registers · Provider exposes Kubernetes-related resources and data sources.
- Provider → Database: registers · Provider exposes database resources and lookups.
- Provider → Tagging: registers · Provider exposes tagging support.
- VPC → API client: calls · VPC service layer uses the shared client and API helpers.
- Subnet → API client: calls · Subnet service layer uses the shared client and API helpers.
- Compute → API client: calls · Compute domain services use the shared client.
- Storage → API client: calls · Storage service layer uses the shared client.
- Object storage → API client: calls · Object storage service layer uses the shared client.
- Load balancer v2 → API client: calls · LBv2 service layer uses the shared client.
- Kubernetes → API client: calls · Kubernetes domain services use the shared client.
- Database → API client: calls · Database services use the shared client.
- Tagging → API client: calls · Tagging service layer uses the shared client.
- VPC → List utils: normalizes · List-style data sources use shared filtering/sorting helpers.
- Subnet → List utils: normalizes · Subnet lookups rely on shared list helpers.
- Compute → Errors: raises · Domain operations map failures through shared error types.
- Load balancer v2 → Errors: raises · LBv2 operations use common error handling.
- Docs → Examples: mirrors · Documentation and examples are kept aligned with exposed Terraform objects.
- CI / release → Provider: validates · CI runs tests and release validation against provider code.
- CI / release → Docs: checks · Automation covers generated documentation and packaging.