feat: back meshstack_tenant with the v4 tenant API + migration

Reimplement meshstack_tenant on the shared v4 body (platform_ref, landing_zone_ref,
platform_tenant_id, status, ref, wait_for_completion):
- v3->v4 state upgrade (SchemaVersion 1): the upgrader resolves the tenant via the list
  endpoint (Configure runs before UpgradeResourceState) and backfills uuid + refs.
- moved support from meshstack_tenant_v4 (shared body -> non-destructive).
- import accepts a tenant UUID or the legacy workspace.project.location.platform composite.
- singular data source reimplemented over TenantV4.List (composite key).
- deprecate the meshstack_tenant_v4 resource (-> meshstack_tenant + moved) and the singular
  meshstack_tenant / meshstack_tenant_v4 data sources (-> plural meshstack_tenants).
- rename the plural tenants data source's internal identifiers off the _v4 suffix (HCL name
  meshstack_tenants unchanged).

Shared the v4 body schema + state mapping between meshstack_tenant and meshstack_tenant_v4.
Adds a WithRawBlock test helper for moved-block configs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: grubmeshi

CHANGELOG.md

@@ -1,17 +1,24 @@
 # v0.24.0
 
 BREAKING CHANGES:
-- `meshstack_tenant_v4`: the tenant now references its platform and landing zone by ref instead of by identifier, aligning with other meshObject references. `spec.platform_identifier` (a string) is replaced by `spec.platform_ref` (`{uuid, kind}`) and `spec.landing_zone_identifier` (a string) by `spec.landing_zone_ref` (`{name, kind}`, where `name` is the landing zone identifier). Assign the referenced resources' computed `ref` outputs directly, e.g. `platform_ref = meshstack_platform.example.ref` and `landing_zone_ref = meshstack_landingzone.example.ref`. Both data sources expose the refs as computed outputs. Requires meshStack with the meshTenant v4 API carrying `platformRef`/`landingZoneRef`.
-
-FEATURES:
-- `meshstack_landingzone` resource and data source now expose a computed `ref` output (`{name, kind}`) suitable for use as `landing_zone_ref` in `meshstack_tenant_v4`, matching the existing `ref` outputs on other resources.
+- `meshstack_tenant` now runs on the meshTenant v4 API and the resource body changed accordingly (the move itself upgrades state in place, without recreating the tenant): `metadata.platform_identifier` → `spec.platform_ref` (`{uuid, kind}`), `spec.local_id` → `spec.platform_tenant_id`, `spec.landing_zone_identifier` → `spec.landing_zone_ref` (`{name, kind}`), `metadata.assigned_tags` → `status.tags`, and `spec.quotas` is now a set. New computed `ref`, richer `status`, and a `wait_for_completion` toggle. Import accepts either the tenant UUID or the legacy `workspace.project.location.platform` composite. Requires meshStack with the meshTenant v4 API carrying `platformRef`/`landingZoneRef`. Upgrade caveats: the automatic state upgrade queries the backend and expects exactly one active tenant for the composite (it errors otherwise); and if you previously omitted the landing zone, set `landing_zone_ref` after upgrading, because it is `RequiresReplace` — leaving it unset forces a tenant recreate.
+- `meshstack_tenant_v4`: references its platform and landing zone by ref instead of by identifier. `spec.platform_identifier` → `spec.platform_ref` (`{uuid, kind}`) and `spec.landing_zone_identifier` → `spec.landing_zone_ref` (`{name, kind}`, where `name` is the landing zone identifier). Assign the referenced resources' computed `ref` outputs directly, e.g. `platform_ref = meshstack_platform.example.ref` and `landing_zone_ref = meshstack_landingzone.example.ref`.
 
 FEATURES:
+- `meshstack_landingzone` resource and data source now expose a computed `ref` output (`{name, kind}`) suitable for use as `landing_zone_ref` in tenant resources, matching the existing `ref` outputs on other resources.
+- `meshstack_tenant` supports migrating from `meshstack_tenant_v4` with a `moved` block (both share the v4 body, so the move is non-destructive).
 - `meshstack_building_block_definition`: `version_spec.inputs` and `version_spec.outputs` now support an optional `display_order` (number) attribute that controls how inputs/outputs are arranged in meshPanel. It defaults to the already set value when omitted, or `0` if there is none.
 
 FIXES:
 - `meshstack_building_block`: A `content_hash` wired from a definition's computed `content_hash` no longer triggers a re-run when the value changed only because the hash-algorithm version changed (e.g. after upgrading the provider). Such version-only differences are now recognized and ignored, while genuine content changes still re-run. Setting an arbitrary (non-versioned) `content_hash` to force a manual re-run continues to work.
 
