Provider v0.2.1 to v1.0.1

This is an explicit resource cutover, not an in-place provider upgrade. Provider v1.0.1 is published and its authenticated Terraform/OpenTofu readback from the canonical Registry is retained. These instructions are now the operator procedure for that exact signed provider.

This guide applies only when the state was written by provider v0.2.1. Provider v0.1.x state must remain pinned to the exact v0.1.x release that wrote it; it cannot be safely refreshed through v0.2.1 as an intermediate migration step.

Why a direct upgrade is unsafe

Provider v0.2.1 and published v1.0.1 each compile 34 exact Form identities, but none of the old identities is unchanged:

• 33 kinds keep a Terraform resource type while changing their exact definition and/or package identity;
• HttpService is removed and EdgeWorker is added;
• the writable takoform_interface resource is removed;
• common naming, connection, artifact, and semantic field contracts changed.

An exact Resource GET includes the build-pinned FormRef and package digest. Without a migration fence, refreshing old state through provider v1 could query the new exact identity, receive 404 while the old exact Resource still exists, and remove that Terraform state entry as if the Resource had been deleted.

Provider v1 therefore gives every Form resource schema version 1, records the exact identity in five computed state attributes, and gives schema version 0 only a diagnostic-only rejection handler. It returns no transformed state and makes no Resource lifecycle request. OpenTofu or Terraform must therefore reject v0.2.1 Form state before resource lifecycle code can query an exact Resource identity. A missing or mismatched exact identity also produces a diagnostic before any Resource lifecycle request and retains state. Provider configuration may already have performed host discovery; this fence is about Create, Read, Update, Delete, and Import requests, not every possible HTTP request. There is no portable transformation that could honestly infer backend data migration, rename Resources, or translate all changed desired schemas.

The machine-readable audit is v0.2.1-to-v1.0.1.json.

1. Inventory and back up under v0.2.1

Keep the old provider and source configuration pinned while inspecting the old state:

terraform {
  required_providers {
    takoform = {
      source  = "registry.terraform.io/tako0614/takoform"
      version = "= 0.2.1"
    }
  }
}

tofu providers
tofu state list
tofu state pull > takoform-v0.2.1-state.json

state pull output can contain sensitive values. Store it according to the backend recovery policy and never commit it. For each Form Resource, record its Space, name, exact host identity, consumers, public outputs, data backup, and rollback owner. A stateful Resource needs a host/backend-specific data migration and recovery proof; Takoform cannot synthesize one from HCL state.

2. Normalize an old OpenTofu provider address when necessary

First inspect tofu providers. Many v0.2.1 configurations already used the canonical Terraform Registry address. Only state that actually names registry.opentofu.org/tako0614/takoform needs replacement.

Keep version 0.2.1 pinned, change required_providers.takoform.source to the canonical address shown above, back up state, and run the command without -auto-approve so the proposed state identities can be reviewed:

tofu state replace-provider \
  registry.opentofu.org/tako0614/takoform \
  registry.terraform.io/tako0614/takoform

Then run tofu providers again and take another state backup. This operation changes only the provider address stored in state. It does not convert a v0.2.1 Form identity, desired schema, remote Resource, or host data into its v1 successor, and it does not make an in-place provider upgrade safe.

3. Cut over Resources explicitly

Use a separate state/work directory for candidate v1 Resources. Provider constraints select one version of one source address for a configuration, so the old management state and new cutover state must not be mixed.

For each Resource:

1. Choose a new Space/name when old and new Resources must coexist.
2. Translate the HCL deliberately to the current resource schema.
3. Create the new exact Resource with provider v1.
4. Verify host observation, public outputs, runtime behavior, and any data copy.
5. Move consumers to the new Resource and prove rollback while the old one still exists.
6. Delete the old Resource through its v0.2.1 state only after cutover is accepted.

takoform_http_service requires a semantic migration to takoform_edge_worker; a state rename is not a migration. A writable takoform_interface may point at an Interface record the host has already adopted. Destroying that resource through v0.2.1 sends the host delete request and can delete the adopted record. After explicitly verifying host ownership, binding continuity, and a rollback record, remove only the Terraform state entry for an adopted Interface. Destroy it through v0.2.1 only when the operator intentionally wants to retire the remote Interface record. No state mv, replace-provider, or v1 import can change either old remote identity into the new one.

Destroy-and-recreate in one name/Space is an alternative only when the operator has explicitly accepted the outage and data-loss boundary. Takoform does not declare that safe by default.

4. Start the v1 state line

Only a clean v1 state, or a Resource that the host already exposes under the current exact v1 Form identity, may be created or imported with provider v1. Every successful create, read, and import records:

• form_api_version;
• form_kind;
• form_definition_version;
• form_schema_digest;
• form_package_digest.

Future provider builds must fail closed when those values differ from the build-pinned exact identity. A genuine 404 removes state only after this identity check proves that the state and provider are talking about the same exact Form.

Do not run plan, apply, refresh, or import with provider v1 against a v0.2.1 state snapshot. The schema-version and exact-identity diagnostics are a last-resort loss-prevention fence, not an automatic migration mechanism.