docs(virtualization): add a VMware vSphere migration guide - #673
Draft
Andrei Kvapil (kvaps) wants to merge 4 commits into
Draft
docs(virtualization): add a VMware vSphere migration guide#673Andrei Kvapil (kvaps) wants to merge 4 commits into
Andrei Kvapil (kvaps) wants to merge 4 commits into
Conversation
Documents the forklift.cozystack.io import API: registering a vCenter connection, running an import, and what the result is. Sits beside the Proxmox guide, which covers the manual export-and-upload path. The pre-flight section is the part that matters. Every check in it corresponds to a failure observed on a live cluster, and each one surfaces late and names something other than its cause: a WaitForFirstConsumer storage class that deadlocks the transfer, an ESXi address colliding with the cluster Service CIDR so the VDDK connection is swallowed by service routing, a vCenter username missing its SSO domain reported as a wrong password, and a Forklift deployment serving a certificate its own rotated CA no longer matches. Assisted-By: Claude Signed-off-by: Andrei Kvapil <kvapss@gmail.com>
The VDDK is licensed software: VMware distributes it to registered users only and nobody may redistribute it, which is why Cozystack ships no image and the platform value starts empty. That leaves an administrator with a build step and no instructions for it. Covers where to get the kit, matching its version to vSphere, the Containerfile, building for linux/amd64 (an arm64 build pulls and then fails to execute on the workers), making a private registry pullable from the namespaces that need it, and a one-liner to confirm the pull before the first migration rather than during it. Also notes that Proxmox is not a provider the engine supports, so readers arriving from Proxmox are sent to the guide that applies to them instead of working through a vCenter setup that will not help. Assisted-By: Claude Signed-off-by: Andrei Kvapil <kvapss@gmail.com>
Leaves the page to describe the vSphere path on its own terms. Assisted-By: Claude Signed-off-by: Andrei Kvapil <kvapss@gmail.com>
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: trueThanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
The limitations section said a guest must already carry virtio drivers, which stopped being true when imports started defaulting to the SATA bus. It also understated the failure: a guest without virtio does not fail the import, it imports successfully and then does not boot. Adds the section the lab run showed was missing — why the bus is what it is, how to move to virtio once the drivers are in place, and what happens to a machine with more disks than the controller has ports. Assisted-By: Claude Signed-off-by: Andrei Kvapil <kvapss@gmail.com>
11 tasks
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.
Adds a migration guide for the
forklift.cozystack.ioimport API: register a vCenter connection, name the machines, getVMDiskandVMInstanceobjects.Placed in
next, not a released version: the API it documents is still in review (cozystack/cozystack#3931, design in cozystack/community#62). It should not be published until that lands.The guide is written from an end-to-end migration run against a real vSphere environment rather than from the API surface, which is why the pre-flight section is as long as it is. Each check in it corresponds to a failure that actually happened, and every one of them surfaces late and blames something else:
WaitForFirstConsumerstorage class deadlocks the transfer — and it is frequently the cluster default;There is also an administrator section on building the VDDK image. The kit is licensed software that VMware distributes to registered users only and nobody may redistribute, which is why Cozystack ships no image and the platform value starts empty — leaving an administrator with a build step and, until now, no instructions for it. It covers matching the kit version to vSphere, building for
linux/amd64(an arm64 build pulls and then fails to execute on the workers), making a private registry pullable from the namespaces that need it, and confirming the pull before the first migration rather than during it.The rest documents what the result actually is: the transfer is cold, so the source is powered off; nothing is copied twice; the imported VM starts
Halted; and the outputs outlive the task that produced them. Limitations are stated explicitly — vSphere only, cold only, one storage class per task, pod networking, no guest conversion — so nobody plans a Windows migration around a path that copies disks as-is.