[Feature] Add user principal id to global role binding

[Raboo]

Summary

• Add user_principal_id field to rancher2_global_role_binding resource, enabling assignment of global roles to remote users via their principal ID
• Follows the same pattern already used in rancher2_cluster_role_template_binding and rancher2_project_role_template_binding
• Adds user_principal_id to the data source as well for completeness

Related

Fixes #2152

Changes

File	Change
rancher2/schema_global_role_binding.go	Added user_principal_id field to schema
rancher2/structure_global_role_binding.go	Added flatten/expand support for UserPrincipalID
rancher2/data_source_rancher2_global_role_binding.go	Added user_principal_id computed attribute
rancher2/structure_global_role_binding_test.go	Added test coverage for user_principal_id
docs/resources/global_role_binding.md	Added argument reference, example, and note
docs/data-sources/global_role_binding.md	Added attribute reference

Testing

• TestFlattenGlobalRoleBinding — PASS
• TestExpandGlobalRoleBinding — PASS
• go build ./... — compiles cleanly

Breaking Change Notice

This is a breaking change for existing rancher2_global_role_binding resources.

The user_principal_id field uses ForceNew: true, which means that on upgrade, Terraform will detect a diff between the config (which does not specify user_principal_id) and the state (which will be populated from the Rancher API during refresh). This triggers a destroy and recreate of all existing global role bindings managed by Terraform.

This matches the pattern used in rancher2_cluster_role_template_binding and rancher2_project_role_template_binding, where ForceNew: true was eventually adopted for identity-related fields. The field is immutable at the Rancher API level — a global role binding's principal cannot be changed without recreating the binding.

Generated with

This PR was made with OpenCode using model Qwen3.6-35B-A3B.

[matttrach]

Have you tested "ForceNew" here? Does it cause existing configurations which upgrade to the new version to need to be recreated? If so, that would be a breaking change.

[Copilot]

Pull request overview

Adds support for assigning rancher2_global_role_binding to remote users via user_principal_id, bringing the global role binding resource/data source in line with the existing patterns for cluster/project role template bindings.

Changes:

• Extend the global role binding schema/resource flatten+expand to include user_principal_id.
• Expose user_principal_id on the rancher2_global_role_binding data source.
• Update docs and structure tests to cover the new attribute.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
rancher2/schema_global_role_binding.go	Adds user_principal_id to the resource schema.
rancher2/structure_global_role_binding.go	Adds flatten/expand wiring for UserPrincipalID.
rancher2/data_source_rancher2_global_role_binding.go	Adds computed user_principal_id to the data source schema.
rancher2/structure_global_role_binding_test.go	Updates flatten/expand tests to include user_principal_id.
docs/resources/global_role_binding.md	Documents user_principal_id and adds an example for it.
docs/data-sources/global_role_binding.md	Documents the new computed attribute.

Comments suppressed due to low confidence (1)

rancher2/structure_global_role_binding.go:23

• flattenGlobalRoleBinding only sets group_principal_id when the API value is non-empty. If the binding changes on the server (e.g., from group-based to user-based), the prior non-empty group_principal_id can remain in Terraform state because it is never explicitly cleared. Consider always calling d.Set("group_principal_id", in.GroupPrincipalID) (even when empty) to keep state accurate and consistent with other *RoleTemplateBinding flatteners in this repo.

	d.Set("user_principal_id", in.UserPrincipalID)
	d.Set("name", in.Name)

	if len(in.GroupPrincipalID) > 0 {
		d.Set("group_principal_id", in.GroupPrincipalID)
	}

[Raboo]

Have you tested "ForceNew" here? Does it cause existing configurations which upgrade to the new version to need to be recreated? If so, that would be a breaking change.

@matttrach how do I test it? Is there a test that will do it or do I need write a Tofu module that uses this provider to test this situation?

[Raboo]

Have you tested "ForceNew" here? Does it cause existing configurations which upgrade to the new version to need to be recreated? If so, that would be a breaking change.

@matttrach how do I test it? Is there a test that will do it or do I need write a Tofu module that uses this provider to test this situation?

I ran a analysis using my LLM;

Yes, it is a breaking change. Here's the analysis:

What's happening

The Rancher API's GlobalRoleBinding struct already has a UserPrincipalID field. When a user upgrades the provider:

1. Terraform refreshes the resource state by reading from the API
2. flattenGlobalRoleBinding calls d.Set("user_principal_id", in.UserPrincipalID)
3. If the API returns a non-empty user_principal_id (e.g. "local://user-12345"), Terraform sees a diff:
   • Config: user_principal_id = (not specified)
   • State after Read: user_principal_id = "local://user-12345"
4. With ForceNew: true, Terraform plans to destroy and recreate the resource

The Computed: true flag allows Terraform to accept API values, but it does not suppress diffs.

So knowing this is a breaking change (the field is immutable at the API level), what should I do?

[Raboo]

I updated the description of the PR with a breaking change notice.

[Raboo]

@matttrach do I need to do anything to get this moving along?

[matttrach]

Hi @Raboo, I am getting the appropriate team to review, sorry for the wait.

[JonCrowther]

LGTM. Thanks for contributing!

[Raboo]

Thanks guys! Will this be a part of v15.0.0?