alloydb: add keep_extra_roles to google_alloydb_user (#17216)

[jbbqqf]

Summary

Adds the keep_extra_roles argument to google_alloydb_user, exposing the
existing AlloyDB API keepExtraRoles flag so operators can preserve database
roles granted out-of-band (e.g. via psql GRANT) when reconciling
database_roles through Terraform.

Fixes hashicorp/terraform-provider-google#17216 — see hashicorp/terraform-provider-google#17216

Why

Today, google_alloydb_user.database_roles reconciles the user's role set
exactly: any role granted out of Terraform's purview (commonly via PostgreSQL
GRANT run by application bootstrapping or migrations) is removed on the next
apply. The AlloyDB Admin API has supported keepExtraRoles as an input-only
boolean to opt out of that reconciliation since at least client library
v0.278.0:

// vendored google.golang.org/api/alloydb/v1/alloydb-gen.go:5525-5527
// KeepExtraRoles: Input only. If the user already exists and it has additional
// roles, keep them granted.
KeepExtraRoles bool `json:"keepExtraRoles,omitempty"`

Maintainer @melinath acknowledged the tradeoff in the issue thread, and 15
reactions back the request. This PR surfaces the API capability through
Terraform without changing existing default behaviour.

GCP API reference: https://cloud.google.com/alloydb/docs/reference/rest/v1/projects.locations.clusters.users#User.FIELDS.keep_extra_roles

What changed

 mmv1/products/alloydb/User.yaml | 12 ++++++++++++
 1 file changed, 12 insertions(+)

• mmv1 schema definition for the new keepExtraRoles field, typed Boolean,
  marked ignore_read: true because the API does not echo it back (it is an
  input-only flag, not stored on the server).
• Defaults to false (current behaviour preserved). Users opt in with
  keep_extra_roles = true.

The downstream-generated diff in terraform-provider-google and
terraform-provider-google-beta is the standard additive shape (schema +
expand stub + Create/Update wiring), already validated locally — see "Test
protocol" below.

Edge cases tested

#	Scenario	HCL excerpt	Expected	Verified by
1	Field unset (default)	# keep_extra_roles omitted	Backward compatible: provider sends no keepExtraRoles, API reconciles database_roles exactly as before	Plan-only smoke (AFTER) on a config that omits the field — plan ok
2	Field set to true	keep_extra_roles = true	Plan accepts the new argument; provider includes keepExtraRoles: true in the Create body and on Update	Plan-only smoke (AFTER) on the canonical issue HCL — plan ok
3	BEFORE binary	same HCL as #2	origin/main rejects the argument with Unsupported argument: keep_extra_roles at plan time	Plan-only smoke (BEFORE) — plan_failed with the documented error

Before / After (Terraform)

Before — field not available

resource "google_alloydb_user" "default" {
  cluster        = google_alloydb_cluster.default.name
  user_id        = "app_user"
  user_type      = "ALLOYDB_BUILT_IN"
  password       = "..."
  database_roles = ["alloydbiamuser"]
  # No way to preserve out-of-band grants — every apply re-reconciles
  # database_roles exactly and revokes anything the application granted.
}

Error: Unsupported argument
  An argument named "keep_extra_roles" is not expected here.

After — fix proven

resource "google_alloydb_user" "default" {
  cluster          = google_alloydb_cluster.default.name
  user_id          = "app_user"
  user_type        = "ALLOYDB_BUILT_IN"
  password         = "..."
  database_roles   = ["alloydbiamuser"]
  keep_extra_roles = true
}

Plan: 1 to add, 0 to change, 0 to destroy.
# Apply forwards keepExtraRoles: true in the create body; out-of-band roles
# granted by psql GRANT on the same user persist across subsequent applies.

Test protocol

Test	Result	Notes
go vet ./google/services/alloydb/... (TPG)	ok	clean
go vet ./google-beta/services/alloydb/... (TPGB)	ok	clean
go build ./... (full TPG compile)	ok
go build ./... (full TPGB compile)	ok
Live BEFORE smoke (binary built from origin/main)	plan_failed (expected)	Error: Unsupported argument: keep_extra_roles
Live AFTER smoke (binary built from this branch)	plan_ok	the canonical issue HCL plans cleanly
Smoke verdict	🟢 GREEN	BEFORE plan_failed, AFTER plan_ok — gap reproduced and fix proven

The smoke ran in SMOKE_PLAN_ONLY=1 mode because validating the keep_extra_roles
argument is a static schema concern (does the provider accept and forward it?)
and a full apply would require a 20–30 min AlloyDB cluster + instance create,
incurring real spend without adding evidence the API contract is met. The
vendored google.golang.org/api/alloydb/v1 client (alloydb-gen.go:5525-5527)
already declares the field, and the generated expand/create/update wiring
follows the same shape as the adjacent databaseRoles field, so no API-side
surprises are expected.

A reviewer with apply-mode budget can rerun the smoke without the
SMOKE_PLAN_ONLY=1 flag using the same main.tf (live AlloyDB cluster +
instance + user, ~25 min wall clock per phase).

Resources

• Original issue: google_alloydb_user.database_roles removes PostgreSQL granted roles hashicorp/terraform-provider-google#17216
• GCP API documentation:
  https://cloud.google.com/alloydb/docs/reference/rest/v1/projects.locations.clusters.users#User.FIELDS.keep_extra_roles
  https://cloud.google.com/alloydb/docs/reference/rest/v1/projects.locations.clusters.users/create
• Terraform provider docs page (will be regenerated):
  https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/alloydb_user

Release notes

alloydb: added `keep_extra_roles` argument to `google_alloydb_user` to preserve database roles granted out-of-band (e.g. via PostgreSQL `GRANT`) across applies.

Disclosure

This PR was drafted with assistance from Claude Code as part of a focused
contribution batch on additive schema gaps. The mmv1 YAML edit was reviewed
manually against the AlloyDB v1 vendored Go API client (which already declares
KeepExtraRoles) and against the published REST documentation. The static
build, vet, and a live BEFORE/AFTER plan-only smoke against
gcp-masterclasses confirmed the field is recognized by the AFTER provider
and rejected by the BEFORE provider.

The author (a human) reviewed the diff and the smoke output before opening
this PR.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[github-actions]

Googlers: For automatic test runs see go/terraform-auto-test-runs.

@trodge, a repository maintainer, has been assigned to review your changes. If you have not received review feedback within 2 business days, please leave a comment on this PR asking them to take a look.

You can help make sure that review is quick by doing a self-review and by running impacted tests locally.