# fpt-corp/terraform-provider-fptcloud architecture

> Architecture diagram of the GitHub repository fpt-corp/terraform-provider-fptcloud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fpt-corp/terraform-provider-fptcloud
- Repository: https://github.com/fpt-corp/terraform-provider-fptcloud

## Overview

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: [`fptcloud/provider.go`](https://github.com/fpt-corp/terraform-provider-fptcloud/blob/master/fptcloud/provider.go) (Provider), [`commons/client.go`](https://github.com/fpt-corp/terraform-provider-fptcloud/blob/master/commons/client.go) (API client), [`fptcloud/vpc`](https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/vpc) (VPC), [`fptcloud/subnet`](https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/subnet) (Subnet)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["main.go<br/>entrypoint<br/>[main.go]"]
  node_provider["Provider<br/>terraform integration<br/>[provider.go]"]
  node_provider_tf6["TF6 compat<br/>compat layer<br/>[provider_tf6.go]"]
end

subgraph group_shared["Shared Core"]
  node_commons_client["API client<br/>http client<br/>[client.go]"]
  node_commons_data_list["List utils<br/>list normalization"]
  node_commons_errors["Errors<br/>[errors.go]"]
end

subgraph group_domains["Provider Domains"]
  node_vpc["VPC<br/>network domain"]
  node_subnet["Subnet<br/>network domain"]
  node_compute["Compute"]
  node_storage["Storage"]
  node_object_storage["Object storage"]
  node_lbv2["Load balancer v2<br/>lb domain"]
  node_k8s["Kubernetes"]
  node_database["Database"]
  node_tagging["Tagging<br/>metadata domain"]
end

subgraph group_delivery["Delivery"]
  node_docs["Docs"]
  node_examples["Examples"]
  node_ci["CI / release<br/>automation<br/>[workflows]"]
end

node_main -->|"bootstraps"| node_provider
node_provider -->|"compat"| node_provider_tf6
node_provider -->|"uses"| node_commons_client
node_provider -->|"registers"| node_vpc
node_provider -->|"registers"| node_subnet
node_provider -->|"registers"| node_compute
node_provider -->|"registers"| node_storage
node_provider -->|"registers"| node_object_storage
node_provider -->|"registers"| node_lbv2
node_provider -->|"registers"| node_k8s
node_provider -->|"registers"| node_database
node_provider -->|"registers"| node_tagging
node_vpc -->|"calls"| node_commons_client
node_subnet -->|"calls"| node_commons_client
node_compute -->|"calls"| node_commons_client
node_storage -->|"calls"| node_commons_client
node_object_storage -->|"calls"| node_commons_client
node_lbv2 -->|"calls"| node_commons_client
node_k8s -->|"calls"| node_commons_client
node_database -->|"calls"| node_commons_client
node_tagging -->|"calls"| node_commons_client
node_vpc -->|"normalizes"| node_commons_data_list
node_subnet -->|"normalizes"| node_commons_data_list
node_compute -->|"raises"| node_commons_errors
node_lbv2 -->|"raises"| node_commons_errors
node_docs -->|"mirrors"| node_examples
node_ci -->|"validates"| node_provider
node_ci -->|"checks"| node_docs

click node_main "https://github.com/fpt-corp/terraform-provider-fptcloud/blob/master/main.go"
click node_provider "https://github.com/fpt-corp/terraform-provider-fptcloud/blob/master/fptcloud/provider.go"
click node_provider_tf6 "https://github.com/fpt-corp/terraform-provider-fptcloud/blob/master/fptcloud/provider_tf6.go"
click node_commons_client "https://github.com/fpt-corp/terraform-provider-fptcloud/blob/master/commons/client.go"
click node_commons_data_list "https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/commons/data-list"
click node_commons_errors "https://github.com/fpt-corp/terraform-provider-fptcloud/blob/master/commons/errors.go"
click node_vpc "https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/vpc"
click node_subnet "https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/subnet"
click node_compute "https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/instance"
click node_storage "https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/storage"
click node_object_storage "https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/object-storage"
click node_lbv2 "https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/load_balancer_v2"
click node_k8s "https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/dfke"
click node_database "https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/database"
click node_tagging "https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/tagging"
click node_docs "https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/docs"
click node_examples "https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/examples"
click node_ci "https://github.com/fpt-corp/terraform-provider-fptcloud/blob/master/.github/workflows"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_provider,node_provider_tf6 toneBlue
class node_commons_client,node_commons_data_list,node_commons_errors toneAmber
class node_vpc,node_subnet,node_compute,node_storage,node_object_storage,node_lbv2,node_k8s,node_database,node_tagging toneMint
class node_docs,node_examples,node_ci toneRose
```

## Components

### Runtime

Terraform provider bootstrap and integration boundary.

- [main.go](https://github.com/fpt-corp/terraform-provider-fptcloud/blob/master/main.go): entrypoint · Provider executable entrypoint. · `main.go`
- [Provider](https://github.com/fpt-corp/terraform-provider-fptcloud/blob/master/fptcloud/provider.go): terraform integration · Terraform provider wiring and TF6 compatibility boundary. · `fptcloud/provider.go`
- [TF6 compat](https://github.com/fpt-corp/terraform-provider-fptcloud/blob/master/fptcloud/provider_tf6.go): compat layer · Terraform framework compatibility support. · `fptcloud/provider_tf6.go`

### Shared Core

Cross-cutting API/client and utility code used by all domains.

- [API client](https://github.com/fpt-corp/terraform-provider-fptcloud/blob/master/commons/client.go): http client · Shared client and API path helpers for Fptcloud requests. · `commons/client.go`
- [List utils](https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/commons/data-list): list normalization · Filtering, sorting, schema, and value helpers for list-style APIs. · `commons/data-list`
- [Errors](https://github.com/fpt-corp/terraform-provider-fptcloud/blob/master/commons/errors.go): shared errors · Common error types and handling helpers. · `commons/errors.go`

### Provider Domains

Major Fptcloud product areas implemented as domain packages.

- [VPC](https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/vpc): network domain · Virtual network resources, data sources, schemas, and service boundary. · `fptcloud/vpc`
- [Subnet](https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/subnet): network domain · Subnet resources and lookups. · `fptcloud/subnet`
- [Compute](https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/instance): compute domain · Instances, images, flavors, floating IPs, instance groups, SSH keys, and security groups. · `fptcloud/instance`
- [Storage](https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/storage): block storage domain · Block storage and storage policy APIs. · `fptcloud/storage`
- [Object storage](https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/object-storage): object storage domain · Bucket, ACL, lifecycle, CORS, versioning, sub-user, and access-key management. · `fptcloud/object-storage`
- [Load balancer v2](https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/load_balancer_v2): lb domain · Load balancer, listener, pool, certificate, L7 policy, and rule management. · `fptcloud/load_balancer_v2`
- [Kubernetes](https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/dfke): kubernetes domain · DFKE and MFKE resources, state, tenancy, defaults, and validation flows. · `fptcloud/dfke`
- [Database](https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/database): database domain · Database resources and flavor lookups. · `fptcloud/database`
- [Tagging](https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/fptcloud/tagging): metadata domain · Tagging resources and dependency handling. · `fptcloud/tagging`

### Delivery

Documentation, examples, and CI/release automation.

- [Docs](https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/docs): generated docs · Terraform-facing resource and data-source documentation. · `docs`
- [Examples](https://github.com/fpt-corp/terraform-provider-fptcloud/tree/master/examples): usage examples · One example directory per resource and data source. · `examples`
- [CI / release](https://github.com/fpt-corp/terraform-provider-fptcloud/blob/master/.github/workflows): automation · GitHub Actions, GoReleaser, linting, and release automation. · `.github/workflows`

## Connections

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