autogen-create-resource

name	autogen-create-resource
description	Use when creating a brand-new autogenerated (serviceapi) resource in this provider from an OpenAPI spec — "autogenerate new terraform resource <name>", a new-resource workflow dispatch, or any request to add a new autogen resource together with its acceptance tests, examples, docs, and changelog.

Create a new autogen resource

Orchestrates the full new-resource flow: generated code plus the complementary artifacts. This skill owns sequencing and commands only — schema and config judgment lives in autogen-config, test conventions in acceptance-test-patterns, docs, examples, and changelog conventions in pr-and-documentation-standards.

Inputs

1. Resource name — the future tools/codegen/config.yml key (strip any mongodbatlas_ prefix; no _api suffix, that tier is internal-only).
2. Spec source — default is the prod spec. Otherwise the caller supplies a URL or an already-fetched local file passed as spec_source.
3. Artifact selection — which complementary artifacts to produce (a dispatch may deselect e.g. acceptance tests). Default: all.
4. Output file (optional) — output_file, the path the run summary is written to. Non-interactive callers such as a CI workflow supply it; when it is absent the summary is presented in the session instead.

Flow

1. Fetch and flatten the spec

   make autogen-update-api-spec              # prod
   make autogen-update-api-spec spec_source=<url-or-file>
   

2. Author the config.yml entry — follow the autogen-config skill (path-to-CRUD mapping, version_header, aliases, ignores, wait, overrides).
3. Generate

   make autogen-generate-resources resource_name=<name>
   

4. Schema review — the post-generation review in autogen-config. Apply override fixes and regenerate before building artifacts on top of a wrong schema.
5. Register in the provider — manual edit to internal/provider/provider.go: add the internal/serviceapi/<package> import, then register only the surfaces codegen actually emitted. Resource exists only when the entry has resource CRUD operations, DataSource only with datasources.read, and PluralDataSource only with datasources.list, so check which files the generator produced (resource.go, data_source.go, plural_data_source.go) before adding entries: referencing a symbol codegen did not emit fails go build. metricintegration has all three; aimodelorgapikey is data-source-only. If the package name collides with a handwritten service, use an aliased import (see autogenprojectipaccesslist). Do not use make enable-internal-autogen — it registers every unregistered serviceapi package, including internal _api ones.
6. Build: go build ./...
7. Complementary artifacts (honoring the artifact selection):
   • Acceptance tests — internal/serviceapi/<package>/resource_test.go + main_test.go, following acceptance-test-patterns (consolidated resource+data-source test, optional-attribute lifecycle, checkExists/checkDestroy via the SDK's untyped client with the package's apiVersionHeader const). If the Go SDK lacks the endpoint, add a raw-HTTP helper under internal/testutil/acc/ (see metric_integration.go there).
   • CI wiring — in .github/workflows/acceptance-tests-runner.yml: add internal/serviceapi/<package>/*.go to the autogen_fast change-detection filter group (autogen_slow only for long-provisioning resources), and add the package to ACCTEST_PACKAGES. Without this a new package belongs to no group and its tests never run on PRs. If the tests need external credentials, do not invent secret names — flag the secrets wiring (runner secrets: inputs, job env, acceptance-tests.yml pass-through) under "Needs human attention".
   • Examples — follow pr-and-documentation-standards. One flow: flat examples/mongodbatlas_<name>/ with main.tf. Two or more flows: parent README plus use-case sibling directories (canonical: examples/mongodbatlas_cloud_backup_collection_restore_job/). Embed registry docs with tffile; do not paste HCL into .md.tmpl. Prerequisite third-party resources are defined inline or as input variables with best-effort realistic values, flagged for the author.
   • Docs — author a template per surface that exists: templates/resources/<name>.md.tmpl, and templates/data-sources/<name>.md.tmpl / <name>s.md.tmpl for the singular and plural data sources codegen emitted (subcategory, import section, any behavioral notes codegen can't produce), then make generate-doc resource_name=<name>.
   • Changelog — .changelog/<PR number>.txt: one release-note:new-resource block plus one release-note:new-datasource block per data source. Predict the number from the latest issue/PR number when reachable, otherwise from the highest existing .changelog/ entry, and flag it for verification once the PR exists.
8. Run summary — see below.

Structured run summary

End every run by producing a summary with two sections. Write it to output_file when the caller supplied one; otherwise present it in the session.

• Reasoning — the notable judgment calls: override choices and their upstream spec reports, aliases/ignores/wait decisions, acceptance-test scenarios covered, artifacts skipped by deselection, anything you could not verify.
• Needs human attention — aggregated follow-ups: prerequisite resources to provision, secrets wiring, likely resource_custom_hooks.go work (flag, never attempt), possible breaking changes, upstream module impact. Omit empty categories; state "None identified" if the list is empty.

When the spec source is not prod, state DO NOT MERGE prominently at the top of the summary. Do not create the PR; the caller (CI workflow or engineer) owns that.

Error handling

Error	Cause and resolution
npx or flattener fails	Node.js not installed — check node --version.
model-gen: "resource not found"	Name doesn't match the config.yml key.
model-gen: override error	Overrides can hit the same attribute on multiple surfaces — read the error, it may be a surface you did not intend.
code-gen failure	Structural issue in tools/codegen/models/<name>.yaml — inspect the model.
go build ./... fails on provider.go imports	Registration step incomplete, or it registers a surface codegen did not emit; may also need go mod tidy.