Add action support for VM power operations (Day-2 actions)

[akli-ime]

Code of Conduct

• I have read and agree to the project's Code of Conduct.
• Vote on this issue by adding a 👍 reaction to the original issue initial description to help the maintainers prioritize.
• Do not leave "+1" or other comments that do not add relevant information or questions.
• If you are interested in working on this issue or have submitted a pull request, please leave a comment.

Description

The Terraform vSphere Provider currently focuses on declarative lifecycle management of virtual machines. However, it does not provide native support for Day-2 operational tasks such as power operations (start, stop, reboot, guest shutdown).

According to Terraform documentation, not all infrastructure operations fit into the traditional CRUD model. Terraform now introduces actions as a first-class concept to handle operations that act on existing resources without representing persistent state.

These actions are designed to expose side-effects and operational workflows, such as maintenance or ad-hoc tasks, which cannot be modeled as standard resources.

In real-world vSphere environments, VM power operations are a typical example of such workflows: they operate on already-managed infrastructure and represent explicit operational intent rather than desired state.

This enhancement proposes adding a native action to the provider to handle VM power state transitions in a way that aligns with Terraform’s emerging action model, instead of relying on external scripts, provisioners, or workarounds.

Use Case(s)

• Reboot VMs after configuration or patching
• Gracefully shutdown guest OS during maintenance windows
• Power on/off environments (e.g., dev/test scheduling)
• Suspend/resume workloads
• Integrate Day-2 operations into Terraform workflows
• Replace external scripts or null_resource patterns with native provider capabilities

Potential Configuration

Proposed action:

action "vsphere_virtual_machine_powerstate" "example" {
  config {
    moid  = "vm-xxx"
    state = "powered-off"
  }
}

Supported values for state:

• powered-off
• powered-on (default)
• reboot-guest
• restarted
• shutdown-guest
• suspended

Behavior

• This action targets an existing VM identified by its moid
• It triggers a vSphere API operation (exemple : RebootGuest)
• It does not represent persistent resource state

Integration with Terraform Actions

Terraform allows providers to expose actions that can be invoked:

1. directly via CLI (terraform apply -invoke=action.vsphere_virtual_machine_powerstate.example)
2. via lifecycle triggers (action_trigger) during apply

Example with trigger:

resource "vsphere_virtual_machine" "vm" {
  # ...
  
  lifecycle {
    action_trigger {
      events  = [after_update]
      actions = [action.vsphere_virtual_machine_powerstate.example]
    }
  }
}

This enables clean integration of Day-2 operations into standard Terraform workflows.

References

https://developer.hashicorp.com/terraform/plugin/framework/actions
https://developer.hashicorp.com/terraform/language/invoke-actions
https://developer.hashicorp.com/terraform/tutorials/configuration-language/actions
https://registry.terraform.io/providers/ansible/aap/latest/docs/actions/job_launch
https://registry.terraform.io/providers/hashicorp/aws/latest/docs/actions/sfn_start_execution