Refactor/agentpool models

[isivaselvan]

Description

Refactors the agent pool models and resource implementation to align more closely with the current Terraform Enterprise API shape. This change removes the old allowed_workspace_policy model, adds first-class support for allowed projects/workspaces relationships, and improves agent pool parsing/validation across list, create, read, update, and assignment flows.

It also introduces project assignment support for agent pools, adds agent-pool-specific validation errors, and updates examples/tests to reflect the new model behavior. As part of the refactor, the model layer was adjusted to better handle forward references and circular imports between AgentPool, Project, Workspace, and related models.

Key changes

• Remove AgentPoolAllowedWorkspacePolicy from agent pool models and exports
• Add support for:
  • allowed_project_ids
  • allowed_workspace_ids
  • excluded_workspace_ids
  • allowed_projects, allowed_workspaces, and excluded_workspaces relationships on AgentPool
• Add AgentPoolAssignToProjectsOptions and implement assign_to_projects() in the agent pool resource
• Refactor agent pool response parsing into a shared _parse_agent_pool_from() helper
• Replace generic validation/value errors with more specific agent-pool-related errors
• Expand AgentPoolListOptions to support include/query/filter/sort parameters
• Add model validation for create/update options
• Resolve circular import / forward reference issues with model rebuilds
• Update the example script to demonstrate project assignment
• Update unit tests to match the refactored model/API behavior

Testing plan

External links

• JIRA
• Issue

Output from tests

Including output from tests may require access to a TFE instance. Ignore this section if you have no environment to test against.

> python examples/agent_pool.py
Connected to: https://app.terraform.io
 Organization: prab-sandbox01

 Listing existing agent pools...
Found 3 agent pools:
  - pytfe-test-agentpool (ID: apool-SoqJ6BDzXZgSxcuL, Agents: 0)
  - sdk-example-pool-b6f4d866-updated (ID: apool-2XpzVTfiK1FSLJyc, Agents: 0)
  - agent-pool-test (ID: apool-xjy1WtFEZUGRCqun, Agents: 0)

 Creating a new agent pool...
Created agent pool: sdk-example-pool-9858d26b (ID: apool-uD5TR4mKZejfX9fw)

 Reading agent pool details...
Name: sdk-example-pool-9858d26b
Organization Scoped: True
Agent Count: 0

 Updating agent pool...
Updated agent pool name to: sdk-example-pool-9858d26b-updated

 Assigning workspace to agent pool...
  Assigned workspace ws-m7LuQ3FPv2ug3hEA to pool sdk-example-pool-9858d26b-updated

 Removing workspace from agent pool...
  Removed workspace ws-m7LuQ3FPv2ug3hEA from pool sdk-example-pool-9858d26b-updated

 Assigning project to agent pool...
  Assigned project prj-fC61qfoTBVNAAEAu to pool sdk-example-pool-9858d26b-updated

 Listing agent tokens...
Found 1 tokens:
  - SDK example token (ID: at-7z3NLwZQaeRvPfkx)

 Cleaning up...
Deleted agent token
Deleted agent pool

 Agent pool operations completed successfully!

Rollback Plan

Changes to Security Controls

PCI review checklist

• I have documented a clear reason for, and description of, the change I am making.

• If applicable, I've documented a plan to revert these changes if they require more than reverting the pull request.

• If applicable, I've documented the impact of any changes to security controls.

  Examples of changes to security controls include using new access control methods, adding or removing logging pipelines, etc.

If you have any questions, please contact your direct supervisor, GRC (#team-grc), or the PCI working group (#proj-pci-reboot). You can also find more information at PCI Compliance.