Proposal: Terraform provider for Open Cloud Datacenter (DC-API)

[sameera-87]

Summary

This proposes introducing a Terraform provider for the Open Cloud datacenter platform (DC-API). The provider lets operators declaratively provision and manage DC-API resources — tenants and projects, virtual machines and clusters, networking, and security policies — through Terraform instead of imperative CLI calls, with the full plan/apply, state, and dependency-graph behavior Terraform users expect.

Most of the resource set is implemented and working against a local DC-API server. First, I'd like alignment on a few design and distribution decisions so the code lands in a shape the maintainers are happy to own long-term.

Motivation

Today, provisioning DC-API resources is done imperatively (via dcctl / direct REST calls). That works, but it leaves operators without:

• declarative, version-controlled infrastructure definitions,
• a plan step to preview changes before applying them,
• automatic dependency ordering between related resources,
• drift detection against the real platform state.

A Terraform provider gives all of that for free, because Terraform Core owns the dependency graph, the state file, and the plan/apply lifecycle. The provider itself stays stateless — it just translates individual CRUD instructions into DC-API calls. This is the standard model for cloud providers (AWS, Azure, GCP), and DC-API's resource hierarchy maps onto it cleanly.

Resources and status

The full resource hierarchy is below, with each resource labeled by status. 14 of the 19 resources are implemented; the remaining 5 are planned for follow-up PRs.

Tenant                              [implemented]
├── ServiceAccount                  [implemented]
├── TenantMember                    [planned]
└── Project                         [implemented]
    ├── Cluster                     [implemented]
    │   └── NodePool                [implemented]
    ├── VNet                        [implemented]
    │   ├── Subnet                  [implemented]
    │   │   ├── VirtualMachine      [implemented]
    │   │   └── PrivateEndpoint     [planned]
    │   ├── RouteTable              [implemented]
    │   │   └── RouteTableAssociation   [implemented]
    │   ├── NetworkSecurityGroup    [implemented]
    │   │   └── NSGAttachment       [implemented]
    │   ├── VNetPeering             [implemented]
    │   └── Bastion                 [implemented]
    ├── KeyVault                    [planned]
    └── PrivateDnsZone              [planned]
        └── DnsRecord               [planned]

Legend: [implemented] = managed today; [planned] = not yet, scheduled for a later PR.

All implemented resources support the full CRUD lifecycle (create, read, update, delete) plus import, and are validated against a local DC-API server started via make run.

Usage example

terraform {
  required_providers {
    dcapi = {
      source  = "registry.terraform.io/wso2/dcapi"
      version = "~> 0.1.0"
    }
  }
}
provider "dcapi" {}
resource "dcapi_project" "example" {

tenant_id  = "my-org"

project_id = "my-project"
name        = "Infrastructure Team"

description = "Core infrastructure resources: VNets, clusters, and shared VMs."
cpu_cores  = 20

memory_gb  = 64

storage_gb = 500
max_vnets      = 5

max_clusters   = 2

max_volumes    = 20

max_public_ips = 3

}
resource "dcapi_vnet" "example" {

tenant_id  = dcapi_project.example.tenant_id

project_id = dcapi_project.example.project_id
name          = "prod-vpc"

address_space = ["10.1.0.0/16"]

region        = "lk"

description   = "Production VPC"

}
resource "dcapi_subnet" "app" {

tenant_id  = dcapi_vnet.example.tenant_id

project_id = dcapi_vnet.example.project_id

vnet_id    = dcapi_vnet.example.vnet_uuid
name        = "app-subnet"

cidr        = "10.1.1.0/24"

description = "Application tier subnet"

}
resource "dcapi_virtual_machine" "web" {

tenant_id  = dcapi_subnet.app.tenant_id

project_id = dcapi_subnet.app.project_id
name       = "web-01"

size       = "medium"

image_name = "rancher-infra/ubuntu-22-04"
vnet_id   = dcapi_subnet.app.vnet_id

subnet_id = dcapi_subnet.app.subnet_uuid

}

Note the use of attribute references (dcapi_project.example.tenant_id) rather than hardcoded IDs — this is what lets Terraform Core infer the implicit dependency ordering and tear resources down in the correct reverse order.

Design decisions I'd like feedback on

Asynchronous resource lifecycle (202 + poll)

DC-API returns HTTP 202 Accepted on create and processes the work asynchronously. The provider polls the resource until it reaches a known ready state. Failure handling is deliberately conservative: only known terminal-failure statuses are treated as errors; unknown or intermediate statuses mean "keep polling." d.SetId() is set only after the resource is confirmed created, so a polling failure produces a clean failure rather than a tainted resource left in state.

Deletes follow the same shape where the API is async: poll until the resource returns 404, and treat 404 as success (already gone). VNet deletes return 409 while child subnets still exist, which surfaces as an actionable error.

Authentication model

The provider resolves credentials at runtime via a chain rather than storing them:

1. explicit value in the provider block, then
2. the DCAPI_TOKEN environment variable, then
3. reading the dcctl credentials file directly.

The endpoint comes from DCAPI_ENDPOINT. The principle here is resolve, don't duplicate — the provider never becomes a second store of long-lived secrets. I'd welcome scrutiny on this, since auth is the part of any provider that most deserves it.

Resource IDs and state

Parent IDs (e.g. tenant_id, project_id) are persisted into state so that downstream attribute references resolve correctly and the dependency graph behaves as expected. Resource IDs map to the DC-API server-assigned identifiers.

Compatibility and distribution

Item	Value
Provider source address	registry.terraform.io/wso2/dcapi
Resource naming	dcapi_<resource> (e.g. dcapi_vnet)
Supported Terraform versions	>= 1.0
Go version (to build from source)	>= 1.25
Initial release	0.1.0

Local development uses dev_overrides in ~/.terraformrc pointing at a locally compiled binary; this is dev-only and bypasses the registry.

What this proposal intentionally does not include

These resources are planned but not in the initial implementation, to keep the first contribution reviewable:

• dcapi_private_dns_zone
• dcapi_dns_record
• dcapi_key_vault
• dcapi_private_endpoint
• dcapi_tenant_member

They'll follow in subsequent PRs once the core hierarchy is merged.

Proposed conclusion

Adopt the provider as described: release the implemented resource set (14 of the 19 resources) as 0.1.0, with the asynchronous 202-and-poll lifecycle, the runtime credential-resolution chain, and consistent parent-ID and state handling covered above. The five deferred resources follow in subsequent PRs once the core hierarchy is merged.

If the design here looks right, my next step is to open a draft PR for review. Happy to split it into smaller PRs if maintainers prefer.