Skip to content

Commit a4aa4d4

Browse files
akutzdilyar85
akutz
and
dilyar85
authored
docs: vSphere policy documentation (#1177)
This patch adds documentation for the vSphere policy API changes introduced in #1123. Co-authored-by: Sai Diliyaer <[email protected]>
1 parent 5cdb882 commit a4aa4d4

File tree

4 files changed

+366
-0
lines changed

4 files changed

+366
-0
lines changed

‎docs/concepts/workloads/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,4 @@ This section provides information about workload resources, such as:
1717
In addition to the workload resources themselves, there is documentation related to broader topics related to workloads:
1818

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

‎docs/concepts/workloads/vm.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,16 @@ kubectl get -n <NAMESPACE> encryptionclass
9999

100100
For more information on `EncryptionClass` resources, please see the [Encryption](#encryption) section below.
101101

102+
### vSphere Policies
103+
104+
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:
105+
106+
```shell
107+
kubectl get -n <NAMESPACE> computepolicy
108+
```
109+
110+
For more information on vSphere policies and how to apply them to VMs, please see the [vSphere Policies](#vsphere-policies-1) section below.
111+
102112
## Hardware
103113

104114
### Configuration
@@ -143,6 +153,7 @@ It is possible to update parts of an existing `VirtualMachine` resource. Some fi
143153
| `spec.imageName` | The name of the `VirtualMachineImage` that supplies the VM's disk(s) | ✗ | ✗ | _NA_ |
144154
| `spec.className` | The name of the `VirtualMachineClass` that supplies the VM's virtual hardware | ✓ | ✓ | _NA_ |
145155
| `spec.powerState` | The VM's desired power state | ✓ | ✓ | _NA_ |
156+
| `spec.policies` | The list of vSphere policies to apply to the VM | ✓ | ✓ | _NA_ |
146157
| `metadata.labels.topology.kubernetes.io/zone` | The desired availability zone in which to schedule the VM | x | x | ✓ |
147158
| `spec.hardware.cdrom[].name` | The name of the CD-ROM device to mount ISO in the VM | x | ✓ | _NA_ |
148159
| `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
10121023

10131024
For more information on the ISO VM workflow, please refer to the [Deploy a VM with ISO](../../../tutorials/deploy-vm/iso/) tutorial.
10141025

1026+
## vSphere Policies
1027+
1028+
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.
1029+
1030+
### Configuration
1031+
1032+
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:
1033+
1034+
```yaml
1035+
apiVersion: vmoperator.vmware.com/v1alpha5
1036+
kind: VirtualMachine
1037+
metadata:
1038+
name: my-vm
1039+
namespace: my-namespace
1040+
spec:
1041+
className: my-vm-class
1042+
imageName: vmi-0a0044d7c690bcbea
1043+
storageClass: my-storage-class
1044+
policies:
1045+
- apiVersion: vsphere.policy.vmware.com/v1alpha1
1046+
kind: ComputePolicy
1047+
name: my-compute-policy
1048+
```
1049+
1050+
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.
1051+
1052+
### Status
1053+
1054+
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:
1055+
1056+
```yaml
1057+
status:
1058+
policies:
1059+
- apiVersion: vsphere.policy.vmware.com/v1alpha1
1060+
kind: ComputePolicy
1061+
name: my-compute-policy
1062+
generation: 2
1063+
- apiVersion: vsphere.policy.vmware.com/v1alpha1
1064+
kind: ComputePolicy
1065+
name: namespace-default-policy
1066+
generation: 1
1067+
```
1068+
1069+
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.
1070+
1071+
### Policy Types
1072+
1073+
#### ComputePolicy
1074+
1075+
A `ComputePolicy` defines compute-related policies for VMs, such as placement rules, resource allocations, and operational constraints. These policies can be:
1076+
1077+
- **Mandatory**: Automatically applied to VMs based on match criteria
1078+
- **Optional**: Must be explicitly referenced in the VM's `spec.policies` field
1079+
1080+
The policy may include references to `TagPolicy` objects that define vSphere tags to be applied to activate the policy.
1081+
1082+
#### TagPolicy
1083+
1084+
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.
1085+
1086+
### Policy Evaluation
1087+
1088+
When a VM is created or updated, the system evaluates which policies should be applied based on:
1089+
1090+
1. **Explicit policies**: Those listed in `spec.policies`
1091+
2. **Mandatory policies**: Those with `spec.enforcementMode: Mandatory` that match the VM
1092+
3. **Match criteria**: Policies can specify match criteria based on:
1093+
- Workload labels
1094+
- Image name and labels
1095+
- Guest operating system (ID and family)
1096+
- Workload kind (Pod or VirtualMachine)
1097+
1098+
The evaluation results are reflected in `status.policies`, showing all policies that have been applied to the VM.
1099+
10151100
## Affinity
10161101

10171102
The optional field `spec.affinity` that may be used to define a set of affinity/anti-affinity scheduling rules for VMs.

‎docs/concepts/workloads/vsphere-policies.md‎

Lines changed: 279 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
# vSphere Policies
2+
3+
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.
4+
5+
## Overview
6+
7+
The vSphere Policy APIs introduce three main resource types:
8+
9+
- **ComputePolicy**: Defines compute-related policies for workloads
10+
- **TagPolicy**: Defines vSphere tags to be applied to workloads
11+
- **PolicyEvaluation**: Evaluates which policies should apply to a workload
12+
13+
These resources work together to provide flexible, declarative policy management that can be applied either explicitly or automatically based on matching criteria.
14+
15+
## ComputePolicy
16+
17+
A `ComputePolicy` resource defines compute-related policies that control various aspects of VM behavior, placement, and resource allocation in vSphere.
18+
19+
### Specification
20+
21+
```yaml
22+
apiVersion: vsphere.policy.vmware.com/v1alpha1
23+
kind: ComputePolicy
24+
metadata:
25+
name: production-policy
26+
namespace: my-namespace
27+
spec:
28+
description: "Production workload policy"
29+
policyID: "vsphere-policy-123" # Optional vSphere policy ID
30+
enforcementMode: Mandatory # Or Optional
31+
match:
32+
workload:
33+
labels:
34+
- key: tier
35+
operator: In
36+
values:
37+
- production
38+
kind: VirtualMachine
39+
tags:
40+
- production-tag-policy
41+
```
42+
43+
### Enforcement Modes
44+
45+
ComputePolicy resources support two enforcement modes:
46+
47+
#### Mandatory Policies
48+
49+
- Automatically applied to all matching workloads in the namespace
50+
- Cannot be overridden or removed by users
51+
- Applied based on the `match` criteria
52+
- If no `match` is specified, applies to all workloads in the namespace
53+
54+
#### Optional Policies
55+
56+
- Must be explicitly referenced in a VM's `spec.policies` field
57+
- Users can choose whether to apply these policies
58+
- Provide flexibility for workload-specific requirements
59+
60+
### Match Specifications
61+
62+
The `match` field allows sophisticated matching based on:
63+
64+
#### Workload Properties
65+
- **Labels**: Match based on workload labels using label selector requirements
66+
- **Kind**: Filter by workload type (`Pod` or `VirtualMachine`)
67+
- **Guest OS**: Match based on guest ID or guest family
68+
69+
#### Image Properties
70+
- **Name**: Match based on image name patterns
71+
- **Labels**: Match based on image labels
72+
73+
#### Boolean Operations
74+
- **And**: All conditions must match (default)
75+
- **Or**: At least one condition must match
76+
77+
Example of complex matching:
78+
79+
```yaml
80+
spec:
81+
match:
82+
op: Or
83+
match:
84+
- workload:
85+
labels:
86+
- key: tier
87+
operator: In
88+
values: [production]
89+
- image:
90+
name:
91+
op: HasPrefix
92+
value: "production-"
93+
```
94+
95+
## TagPolicy
96+
97+
A `TagPolicy` resource defines vSphere tags that should be applied to workloads. These are typically referenced by ComputePolicy objects.
98+
99+
### Specification
100+
101+
```yaml
102+
apiVersion: vsphere.policy.vmware.com/v1alpha1
103+
kind: TagPolicy
104+
metadata:
105+
name: production-tag-policy
106+
namespace: my-namespace
107+
spec:
108+
tags:
109+
- "urn:vmomi:InventoryServiceTag:12345678-1234-1234-1234-123456789abc:GLOBAL"
110+
- "urn:vmomi:InventoryServiceTag:87654321-4321-4321-4321-cba987654321:GLOBAL"
111+
```
112+
113+
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.
114+
115+
## PolicyEvaluation
116+
117+
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.
118+
119+
### Specification
120+
121+
```yaml
122+
apiVersion: vsphere.policy.vmware.com/v1alpha1
123+
kind: PolicyEvaluation
124+
metadata:
125+
name: test-evaluation
126+
namespace: my-namespace
127+
spec:
128+
workload:
129+
labels:
130+
tier: production
131+
guest:
132+
guestID: ubuntu64Guest
133+
guestFamily: Linux
134+
image:
135+
name: ubuntu-22.04
136+
labels:
137+
os: ubuntu
138+
policies:
139+
- apiVersion: vsphere.policy.vmware.com/v1alpha1
140+
kind: ComputePolicy
141+
name: specific-policy
142+
```
143+
144+
### Status
145+
146+
After evaluation, the status will contain the list of policies that would apply:
147+
148+
```yaml
149+
status:
150+
policies:
151+
- apiVersion: vsphere.policy.vmware.com/v1alpha1
152+
kind: ComputePolicy
153+
name: production-policy
154+
observedGeneration: 2
155+
tags:
156+
- "urn:vmomi:InventoryServiceTag:12345678-1234-1234-1234-123456789abc:GLOBAL"
157+
- apiVersion: vsphere.policy.vmware.com/v1alpha1
158+
kind: ComputePolicy
159+
name: namespace-default
160+
observedGeneration: 1
161+
conditions:
162+
- type: Ready
163+
status: "True"
164+
```
165+
166+
## Applying Policies to VirtualMachines
167+
168+
### Explicit Application
169+
170+
Optional policies can be explicitly applied to a VM using the `spec.policies` field:
171+
172+
```yaml
173+
apiVersion: vmoperator.vmware.com/v1alpha5
174+
kind: VirtualMachine
175+
metadata:
176+
name: my-vm
177+
namespace: my-namespace
178+
spec:
179+
className: my-vm-class
180+
imageName: ubuntu-22.04
181+
storageClass: my-storage-class
182+
policies:
183+
- apiVersion: vsphere.policy.vmware.com/v1alpha1
184+
kind: ComputePolicy
185+
name: performance-policy
186+
- apiVersion: vsphere.policy.vmware.com/v1alpha1
187+
kind: ComputePolicy
188+
name: compliance-policy
189+
```
190+
191+
### Automatic Application
192+
193+
Mandatory policies are automatically applied based on their match criteria. The VM's status will reflect all applied policies:
194+
195+
```yaml
196+
status:
197+
policies:
198+
- apiVersion: vsphere.policy.vmware.com/v1alpha1
199+
kind: ComputePolicy
200+
name: performance-policy
201+
generation: 3
202+
- apiVersion: vsphere.policy.vmware.com/v1alpha1
203+
kind: ComputePolicy
204+
name: compliance-policy
205+
generation: 1
206+
- apiVersion: vsphere.policy.vmware.com/v1alpha1
207+
kind: ComputePolicy
208+
name: namespace-mandatory-policy
209+
generation: 2
210+
```
211+
212+
The `generation` field indicates which version of the policy was applied, helping track when policies need to be re-evaluated.
213+
214+
## Match Operations
215+
216+
The policy matching system supports various string and pattern matching operations:
217+
218+
| Operation | Description | Example |
219+
|-----------|-------------|---------|
220+
| `Equal` | Exact match | `value: "production"` |
221+
| `NotEqual` | Does not match | `value: "development"` |
222+
| `HasPrefix` | Starts with | `value: "prod-"` |
223+
| `NotHasPrefix` | Does not start with | `value: "test-"` |
224+
| `HasSuffix` | Ends with | `value: "-prod"` |
225+
| `NotHasSuffix` | Does not end with | `value: "-test"` |
226+
| `Contains` | Contains substring | `value: "production"` |
227+
| `NotContains` | Does not contain | `value: "test"` |
228+
| `Match` | Regex match | `value: "^prod-.*-v[0-9]+$"` |
229+
| `NotMatch` | Does not match regex | `value: "^test-.*"` |
230+
231+
## Guest Family Types
232+
233+
When matching based on guest operating system family, the following values are supported:
234+
235+
- `Darwin`: macOS guests
236+
- `Linux`: Linux-based guests
237+
- `Netware`: NetWare guests
238+
- `Other`: Other guest types
239+
- `Solaris`: Solaris guests
240+
- `Windows`: Windows guests
241+
242+
## Best Practices
243+
244+
### Policy Naming
245+
- Use descriptive names that indicate the policy's purpose
246+
- Include environment or tier indicators (e.g., `production-compute-policy`)
247+
- Be consistent with naming conventions across namespaces
248+
249+
### Match Criteria
250+
- Keep match criteria as specific as needed but not overly complex
251+
- Use labels for flexible, user-controllable matching
252+
- Use image and guest properties for system-enforced matching
253+
254+
### Enforcement Modes
255+
- Use mandatory policies for namespace-wide requirements
256+
- Use optional policies for workload-specific optimizations
257+
- Document which policies are available and their purposes
258+
259+
### Policy Updates
260+
- Monitor the `generation` field in VM status to track policy versions
261+
- Test policy changes with PolicyEvaluation before applying
262+
- Consider the impact on existing VMs when updating policies
263+
264+
## Troubleshooting
265+
266+
### Policies Not Applied
267+
- Check the policy's `enforcementMode` - optional policies need explicit reference
268+
- Verify match criteria using a PolicyEvaluation resource
269+
- Ensure the policy exists in the same namespace as the VM
270+
271+
### Policy Conflicts
272+
- Review all mandatory policies in the namespace
273+
- Check for overlapping match criteria
274+
- Use PolicyEvaluation to test combinations
275+
276+
### Tag Activation
277+
- Verify TagPolicy resources contain valid vSphere tag UUIDs
278+
- Ensure referenced TagPolicy resources exist
279+
- Check vSphere permissions for tag application

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,7 @@ nav:
139139
- Guest Customization: concepts/workloads/guest.md
140140
- VirtualMachine Placement: concepts/workloads/vm-placement.md
141141
- VirtualMachineGroup: concepts/workloads/vm-group.md
142+
- Policies: concepts/workloads/vsphere-policies.md
142143
- Images:
143144
- concepts/images/README.md
144145
- VirtualMachineImage: concepts/images/vm-image.md

0 commit comments

Comments
 (0)