vmware-tanzu · dilyar85 · Nov 19, 2025 · Sep 16, 2025 · Nov 19, 2025
diff --git a/docs/concepts/workloads/README.md b/docs/concepts/workloads/README.md
@@ -17,3 +17,4 @@ This section provides information about workload resources, such as:
 In addition to the workload resources themselves, there is documentation related to broader topics related to workloads:
 
 * [Customizing a Guest](./guest.md)
+* [vSphere Policies](./vsphere-policies.md)
diff --git a/docs/concepts/workloads/vm.md b/docs/concepts/workloads/vm.md
@@ -99,6 +99,16 @@ kubectl get -n <NAMESPACE> encryptionclass
 
 For more information on `EncryptionClass` resources, please see the [Encryption](#encryption) section below.
 
+### vSphere Policies
+
+A `ComputePolicy` is a namespace-scoped resource from the `vsphere.policy.vmware.com/v1alpha1` API group that defines vSphere compute policies that can be applied to VMs. These policies control various aspects of VM placement, resource allocation, and operational behavior. The following command may be used to discover a namespace's available `ComputePolicy` resources:
+
+```shell
+kubectl get -n <NAMESPACE> computepolicy
+```
+
+For more information on vSphere policies and how to apply them to VMs, please see the [vSphere Policies](#vsphere-policies-1) section below.
+
 ## Hardware
 
 ### Configuration
@@ -143,6 +153,7 @@ It is possible to update parts of an existing `VirtualMachine` resource. Some fi
 | `spec.imageName` | The name of the `VirtualMachineImage` that supplies the VM's disk(s) | ✗ | ✗ | _NA_ |
 | `spec.className` | The name of the `VirtualMachineClass` that supplies the VM's virtual hardware | ✓ | ✓ | _NA_ |
 | `spec.powerState` | The VM's desired power state | ✓ | ✓ | _NA_ |
+| `spec.policies` | The list of vSphere policies to apply to the VM | ✓ | ✓ | _NA_ |
 | `metadata.labels.topology.kubernetes.io/zone` | The desired availability zone in which to schedule the VM | x | x | ✓ |
 | `spec.hardware.cdrom[].name` | The name of the CD-ROM device to mount ISO in the VM | x | ✓ | _NA_ |
 | `spec.hardware.cdrom[].image` | The reference to an ISO type `VirtualMachineImage` or `ClusterVirtualMachineImage` to mount in the VM | x | ✓ | _NA_ |
@@ -1012,6 +1023,80 @@ The `spec.hardware.cdrom[].allowGuestControl` field controls the guest OS's abil
 
 For more information on the ISO VM workflow, please refer to the [Deploy a VM with ISO](../../../tutorials/deploy-vm/iso/) tutorial.
 
+## vSphere Policies
+
+vSphere policies provide a way to apply compute and tag policies to VMs. These policies can control placement, resource allocation, and operational behavior of VMs in a vSphere environment.
+
+### Configuration
+
+The field `spec.policies` may be used to specify one or more policies to apply to a VM. Each policy reference includes the API version, kind, and name of the policy object:
+
+```yaml
+apiVersion: vmoperator.vmware.com/v1alpha5
+kind: VirtualMachine
+metadata:
+  name: my-vm
+  namespace: my-namespace
+spec:
+  className: my-vm-class
+  imageName: vmi-0a0044d7c690bcbea
+  storageClass: my-storage-class
+  policies:
+  - apiVersion: vsphere.policy.vmware.com/v1alpha1
+    kind: ComputePolicy
+    name: my-compute-policy
+```
+
+Only `ComputePolicy` objects with `spec.enforcementMode: Optional` can be explicitly applied to VMs through the `spec.policies` field. Mandatory policies are automatically applied based on their match criteria and do not need to be specified.
+
+### Status
+
+Information about the policies applied to a VM can be found in `status.policies`. This includes both explicitly requested policies and any mandatory policies that were automatically applied:
+
+```yaml
+status:
+  policies:
+  - apiVersion: vsphere.policy.vmware.com/v1alpha1
+    kind: ComputePolicy
+    name: my-compute-policy
+    generation: 2
+  - apiVersion: vsphere.policy.vmware.com/v1alpha1
+    kind: ComputePolicy
+    name: namespace-default-policy
+    generation: 1
+```
+
+The `generation` field indicates the observed generation of the policy when it was applied to the VM, which helps track whether the VM is using the latest version of a policy.
+
+### Policy Types
+
+#### ComputePolicy
+
+A `ComputePolicy` defines compute-related policies for VMs, such as placement rules, resource allocations, and operational constraints. These policies can be:
+
+- **Mandatory**: Automatically applied to VMs based on match criteria
+- **Optional**: Must be explicitly referenced in the VM's `spec.policies` field
+
+The policy may include references to `TagPolicy` objects that define vSphere tags to be applied to activate the policy.
+
+#### TagPolicy
+
+A `TagPolicy` defines vSphere tags that should be applied to workloads. These are typically referenced by `ComputePolicy` objects and are not directly applied to VMs.
+
+### Policy Evaluation
+
+When a VM is created or updated, the system evaluates which policies should be applied based on:
+
+1. **Explicit policies**: Those listed in `spec.policies`
+2. **Mandatory policies**: Those with `spec.enforcementMode: Mandatory` that match the VM
+3. **Match criteria**: Policies can specify match criteria based on:
+   - Workload labels
+   - Image name and labels
+   - Guest operating system (ID and family)
+   - Workload kind (Pod or VirtualMachine)
+
+The evaluation results are reflected in `status.policies`, showing all policies that have been applied to the VM.
+
 ## Affinity
 
 The optional field `spec.affinity` that may be used to define a set of affinity/anti-affinity scheduling rules for VMs.

diff --git a/docs/concepts/workloads/vsphere-policies.md b/docs/concepts/workloads/vsphere-policies.md
@@ -0,0 +1,279 @@
+# vSphere Policies
+
+vSphere Policies provide a declarative way to manage compute policies, tags, and operational constraints for virtual machines running in a vSphere environment. These policies are part of the `vsphere.policy.vmware.com` API group and integrate with VM Operator to enable policy-driven VM management.
+
+## Overview
+
+The vSphere Policy APIs introduce three main resource types:
+
+- **ComputePolicy**: Defines compute-related policies for workloads
+- **TagPolicy**: Defines vSphere tags to be applied to workloads
+- **PolicyEvaluation**: Evaluates which policies should apply to a workload
+
+These resources work together to provide flexible, declarative policy management that can be applied either explicitly or automatically based on matching criteria.
+
+## ComputePolicy
+
+A `ComputePolicy` resource defines compute-related policies that control various aspects of VM behavior, placement, and resource allocation in vSphere.
+
+### Specification
+
+```yaml
+apiVersion: vsphere.policy.vmware.com/v1alpha1
+kind: ComputePolicy
+metadata:
+  name: production-policy
+  namespace: my-namespace
+spec:
+  description: "Production workload policy"
+  policyID: "vsphere-policy-123"  # Optional vSphere policy ID
+  enforcementMode: Mandatory       # Or Optional
+  match:
+    workload:
+      labels:
+      - key: tier
+        operator: In
+        values:
+        - production
+      kind: VirtualMachine
+  tags:
+  - production-tag-policy
+```
+
+### Enforcement Modes
+
+ComputePolicy resources support two enforcement modes:
+
+#### Mandatory Policies
+
+- Automatically applied to all matching workloads in the namespace
+- Cannot be overridden or removed by users
+- Applied based on the `match` criteria
+- If no `match` is specified, applies to all workloads in the namespace
+
+#### Optional Policies
+
+- Must be explicitly referenced in a VM's `spec.policies` field
+- Users can choose whether to apply these policies
+- Provide flexibility for workload-specific requirements
+
+### Match Specifications
+
+The `match` field allows sophisticated matching based on:
+
+#### Workload Properties
+- **Labels**: Match based on workload labels using label selector requirements
+- **Kind**: Filter by workload type (`Pod` or `VirtualMachine`)
+- **Guest OS**: Match based on guest ID or guest family
+
+#### Image Properties
+- **Name**: Match based on image name patterns
+- **Labels**: Match based on image labels
+
+#### Boolean Operations
+- **And**: All conditions must match (default)
+- **Or**: At least one condition must match
+
+Example of complex matching:
+
+```yaml
+spec:
+  match:
+    op: Or
+    match:
+    - workload:
+        labels:
+        - key: tier
+          operator: In
+          values: [production]
+    - image:
+        name:
+          op: HasPrefix
+          value: "production-"
+```
+
+## TagPolicy
+
+A `TagPolicy` resource defines vSphere tags that should be applied to workloads. These are typically referenced by ComputePolicy objects.
+
+### Specification
+
+```yaml
+apiVersion: vsphere.policy.vmware.com/v1alpha1
+kind: TagPolicy
+metadata:
+  name: production-tag-policy
+  namespace: my-namespace
+spec:
+  tags:
+  - "urn:vmomi:InventoryServiceTag:12345678-1234-1234-1234-123456789abc:GLOBAL"
+  - "urn:vmomi:InventoryServiceTag:87654321-4321-4321-4321-cba987654321:GLOBAL"
+```
+
+Tags are specified as UUIDs that correspond to tags configured in vSphere. When a ComputePolicy references a TagPolicy, the tags are applied to activate the policy on the workload.
+
+## PolicyEvaluation
+
+A `PolicyEvaluation` resource is used to evaluate which policies should apply to a theoretical workload configuration. This is useful for testing and validation before actually creating VMs.
+
+### Specification
+
+```yaml
+apiVersion: vsphere.policy.vmware.com/v1alpha1
+kind: PolicyEvaluation
+metadata:
+  name: test-evaluation
+  namespace: my-namespace
+spec:
+  workload:
+    labels:
+      tier: production
+    guest:
+      guestID: ubuntu64Guest
+      guestFamily: Linux
+  image:
+    name: ubuntu-22.04
+    labels:
+      os: ubuntu
+  policies:
+  - apiVersion: vsphere.policy.vmware.com/v1alpha1
+    kind: ComputePolicy
+    name: specific-policy
+```
+
+### Status
+
+After evaluation, the status will contain the list of policies that would apply:
+
+```yaml
+status:
+  policies:
+  - apiVersion: vsphere.policy.vmware.com/v1alpha1
+    kind: ComputePolicy
+    name: production-policy
+    observedGeneration: 2
+    tags:
+    - "urn:vmomi:InventoryServiceTag:12345678-1234-1234-1234-123456789abc:GLOBAL"
+  - apiVersion: vsphere.policy.vmware.com/v1alpha1
+    kind: ComputePolicy
+    name: namespace-default
+    observedGeneration: 1
+  conditions:
+  - type: Ready
+    status: "True"
+```
+
+## Applying Policies to VirtualMachines
+
+### Explicit Application
+
+Optional policies can be explicitly applied to a VM using the `spec.policies` field:
+
+```yaml
+apiVersion: vmoperator.vmware.com/v1alpha5
+kind: VirtualMachine
+metadata:
+  name: my-vm
+  namespace: my-namespace
+spec:
+  className: my-vm-class
+  imageName: ubuntu-22.04
+  storageClass: my-storage-class
+  policies:
+  - apiVersion: vsphere.policy.vmware.com/v1alpha1
+    kind: ComputePolicy
+    name: performance-policy
+  - apiVersion: vsphere.policy.vmware.com/v1alpha1
+    kind: ComputePolicy
+    name: compliance-policy
+```
+
+### Automatic Application
+
+Mandatory policies are automatically applied based on their match criteria. The VM's status will reflect all applied policies:
+
+```yaml
+status:
+  policies:
+  - apiVersion: vsphere.policy.vmware.com/v1alpha1
+    kind: ComputePolicy
+    name: performance-policy
+    generation: 3
+  - apiVersion: vsphere.policy.vmware.com/v1alpha1
+    kind: ComputePolicy
+    name: compliance-policy
+    generation: 1
+  - apiVersion: vsphere.policy.vmware.com/v1alpha1
+    kind: ComputePolicy
+    name: namespace-mandatory-policy
+    generation: 2
+```
+
+The `generation` field indicates which version of the policy was applied, helping track when policies need to be re-evaluated.
+
+## Match Operations
+
+The policy matching system supports various string and pattern matching operations:
+
+| Operation | Description | Example |
+|-----------|-------------|---------|
+| `Equal` | Exact match | `value: "production"` |
+| `NotEqual` | Does not match | `value: "development"` |
+| `HasPrefix` | Starts with | `value: "prod-"` |
+| `NotHasPrefix` | Does not start with | `value: "test-"` |
+| `HasSuffix` | Ends with | `value: "-prod"` |
+| `NotHasSuffix` | Does not end with | `value: "-test"` |
+| `Contains` | Contains substring | `value: "production"` |
+| `NotContains` | Does not contain | `value: "test"` |
+| `Match` | Regex match | `value: "^prod-.*-v[0-9]+$"` |
+| `NotMatch` | Does not match regex | `value: "^test-.*"` |
+
+## Guest Family Types
+
+When matching based on guest operating system family, the following values are supported:
+
+- `Darwin`: macOS guests
+- `Linux`: Linux-based guests
+- `Netware`: NetWare guests
+- `Other`: Other guest types
+- `Solaris`: Solaris guests
+- `Windows`: Windows guests
+
+## Best Practices
+
+### Policy Naming
+- Use descriptive names that indicate the policy's purpose
+- Include environment or tier indicators (e.g., `production-compute-policy`)
+- Be consistent with naming conventions across namespaces
+
+### Match Criteria
+- Keep match criteria as specific as needed but not overly complex
+- Use labels for flexible, user-controllable matching
+- Use image and guest properties for system-enforced matching
+
+### Enforcement Modes
+- Use mandatory policies for namespace-wide requirements
+- Use optional policies for workload-specific optimizations
+- Document which policies are available and their purposes
+
+### Policy Updates
+- Monitor the `generation` field in VM status to track policy versions
+- Test policy changes with PolicyEvaluation before applying
+- Consider the impact on existing VMs when updating policies
+
+## Troubleshooting
+
+### Policies Not Applied
+- Check the policy's `enforcementMode` - optional policies need explicit reference
+- Verify match criteria using a PolicyEvaluation resource
+- Ensure the policy exists in the same namespace as the VM
+
+### Policy Conflicts
+- Review all mandatory policies in the namespace
+- Check for overlapping match criteria
+- Use PolicyEvaluation to test combinations
+
+### Tag Activation
+- Verify TagPolicy resources contain valid vSphere tag UUIDs
+- Ensure referenced TagPolicy resources exist
+- Check vSphere permissions for tag application
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -139,6 +139,7 @@ nav:
     - Guest Customization: concepts/workloads/guest.md
     - VirtualMachine Placement: concepts/workloads/vm-placement.md
     - VirtualMachineGroup: concepts/workloads/vm-group.md
+    - Policies: concepts/workloads/vsphere-policies.md
   - Images:
     - concepts/images/README.md
     - VirtualMachineImage: concepts/images/vm-image.md
Original file line number	Diff line number	Diff line change
Expand Up		@@ -17,3 +17,4 @@ This section provides information about workload resources, such as:
		In addition to the workload resources themselves, there is documentation related to broader topics related to workloads:

		* [Customizing a Guest](./guest.md)
		* [vSphere Policies](./vsphere-policies.md)