fix(zonerrset): make SOA records settable via update-on-create (#1289)

[nikolauspschuetz]

Problem

For type = "SOA" RRSets, the RRSet is created by the Hetzner Cloud API together with the parent Zone, so it cannot be created a second time. Previously the Create method only imported the existing SOA RRSet and ignored the configured records. Applying a SOA RRSet whose configured records differed from the values the API assigned to the Zone therefore failed with:

Provider produced inconsistent result after apply

because the planned records (the user's config) never matched the value read back from the API. This is #1289.

Fix (settable, update-on-create)

Following @jooola's steer on #1289 — "the Create method for the resource must be able to update the existing SOA record with the user provided value, without having to rely on a 2 steps process" — SOA records stay a normal settable attribute, and Create now:

1. Looks up the pre-existing API-managed SOA RRSet (GetRRSetByNameAndType) to obtain its ID.
2. Updates it in place with the user-provided records via SetRRSetRecords — so the SOA record is managed through this resource in a single apply, no 2-step process.

SERIAL normalization: the API auto-increments the SOA SERIAL field, so it can never be predicted from config. As @jooola noted, the provider normalizes SERIAL to 0 in state (OverrideRecordsSOASerial, unchanged) — and the user is required to set SERIAL to 0 in their configuration. With both sides pinned to 0, plan and apply stay consistent and there is no perpetual diff. This is documented on the resource.

Net effect: applying a SOA RRSet with non-default records succeeds in one apply, and subsequent plans are empty — the #1289 symptom is gone.

Changes

• internal/zonerrset/resource.go — Create performs update-on-create for SOA (SetRRSetRecords against the existing RRSet); dropped the "records are imported/ignored" warning since records are now applied; added a return after the not-found diagnostic (the code path previously fell through to a nil deref).
• internal/zonerrset/resource_test.go — TestAccZoneRRSetResource_SOA now asserts the settable behaviour: applying user-provided SOA records (that differ from the API defaults) succeeds and the state reflects the configured value, changing them applies, and re-plans are empty.
• docs/resources/zone_rrset.md — regenerated via make generate; documents update-on-create and the SERIAL = 0 requirement.

Testing

• go build ./..., go vet ./..., gofmt -l — clean.
• Unit tests pass (TestOverrideRecordsSOASerial, TestModel, TestTXTRecordFunction).
• ⚠️ The acceptance test TestAccZoneRRSetResource_SOA has NOT been run — it needs TF_ACC=1 + a live HCLOUD_TOKEN and hits the real Hetzner DNS API (creates/destroys a real Zone). I've verified it compiles and the plan-consistency reasoning, but it needs a CI run or a maintainer/token run to confirm the API round-trips the configured SOA value exactly.
  • One thing to confirm on the live run: whether the API echoes the configured SOA value byte-for-byte (aside from the auto-incremented SERIAL, which we normalize). If the API canonicalises the SOA string in any other field, the exact-match assertion would need a tweak — flagging so it can be verified against the test account.

Closes #1289

AI assistance

Disclosing per the AI / LLM policy (thanks for the pointer, @jooola): this PR was developed with AI assistance — Claude Code (Anthropic). I reviewed and verified every line, take responsibility for the change, and can explain/defend it in review. This is my only open AI-assisted PR on this repo.

[jooola]

Hey, before going any further, please have a quick look at our contributing guideline, in particular the AI/LLM policy: https://github.com/hetznercloud/terraform-provider-hcloud?tab=contributing-ov-file#ai--llm-policy

I suspect this PR was created with the assistance of an AI tool, but this was not disclosed.

[nikolauspschuetz]

You're right, and apologies for the omission — I've updated the PR description with an AI/LLM disclosure per the policy.

To be explicit on accountability: I hit and reproduced the #1289 "inconsistent result after apply" myself, traced it to the SOA normalization path only handling SERIAL (OverrideRecordsSOASerial) while the API rewrites the other SOA fields, and chose the API-managed approach here. I reviewed and edited every line and can explain/defend it in review. The one open question (read-only vs. settable SOA records, and plan-modifier vs. Computed-only) is genuinely yours to steer — happy to switch the implementation to whichever you prefer.

[jooola]

See my answer to your question in the related issue.

[nikolauspschuetz]

Thanks for the steer, @jooola — you're right that option 1 threw away the ability to manage the SOA record, which we want to keep. I've reworked this to the settable update-on-create approach you described:

• SOA records stay a normal settable attribute (reverted the read-only plan-modifier mechanism from the first draft).
• Create now looks up the pre-existing API-managed SOA RRSet and updates it in place with the user-provided records (SetRRSetRecords), so it's a single apply — no 2-step process.
• SERIAL is normalized to 0 in state as before, and the user sets it to 0 in config, so plan/apply stay consistent and there's no perpetual diff.

The acceptance test TestAccZoneRRSetResource_SOA is restored to the settable expectation (apply user-provided records → succeeds in one apply, changing them applies, re-plans are empty). I haven't been able to run it — it needs TF_ACC=1 + a live token — so it'd need a CI/maintainer run to confirm the API round-trips the configured SOA value exactly (aside from the auto-incremented SERIAL we normalize). Flagged that in the PR body too.

Disclosure: drafted with AI assistance (Claude Code); I've reviewed and verified the change and can defend it in review.

[nikolauspschuetz]

Verified the settable update-on-create rework end-to-end against the live Hetzner API. The acceptance test (TestAccZoneRRSetResource_SOA) now passes, including the exact-value round-trip — the API only rewrites SERIAL (which we normalize to 0), so no other SOA field drifts and there's no post-apply inconsistency.

I ran it through the project's own Test → e2e workflow on my fork (against a dedicated, throwaway Hetzner Cloud project), so it's the same pipeline you'd run:

Passing run: https://github.com/nikolauspschuetz/terraform-provider-hcloud/actions/runs/28606982956

--- PASS: TestAccZoneRRSetDataSourceList (30.21s)
--- PASS: TestAccZoneRRSetDataSource (30.57s)
--- PASS: TestAccZoneRRSetResource_SOA (32.12s)
--- PASS: TestAccZoneRRSetResource (49.78s)
ok  github.com/hetznercloud/terraform-provider-hcloud/internal/zonerrset  49.795s

(Running the e2e job from a fork needs a credential path other than the OIDC/TPS one, since that's scoped to this org. I threaded your tps-action's existing token / tps-url inputs through the workflow in a small separate PR — #1475 — so a fork can authenticate with its own HCLOUD_TOKEN; it's backward-compatible and I'm happy to drop it if you'd prefer.)

Disclosure: developed with AI assistance (Claude Code); I reproduced the issue, validated the diagnosis, ran the verification above, and reviewed every line.