+DEPRECATIONS:
+- `meshstack_tenant_v4` (resource) is deprecated in favor of `meshstack_tenant`; migrate with a `moved` block. The resource stays registered for now.
+- The singular tenant data sources `meshstack_tenant` and `meshstack_tenant_v4` are deprecated in favor of the plural `meshstack_tenants` data source (which filters by workspace/project/platform).
+
+NOTES:
+- The plural tenants data source is `meshstack_tenants` (the internal `*_v4` naming was dropped; the HCL type name is unchanged).
+
 # v0.23.1
 
 FIXES:

docs/data-sources/tenant.md

@@ -4,12 +4,15 @@ page_title: "meshstack_tenant Data Source - terraform-provider-meshstack"
 subcategory: ""
 description: |-
   Single tenant by workspace, project, and platform.
+  ~> Preview: This resource is in preview. Breaking changes are possible without prior notice due to changes in the underlying meshStack preview API https://docs.meshcloud.io/api/technical-specifications#preview-endpoints or due to changes in this provider. Please ensure you are running the latest version of the provider and report any bugs via GitHub issues https://github.com/meshcloud/terraform-provider-meshstack/issues or via support@meshcloud.io.
 ---
 
 # meshstack_tenant (Data Source)
 
 Single tenant by workspace, project, and platform.
 
