📖 Add vim.vmware.com partner integration guide - #1792
Draft
faisalabujabal wants to merge 2 commits into
Draft
Conversation
Author external/vim/doc/integration-guide.md, the consumer-facing contract for the vim.vmware.com APIs (vmop-3739 / Story S2 of vmop-3331): capability gate, the four CRDs and their name conventions, the reconcile pipeline, the ConfigTarget capability surface, VirtualMachineConfigPolicy syncMode and field ownership, both policy enforcement points, a worked denial example, and the CEL/webhook rules a caller will hit. The guide is written against the merged end state of the config policy work, including the enforcement, sync controller, policy webhook, and CEL-migration changes still in review. Writing it surfaced three claims in the sibling docs that the merged code contradicts, corrected here rather than propagated: - controller-workflows.md derived cluster MoIDs from the Zone's spec.namespace.poolMoIDs. Both the Zone controller and the policy sync controller use spec.managedVMs.clusterMoIDs. - deploying-a-vm.md used cluster-1 as a ConfigTarget name. A CEL rule on the CRD requires ^domain-c[0-9]+$, so that example would be rejected by the API server. - deploying-a-vm.md described admission as consulting every zone policy in the namespace and denying only if no zone permits the VM. Enforcement resolves exactly one policy, named after the VM's assigned zone label, and an unplaced VM is not enforced at all. Its worked example is rewritten accordingly. Also fixes the README's link to a doc/environment_browser.md that does not exist, and records in tasks.md that two bullets of T020's original scope (enriched sriov, per-host PropertyCollector iteration) describe a design retired by Story S4's closure.
Three accuracy fixes to the integration guide, each verified against source rather than inferred: - The worked example's denial text quoted invented message tails. Replaced with the real ErrMemoryViolation and ErrExtraConfigViolation strings, and with the real response shape: webhooks/common/response.go returns HTTP 422 with every field error joined into one reason string, not one line each. - status.defaultHardwareVersion and status.vMotionBandwidth are never written by pkg/util/vsphere/configtarget. Moved out of the populated-field list and into the same "do not build on this yet" warning that already covered status.sriov. - Reverted an unverified 422 to 403 edit in deploying-a-vm.md. 422 was correct.
Minimum allowed line rate is |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do, and why is it needed?
Authors
external/vim/doc/integration-guide.md, the partner-facing integration doc for thevim.vmware.comAPIs (vmop-3739, Story S2 of vmop-3331). The audience is teams consuming these APIs from outside VM Operator — UI/CLI surfaces, placement and quota tooling — so it is written as a contract rather than a tour: what you can rely on, what is not populated yet, and what will reject your request.Contents:
supports_vm_service_vm_config_policy), and why CRD presence is not a signal the feature is on.metadata.nameconventions, who writes them, what they derive from.Ready-gating caveats a consumer needs.ConfigTarget.statuscapability surface, includingmaxHardwareVersionand an explicit "do not build onstatus.sriov, it is empty today" warning.VirtualMachineConfigPolicy:syncModesemantics, which spec fields are synced vs. administrator-owned, the multi-cluster intersection merge, theMin > Maxrefusal, and everyReadycondition reason.extraConfigmatching semantics, and what a denial looks like on each path.Written against the merged end state of the stack. The guide describes behavior from five PRs still in review, so it should merge after them:
spec.hardwareVersions, theVirtualMachineConfigPolicyVerifiedconditionVirtualMachineConfigPolicyvalidation webhookReadyreasonsconfigtarget/virtualmachineconfigoptionswebhooks removedVirtualMachineGuestOptionsGC semanticsMarked draft for that reason. Nothing here needs to change if those merge as-is; if #1738's enforcement shifts in review, the "Enforcement" section is one contiguous block to amend.
Three corrections to the sibling docs
Writing this surfaced claims in
controller-workflows.mdanddeploying-a-vm.mdthat the merged code contradicts. Fixed here rather than propagated into a new partner-facing doc:spec.namespace.poolMoIDs. The merged Zone controller and the sync controller in Add VirtualMachineConfigPolicy sync controller #1784 both usespec.managedVMs.clusterMoIDs. Fixed in the mermaid node text and in the prose of both controller sections.ConfigTargetname examples.deploying-a-vm.mdusedcluster-1/cluster-2. vmop-3766: Move ConfigTarget/VirtualMachineConfigOptions validation to CEL #1785 adds a CEL rule requiring^domain-c[0-9]+$, so those examples would be rejected by the API server. Nowdomain-c52.deploying-a-vm.mdstated that admission lists everyVirtualMachineConfigPolicyin the namespace and denies only if no zone permits the VM. ✨ Enforce VirtualMachineConfigPolicy in webhook and power-on reconcile #1738 does the opposite: it resolves exactly one policy, named after the VM's assignedtopology.kubernetes.io/zonelabel, via a singleGet, and a VM with no zone label is not enforced at all. Its worked example and sequence diagram are rewritten to match, and the guide calls out that any-zone reasoning is the consumer's job, not admission's.Also fixes
external/vim/README.md, which linked to adoc/environment_browser.mdthat has never existed, and now links the three real pages.Which issue(s) is/are addressed by this PR?
Addresses vmop-3739.
Are there any special notes for your reviewer:
pkg/,api/, ortest/changes.mkdocs.ymlsetsdocs_dir: docswith no include/monorepo plugin, so nothing underexternal/vim/doc/is reachable by the RTD build today — that is true of all three pages there, not just this one. Publishing means relocating the tree intodocs/, adding a build dependency, or symlinking: a docs-site structural decision worth its own change. T021's other half (review by PM and a downstream consumer team) is a process step no PR can close.tasks.mdrecords both.sriov" and "per-host iteration inside theConfigTargetcontroller (PropertyCollector RPC strategy, partial-failure handling)". Per T066b/T066c and the Story S4 closure, there is no host enumeration, noPropertyCollectorcall, andstatus.sriovships empty pending spec 003. The guide says so plainly and warns consumers off the field;tasks.mdrecords the divergence.Please add a release note if necessary: