From f7c83fbf46dc392bb55345c82dc823ab97674755 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Moritz=20R=C3=B6hrich?= Date: Tue, 3 Dec 2024 11:14:36 +0100 Subject: [PATCH 1/2] docs: document full VM import spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Document the full VM import spec, i.e. all properties of the VirtualMachineImport CRD by giving appropriate examples. - Put examples for OpenStack and VMWare in tabs - Fix whitespaces and long lines Signed-off-by: Moritz Röhrich --- docs/advanced/addons/vmimport.md | 132 ++++++++++++++++++++----------- 1 file changed, 85 insertions(+), 47 deletions(-) diff --git a/docs/advanced/addons/vmimport.md b/docs/advanced/addons/vmimport.md index c119a15891..50bd30b160 100644 --- a/docs/advanced/addons/vmimport.md +++ b/docs/advanced/addons/vmimport.md @@ -10,36 +10,50 @@ title: "VM Import" _Available as of v1.1.0_ -Beginning with v1.1.0, users can import their virtual machines from VMWare and OpenStack into Harvester. +Beginning with v1.1.0, users can import their virtual machines from VMWare and +OpenStack into Harvester. This is accomplished using the vm-import-controller addon. -To use the VM Import feature, users need to enable the vm-import-controller addon. +To use the VM Import feature, users need to enable the vm-import-controller +addon. ![](/img/v1.2/vm-import-controller/EnableAddon.png) -By default, vm-import-controller leverages ephemeral storage, which is mounted from /var/lib/kubelet. +By default, vm-import-controller leverages ephemeral storage, which is mounted +from /var/lib/kubelet. -During the migration, a large VM's node could run out of space on this mount, resulting in subsequent scheduling failures. +During the migration, a large VM's node could run out of space on this mount, +resulting in subsequent scheduling failures. -To avoid this, users are advised to enable PVC-backed storage and customize the amount of storage needed. According to the best practice, the PVC size should be twice the size of the largest VM being migrated. This is essential as the PVC is used as scratch space to download the VM, and convert the disks into raw image files. +To avoid this, users are advised to enable PVC-backed storage and customize the +amount of storage needed. According to the best practice, the PVC size should be +twice the size of the largest VM being migrated. This is essential as the PVC is +used as scratch space to download the VM, and convert the disks into raw image +files. ![](/img/v1.2/vm-import-controller/ConfigureAddon.png) ## vm-import-controller Currently, the following source providers are supported: + * VMWare * OpenStack ## API + The vm-import-controller introduces two CRDs. ### Sources + Sources allow users to define valid source clusters. For example: + + + ```yaml apiVersion: migration.harvesterhci.io/v1beta1 kind: VmwareSource @@ -59,7 +73,7 @@ The secret contains the credentials for the vCenter endpoint: ```yaml apiVersion: v1 kind: Secret -metadata: +metadata: name: vsphere-credentials namespace: default stringData: @@ -67,16 +81,19 @@ stringData: "password": "password" ``` -As part of the reconciliation process, the controller will log into vCenter and verify whether the `dc` specified in the source spec is valid. +As part of the reconciliation process, the controller will log into vCenter and +verify whether the `dc` specified in the source spec is valid. -Once this check is passed, the source is marked as ready and can be used for VM migrations. +Once this check is passed, the source is marked as ready and can be used for VM +migrations. ```shell -$ kubectl get vmwaresource.migration +$ kubectl get vmwaresource.migration NAME STATUS vcsim clusterReady ``` - + + For OpenStack-based source clusters, an example definition is as follows: ```yaml @@ -98,7 +115,7 @@ The secret contains the credentials for the OpenStack endpoint: ```yaml apiVersion: v1 kind: Secret -metadata: +metadata: name: devstack-credentials namespace: default stringData: @@ -109,58 +126,54 @@ stringData: "ca_cert": "pem-encoded-ca-cert" ``` -The OpenStack source reconciliation process attempts to list VMs in the project and marks the source as ready. +The OpenStack source reconciliation process attempts to list VMs in the project +and marks the source as ready. ```shell $ kubectl get opestacksource.migration NAME STATUS devstack clusterReady ``` + + ### VirtualMachineImport -The VirtualMachineImport CRD provides a way for users to define a source VM and map to the actual source cluster to perform VM export/import. + +The VirtualMachineImport CRD provides a way for users to define a source VM and +map to the actual source cluster to perform VM export/import. A sample VirtualMachineImport looks like this: + + + ```yaml apiVersion: migration.harvesterhci.io/v1beta1 kind: VirtualMachineImport metadata: name: alpine-export-test namespace: default -spec: +spec: virtualMachineName: "alpine-export-test" + folder: "/vm-foler" networkMapping: - - sourceNetwork: "dvSwitch 1" - destinationNetwork: "default/vlan1" - - sourceNetwork: "dvSwitch 2" - destinationNetwork: "default/vlan2" - sourceCluster: + - sourceNetwork: "dvSwitch 1" + destinationNetwork: "default/vlan1" + - sourceNetwork: "dvSwitch 2" + destinationNetwork: "default/vlan2" + sourceCluster: name: vcsim namespace: default kind: VmwareSource apiVersion: migration.harvesterhci.io/v1beta1 + storageClass: "harvester-longhorn" ``` -This will trigger the controller to export the VM named "alpine-export-test" on the VMWare source cluster to be exported, processed and recreated into the harvester cluster - -This can take a while based on the size of the virtual machine, but users should see `VirtualMachineImages` created for each disk in the defined virtual machine. - -The list of items in `networkMapping` will define how the source network interfaces are mapped to the Harvester Networks. - -If a match is not found, each unmatched network interface is attached to the default `managementNetwork`. - -Once the virtual machine has been imported successfully, the object will reflect the status: - -```shell -$ kubectl get virtualmachineimport.migration -NAME STATUS -alpine-export-test virtualMachineRunning -openstack-cirros-test virtualMachineRunning - -``` - -Similarly, users can define a VirtualMachineImport for an OpenStack source as well: +This will trigger the controller to export the VM named "alpine-export-test" +from the folder "/vm-folder" on the VMWare source cluster to be exported, +processed and recreated into the harvester cluster + + ```yaml apiVersion: migration.harvesterhci.io/v1beta1 @@ -168,20 +181,45 @@ kind: VirtualMachineImport metadata: name: openstack-demo namespace: default -spec: +spec: virtualMachineName: "openstack-demo" #Name or UUID for instance + folder: "/vm-folder" networkMapping: - - sourceNetwork: "shared" - destinationNetwork: "default/vlan1" - - sourceNetwork: "public" - destinationNetwork: "default/vlan2" - sourceCluster: + - sourceNetwork: "shared" + destinationNetwork: "default/vlan1" + - sourceNetwork: "public" + destinationNetwork: "default/vlan2" + sourceCluster: name: devstack namespace: default kind: OpenstackSource apiVersion: migration.harvesterhci.io/v1beta1 + storageClass: "harvester-longhorn" ``` -:::note -OpenStack allows users to have multiple instances with the same name. In such a scenario, users are advised to use the Instance ID. The reconciliation logic tries to perform a name-to-ID lookup when a name is used. -::: \ No newline at end of file +:::note +OpenStack allows users to have multiple instances with the same name. In such a +scenario, users are advised to use the Instance ID. The reconciliation logic +tries to perform a name-to-ID lookup when a name is used. +::: + + + +This can take a while based on the size of the virtual machine, but users should +see `VirtualMachineImages` created for each disk in the defined virtual machine. + +The list of items in `networkMapping` will define how the source network +interfaces are mapped to the Harvester Networks. + +If a match is not found, each unmatched network interface is attached to the +default `managementNetwork`. + +Once the virtual machine has been imported successfully, the object will reflect +the status: + +```shell +$ kubectl get virtualmachineimport.migration +NAME STATUS +alpine-export-test virtualMachineRunning +openstack-cirros-test virtualMachineRunning +``` From 438b3bb4ee0f5c4c92b20e745bf8b0f689b04ed2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Moritz=20R=C3=B6hrich?= Date: Thu, 5 Dec 2024 09:53:29 +0100 Subject: [PATCH 2/2] fix review suggestions on VM import docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Moritz Röhrich --- docs/advanced/addons/vmimport.md | 34 +++++++++++++++++--------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/advanced/addons/vmimport.md b/docs/advanced/addons/vmimport.md index 50bd30b160..15564752e3 100644 --- a/docs/advanced/addons/vmimport.md +++ b/docs/advanced/addons/vmimport.md @@ -169,9 +169,10 @@ spec: storageClass: "harvester-longhorn" ``` -This will trigger the controller to export the VM named "alpine-export-test" -from the folder "/vm-folder" on the VMWare source cluster to be exported, -processed and recreated into the harvester cluster +This CRD prompts the controller to export the VM named "alpine-export-test" +from the folder "/vm-folder", which is on the source VMWare cluster. +The virtual machine is expored, processed, and recreated into the Harvester +cluster. @@ -182,7 +183,7 @@ metadata: name: openstack-demo namespace: default spec: - virtualMachineName: "openstack-demo" #Name or UUID for instance + virtualMachineName: "openstack-demo" # Instance name or UUID folder: "/vm-folder" networkMapping: - sourceNetwork: "shared" @@ -198,25 +199,26 @@ spec: ``` :::note -OpenStack allows users to have multiple instances with the same name. In such a -scenario, users are advised to use the Instance ID. The reconciliation logic -tries to perform a name-to-ID lookup when a name is used. +The reconciliation logic attempts to perform a name-to-uuid lookup when an +instance name is used. +OpenStack allows the creation of multiple virtual machines with the same +instance name. In this scenario, you are advised to use the UUID. ::: -This can take a while based on the size of the virtual machine, but users should -see `VirtualMachineImages` created for each disk in the defined virtual machine. +This process can take a while depending on the virtual machine size, but you +should see `VirtualMachineImages` created for each disk in the defined virtual +machine. -The list of items in `networkMapping` will define how the source network -interfaces are mapped to the Harvester Networks. +The entries listed under `networkMapping` determine how the source network +interfaces are mapped to the Harvester networks. If no matches are found, each +unmatched network interface is attached to the default `managementNetwork`. -If a match is not found, each unmatched network interface is attached to the -default `managementNetwork`. - -Once the virtual machine has been imported successfully, the object will reflect -the status: +Once the virtual machine is imported successfully, the status of the object +changes to `virtualMachineRunning`. +Example: ```shell $ kubectl get virtualmachineimport.migration NAME STATUS