+~> **Preview:** This resource is in preview. Breaking changes are possible without prior notice due to changes in the underlying [meshStack preview API](https://docs.meshcloud.io/api/technical-specifications#preview-endpoints) or due to changes in this provider. Please ensure you are running the latest version of the provider and report any bugs via [GitHub issues](https://github.com/meshcloud/terraform-provider-meshstack/issues) or via support@meshcloud.io.
+
 ## Example Usage
 
 ```terraform
@@ -32,30 +35,52 @@ data "meshstack_tenant" "name" {
 ### Read-Only
 
 - `spec` (Attributes) Tenant specification. (see [below for nested schema](#nestedatt--spec))
+- `status` (Attributes) Tenant status. (see [below for nested schema](#nestedatt--status))
 
 <a id="nestedatt--metadata"></a>
 ### Nested Schema for `metadata`
 
 Required:
 
-- `owned_by_project` (String)
-- `owned_by_workspace` (String)
-- `platform_identifier` (String)
+- `owned_by_project` (String) Identifier of the project the tenant belongs to.
+- `owned_by_workspace` (String) Identifier of the workspace the tenant belongs to.
+- `platform_identifier` (String) Identifier of the target platform (`<platform>.<location>`).
 
 Read-Only:
 
-- `assigned_tags` (Map of List of String)
+- `created_on` (String)
 - `deleted_on` (String)
+- `marked_for_deletion_on` (String)
+- `uuid` (String) The unique identifier (UUID) of the tenant.
 
 
 <a id="nestedatt--spec"></a>
 ### Nested Schema for `spec`
 
 Read-Only:
 
-- `landing_zone_identifier` (String)
-- `local_id` (String)
-- `quotas` (Attributes List) (see [below for nested schema](#nestedatt--spec--quotas))
+- `landing_zone_ref` (Attributes) (see [below for nested schema](#nestedatt--spec--landing_zone_ref))
+- `platform_ref` (Attributes) (see [below for nested schema](#nestedatt--spec--platform_ref))
+- `platform_tenant_id` (String)
+- `quotas` (Attributes Set) (see [below for nested schema](#nestedatt--spec--quotas))
+
+<a id="nestedatt--spec--landing_zone_ref"></a>
+### Nested Schema for `spec.landing_zone_ref`
+
+Read-Only:
+
+- `kind` (String)
+- `name` (String)
+
+
+<a id="nestedatt--spec--platform_ref"></a>
+### Nested Schema for `spec.platform_ref`
+
+Read-Only:
+
+- `kind` (String)
+- `uuid` (String)
+
 
 <a id="nestedatt--spec--quotas"></a>
 ### Nested Schema for `spec.quotas`
@@ -64,3 +89,15 @@ Read-Only:
 
 - `key` (String)
 - `value` (Number)
+
+
+
+<a id="nestedatt--status"></a>
+### Nested Schema for `status`
+
+Read-Only:
+
+- `platform_type_identifier` (String)
+- `platform_workspace_identifier` (String)
+- `tags` (Map of List of String)
+- `tenant_name` (String)

docs/resources/tenant.md

@@ -3,26 +3,31 @@
 page_title: "meshstack_tenant Resource - terraform-provider-meshstack"
 subcategory: ""
 description: |-
-  Single tenant by workspace, project, and platform.
+  Manages a meshTenant.
+  ~> Preview: This resource is in preview. Breaking changes are possible without prior notice due to changes in the underlying meshStack preview API https://docs.meshcloud.io/api/technical-specifications#preview-endpoints or due to changes in this provider. Please ensure you are running the latest version of the provider and report any bugs via GitHub issues https://github.com/meshcloud/terraform-provider-meshstack/issues or via support@meshcloud.io.
 ---
 
 # meshstack_tenant (Resource)
 
-Single tenant by workspace, project, and platform.
+Manages a `meshTenant`.
+
+~> **Preview:** This resource is in preview. Breaking changes are possible without prior notice due to changes in the underlying [meshStack preview API](https://docs.meshcloud.io/api/technical-specifications#preview-endpoints) or due to changes in this provider. Please ensure you are running the latest version of the provider and report any bugs via [GitHub issues](https://github.com/meshcloud/terraform-provider-meshstack/issues) or via support@meshcloud.io.
 
 ## Example Usage
 
 ```terraform
 resource "meshstack_tenant" "example" {
   metadata = {
-    owned_by_workspace  = data.meshstack_workspace.example.metadata.name
-    owned_by_project    = data.meshstack_project.example.metadata.name
-    platform_identifier = data.meshstack_platform.example.identifier
+    owned_by_workspace = data.meshstack_workspace.example.metadata.name
+    owned_by_project   = data.meshstack_project.example.metadata.name
   }
 
   spec = {
-    landing_zone_identifier = data.meshstack_landingzone.example.metadata.name
+    platform_ref     = data.meshstack_platform.example.ref
+    landing_zone_ref = data.meshstack_landingzone.example.ref
   }
+
+  # wait_for_completion = true
 }
 ```
 
@@ -31,36 +36,104 @@ resource "meshstack_tenant" "example" {
 
 ### Required
 
-- `metadata` (Attributes) Tenant metadata. Workspace, project and platform of the target tenant must be set here. (see [below for nested schema](#nestedatt--metadata))
+- `metadata` (Attributes) Metadata of the tenant. The `owned_by_workspace` and `owned_by_project` attributes must be set here. (see [below for nested schema](#nestedatt--metadata))
 - `spec` (Attributes) Tenant specification. (see [below for nested schema](#nestedatt--spec))
 
+### Optional
+
+- `wait_for_completion` (Boolean) Wait for tenant creation/deletion to complete. Note that tenant creation is considered complete when `spec.platformTenantId` is set and not necessarily when replication is finished. Defaults to `true`.
+
+### Read-Only
+
+- `ref` (Attributes) Reference to this tenant, can be used as `target_ref` in building block resources. (see [below for nested schema](#nestedatt--ref))
+- `status` (Attributes) Tenant status. (see [below for nested schema](#nestedatt--status))
+
 <a id="nestedatt--metadata"></a>
 ### Nested Schema for `metadata`
 
 Required:
 
-- `owned_by_project` (String) Identifier of the project the tenant belongs to.
-- `owned_by_workspace` (String) Identifier of the workspace the tenant belongs to.
-- `platform_identifier` (String) Identifier of the target platform.
+- `owned_by_project` (String) The identifier of the project that the tenant belongs to.
+- `owned_by_workspace` (String) The identifier of the workspace that the tenant belongs to.
 
 Read-Only:
 
-- `assigned_tags` (Map of List of String) Tags assigned to this tenant originating from workspace, payment method and project.
-- `deleted_on` (String) If the tenant has been submitted for deletion by a workspace manager, the date is shown here (e.g. 2020-12-22T09:37:43Z).
+- `created_on` (String) The creation timestamp of the meshTenant (e.g. `2020-12-22T09:37:43Z`).
+- `deleted_on` (String) The deletion timestamp of the tenant (e.g. `2020-12-22T09:37:43Z`).
+- `marked_for_deletion_on` (String) The timestamp when the tenant was marked for deletion (e.g. `2020-12-22T09:37:43Z`).
+- `uuid` (String) The unique identifier (UUID) of the tenant.
 
 
 <a id="nestedatt--spec"></a>
 ### Nested Schema for `spec`
 
+Required:
+
+- `platform_ref` (Attributes) Reference to the platform this tenant belongs to, identified by its uuid. (see [below for nested schema](#nestedatt--spec--platform_ref))
+
+Optional:
+
+- `landing_zone_ref` (Attributes) Reference to the landing zone to assign to this tenant, identified by its name (the landing zone identifier). (see [below for nested schema](#nestedatt--spec--landing_zone_ref))
+- `platform_tenant_id` (String) The identifier of the tenant on the platform (e.g. GCP project ID or Azure subscription ID). If this is not set, a new tenant will be created. If this is set, an existing tenant will be imported. Otherwise, this field will be empty until a successful replication has run.
+- `quotas` (Attributes Set) Landing zone quota settings will be applied by default but can be changed here. (see [below for nested schema](#nestedatt--spec--quotas))
+
+<a id="nestedatt--spec--platform_ref"></a>
+### Nested Schema for `spec.platform_ref`
+
+Required:
+
+- `uuid` (String) UUID of the platform.
+
+Optional:
+
+- `kind` (String) meshObject type, always `meshPlatform`.
+
+
+<a id="nestedatt--spec--landing_zone_ref"></a>
+### Nested Schema for `spec.landing_zone_ref`
+
+Required:
+
+- `name` (String) The name (identifier) of the landing zone.
+
 Optional:
 
-- `landing_zone_identifier` (String) Identifier of landing zone to assign to this tenant. **Note:** This field is only optional for platform type SERVICEREGISTRY, otherwise it is required.
-- `local_id` (String) Tenant ID local to the platform (e.g. GCP project ID, Azure subscription ID). Setting the local ID means that a tenant with this ID should be imported into meshStack. Not setting a local ID means that a new tenant should be created. Field will be empty until a successful replication has run. **Note:** Importing is a high-privileged operation and setting this field is possible only when using API Keys with admin permissions for saving tenants.
-- `quotas` (Attributes List) Set of applied tenant quotas. By default the landing zone quotas are applied to new tenants. (see [below for nested schema](#nestedatt--spec--quotas))
+- `kind` (String) meshObject type, always `meshLandingZone`.
+
 
 <a id="nestedatt--spec--quotas"></a>
 ### Nested Schema for `spec.quotas`
 
+Required:
+
+- `key` (String)
+- `value` (Number)
+
+
+
+<a id="nestedatt--ref"></a>
+### Nested Schema for `ref`
+
+Read-Only:
+
+- `kind` (String) meshObject type, always `meshTenant`.
+- `uuid` (String) UUID of the meshTenant.
+
+
+<a id="nestedatt--status"></a>
+### Nested Schema for `status`
+
+Read-Only:
+
+- `platform_type_identifier` (String) Identifier of the platform type.
+- `platform_workspace_identifier` (String) Some platforms create representations of workspaces, in such cases this will contain the identifier of the workspace on the platform.
+- `quotas` (Attributes Set) The effective quotas applied to the tenant. (see [below for nested schema](#nestedatt--status--quotas))
+- `tags` (Map of List of String) Tags assigned to this tenant.
+- `tenant_name` (String) The full tenant name, a concatenation of the workspace identifier, project identifier and platform identifier.
+
+<a id="nestedatt--status--quotas"></a>
+### Nested Schema for `status.quotas`
+
 Read-Only:
 
 - `key` (String)

docs/resources/tenant_v4.md

@@ -18,8 +18,8 @@ Manages a `meshTenant` with API version 4.
 ```terraform
 resource "meshstack_tenant_v4" "example" {
   metadata = {
-    owned_by_workspace = one(data.meshstack_projects.example_all_projects_in_workspace.projects).metadata.owned_by_workspace
-    owned_by_project   = one(data.meshstack_projects.example_all_projects_in_workspace.projects).metadata.name
+    owned_by_workspace = data.meshstack_workspace.example.metadata.name
+    owned_by_project   = data.meshstack_project.example.metadata.name
   }
 
   spec = {

examples/resources/meshstack_tenant/resource.tf

@@ -1,11 +1,13 @@
 resource "meshstack_tenant" "example" {
   metadata = {
-    owned_by_workspace  = data.meshstack_workspace.example.metadata.name
-    owned_by_project    = data.meshstack_project.example.metadata.name
-    platform_identifier = data.meshstack_platform.example.identifier
+    owned_by_workspace = data.meshstack_workspace.example.metadata.name
+    owned_by_project   = data.meshstack_project.example.metadata.name
   }
 
   spec = {
-    landing_zone_identifier = data.meshstack_landingzone.example.metadata.name
+    platform_ref     = data.meshstack_platform.example.ref
+    landing_zone_ref = data.meshstack_landingzone.example.ref
   }
+
+  # wait_for_completion = true
 }

examples/resources/meshstack_tenant_v4/resource.tf

@@ -1,7 +1,7 @@
 resource "meshstack_tenant_v4" "example" {
   metadata = {
-    owned_by_workspace = one(data.meshstack_projects.example_all_projects_in_workspace.projects).metadata.owned_by_workspace
-    owned_by_project   = one(data.meshstack_projects.example_all_projects_in_workspace.projects).metadata.name
+    owned_by_workspace = data.meshstack_workspace.example.metadata.name
+    owned_by_project   = data.meshstack_project.example.metadata.name
   }
 
   spec = {

internal/provider/acctest/testconfig/build_tenant_v3.go

@@ -2,18 +2,18 @@ package testconfig
 
 import "testing"
 
-// TenantV3 builds a tenant (v3) config using the provided prerequisite addresses.
-func TenantV3(t *testing.T, projectAddr, platformAddr, landingZoneAddr Traversal) (config Config, tenantAddr Traversal) {
+// Tenant builds a meshstack_tenant config (v4 body) using the provided prerequisite addresses.
+func Tenant(t *testing.T, projectAddr, platformAddr, landingZoneAddr Traversal) (config Config, tenantAddr Traversal) {
 	t.Helper()
 	return Resource{Name: "tenant"}.Config(t).WithFirstBlock(
 		ExtractAddress(&tenantAddr),
 		Descend("metadata")(
 			Descend("owned_by_workspace")(SetAddr(projectAddr, "metadata", "owned_by_workspace")),
 			Descend("owned_by_project")(SetAddr(projectAddr, "metadata", "name")),
-			Descend("platform_identifier")(SetAddr(platformAddr, "identifier")),
 		),
 		Descend("spec")(
-			Descend("landing_zone_identifier")(SetAddr(landingZoneAddr, "metadata", "name")),
+			Descend("platform_ref")(SetRawExpr("%s", platformAddr.Join("ref"))),
+			Descend("landing_zone_ref")(SetRawExpr("%s", landingZoneAddr.Join("ref"))),
 		),
 	), tenantAddr
 }

internal/provider/acctest/testconfig/config.go

@@ -98,6 +98,19 @@ func (c Config) Join(others ...Config) Config {
 	return result
 }
 
+// WithRawBlock parses raw HCL (e.g. a `moved {}` block) and appends its blocks to a cloned Config.
+func (c Config) WithRawBlock(raw string) Config {
+	c.t.Helper()
+	result := clone(c)
+	parsed, diags := hclwrite.ParseConfig([]byte(raw), "", hcl.Pos{Line: 1, Column: 1})
+	require.False(c.t, diags.HasErrors(), "WithRawBlock: failed to parse raw HCL: %s", diags.Error())
+	for _, block := range parsed.Body().Blocks() {
+		result.internal.Body().AppendNewline()
+		result.internal.Body().AppendBlock(block)
+	}
+	return result
+}
+
 // WithFirstBlock applies consumers to the first block of a cloned Config and returns the new Config.
 func (c Config) WithFirstBlock(consumers ...ExpressionConsumer) Config {
 	c.t.Helper()

internal/provider/provider.go

@@ -208,7 +208,7 @@ func (p *MeshStackProvider) DataSources(_ context.Context) []func() datasource.D
 		NewTagDefinitionDataSource,
 		NewTagDefinitionsDataSource,
 		NewTenantV4DataSource,
-		NewTenantsV4DataSource,
+		NewTenantsDataSource,
 		NewLandingZoneDataSource,
 		NewPlatformDataSource,
 		NewPaymentMethodDataSource,