autogen-attribute-addition

name

autogen-attribute-addition

description

End-to-end workflow for supporting a new attribute in an autogenerated (serviceapi) resource or data source. Use whenever the Atlas API spec adds a field to an autogen resource — typically surfaced by the "Updates auto-generated production resources (DO NOT MERGE)" bot PR — or when asked to incorporate such a change, add a new attribute to a serviceapi resource, or follow up on an autogen visibility PR. Covers codegen config overrides, regeneration, acceptance tests, docs, and changelog.

Supporting a new attribute in an autogen resource

When the Atlas Admin API adds a field, the scheduled codegen bot surfaces it in a "DO NOT MERGE" visibility PR for production resources. Incorporating it requires complementary work that the bot does not do. Follow these steps; each one defers to the relevant specialized skill where one exists.

1. Understand the change

• Read the visibility PR diff: which generated files changed, and which endpoint's schema gained the field. Spec files often show only an x-xgen-sha bump because the spec content already landed on master via the internal-resources bot PR.
• The resource, singular data source, and plural data source are generated from different endpoints. A new field may appear on any combination of them — only the surfaces whose endpoint schemas include the field are affected. Check all three before assuming a gap.

2. Check schema consistency and apply overrides before regenerating

The generated schema reflects the spec verbatim, but the spec often does not capture how an attribute should behave in Terraform. Before regenerating, review the full set of available overrides — the Override struct in tools/codegen/config/config_model.go is the source of truth, and tools/codegen/config.yml has real examples of each — and decide which apply to the new field. Overrides go under schema.overrides for the resource and datasources.schema.overrides for data sources.

Always evaluate these two first, since they are the easiest to miss and the most impactful when wrong:

• computability → optional + computed: if the API returns a default value when the attribute is omitted, mark it optional + computed so an absent config value does not produce a perpetual non-empty plan. This is exactly the override the "omitting the value" acceptance test in step 4 verifies.

  resources:
    <resource_name>:
      schema:
        overrides:
          <attr>:
            computability:
              optional: true
              computed: true
  

• sensitive: if the field carries a secret (token, password, key, connection string), mark it sensitive. The spec rarely flags this, so it is easy to leak into plan output and state diffs if not set explicitly.

Other overrides to consider for the specific field:

• Collection type (type): if the field exists on another surface as a Set but the new schema lacks uniqueItems: true, codegen emits a List. Align with a type override:

  resources:
    <resource_name>:
      datasources:
        schema:
          overrides:
            roles:
              type: set # Align with the roles attribute in the resource
  

• Descriptions: each surface inherits wording from its own endpoint schema, so the same field can carry different descriptions. Prefer reporting wording inconsistencies (and missing uniqueItems) to the owning API team over papering them with local description overrides — the provider then picks up the fix on a future regen.

3. Regenerate

make autogen-update-api-spec        # fetch + flatten latest prod spec
make autogen-generate-resources resource_name=<name>  # <name> is the resource key in tools/codegen/config.yml
go build ./...

Verify the diff only touches the expected generated files (schema, model yaml, spec SHA). If model generation fails on an override, read the error — overrides can apply to more than one surface, so the override may have hit an attribute on a surface you did not intend.

4. Acceptance tests

Extend the existing consolidated test (resource + singular DS + plural DS share one test function) rather than adding a new one. Assert the new attribute on every surface that gained it: resource and singular data source checks for top-level attributes, and the plural results checks where the field appears per result. Follow the acceptance-test-patterns skill for conventions.

For a new optional attribute on a resource, also cover the configuration lifecycle, not just the happy path with a value set:

• Omitting the value: a config that never sets the attribute must apply cleanly and produce no non-empty plan afterwards (catches unexpected API defaults that require computed or a computability override).
• Unsetting the value: an update step that removes the attribute from a config that previously set it — verify the intended behavior (value cleared vs. kept by the API) and that the plan converges.

5. Docs and changelog

• Regenerate docs: make generate-doc resource_name=<resource_name> (requires templates in templates/). <resource_name> is the Terraform resource name, which for production autogen resources matches the config.yml key used in step 3. Only commit the generated docs for the affected resource and data sources.
• Add .changelog/<PR number>.txt with a release-note:enhancement block per affected resource/data source (see existing entries for format). The filename must match the PR number — predict it from the latest issue/PR number and verify right after creating the PR.

6. PR

Follow the pr-and-documentation-standards skill and the PR template. Reference the visibility PR and the CLOUDP ticket in the description, and note any upstream spec issues (missing uniqueItems, inconsistent descriptions) reported to the owning team.