Skip to content

Commit f7c83fb

Browse files
m-ildefonsm-ildefons
committed
docs: document full VM import spec
- 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 <[email protected]>
1 parent 19cf378 commit f7c83fb

File tree

1 file changed

+85
-47
lines changed

1 file changed

+85
-47
lines changed

‎docs/advanced/addons/vmimport.md

Lines changed: 85 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -10,36 +10,50 @@ title: "VM Import"
1010

1111
_Available as of v1.1.0_
1212

13-
Beginning with v1.1.0, users can import their virtual machines from VMWare and OpenStack into Harvester.
13+
Beginning with v1.1.0, users can import their virtual machines from VMWare and
14+
OpenStack into Harvester.
1415

1516
This is accomplished using the vm-import-controller addon.
1617

17-
To use the VM Import feature, users need to enable the vm-import-controller addon.
18+
To use the VM Import feature, users need to enable the vm-import-controller
19+
addon.
1820

1921
![](/img/v1.2/vm-import-controller/EnableAddon.png)
2022

21-
By default, vm-import-controller leverages ephemeral storage, which is mounted from /var/lib/kubelet.
23+
By default, vm-import-controller leverages ephemeral storage, which is mounted
24+
from /var/lib/kubelet.
2225

23-
During the migration, a large VM's node could run out of space on this mount, resulting in subsequent scheduling failures.
26+
During the migration, a large VM's node could run out of space on this mount,
27+
resulting in subsequent scheduling failures.
2428

25-
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.
29+
To avoid this, users are advised to enable PVC-backed storage and customize the
30+
amount of storage needed. According to the best practice, the PVC size should be
31+
twice the size of the largest VM being migrated. This is essential as the PVC is
32+
used as scratch space to download the VM, and convert the disks into raw image
33+
files.
2634

2735
![](/img/v1.2/vm-import-controller/ConfigureAddon.png)
2836

2937
## vm-import-controller
3038

3139
Currently, the following source providers are supported:
40+
3241
* VMWare
3342
* OpenStack
3443

3544
## API
45+
3646
The vm-import-controller introduces two CRDs.
3747

3848
### Sources
49+
3950
Sources allow users to define valid source clusters.
4051

4152
For example:
4253

54+
<Tabs>
55+
<TabItem value="vmware" label="VMWare" default>
56+
4357
```yaml
4458
apiVersion: migration.harvesterhci.io/v1beta1
4559
kind: VmwareSource
@@ -59,24 +73,27 @@ The secret contains the credentials for the vCenter endpoint:
5973
```yaml
6074
apiVersion: v1
6175
kind: Secret
62-
metadata:
76+
metadata:
6377
name: vsphere-credentials
6478
namespace: default
6579
stringData:
6680
"username": "user"
6781
"password": "password"
6882
```
6983
70-
As part of the reconciliation process, the controller will log into vCenter and verify whether the `dc` specified in the source spec is valid.
84+
As part of the reconciliation process, the controller will log into vCenter and
85+
verify whether the `dc` specified in the source spec is valid.
7186

72-
Once this check is passed, the source is marked as ready and can be used for VM migrations.
87+
Once this check is passed, the source is marked as ready and can be used for VM
88+
migrations.
7389

7490
```shell
75-
$ kubectl get vmwaresource.migration
91+
$ kubectl get vmwaresource.migration
7692
NAME STATUS
7793
vcsim clusterReady
7894
```
79-
95+
</TabItem>
96+
<TabItem value="openstack" label="OpenStack">
8097
For OpenStack-based source clusters, an example definition is as follows:
8198

8299
```yaml
@@ -98,7 +115,7 @@ The secret contains the credentials for the OpenStack endpoint:
98115
```yaml
99116
apiVersion: v1
100117
kind: Secret
101-
metadata:
118+
metadata:
102119
name: devstack-credentials
103120
namespace: default
104121
stringData:
@@ -109,79 +126,100 @@ stringData:
109126
"ca_cert": "pem-encoded-ca-cert"
110127
```
111128

112-
The OpenStack source reconciliation process attempts to list VMs in the project and marks the source as ready.
129+
The OpenStack source reconciliation process attempts to list VMs in the project
130+
and marks the source as ready.
113131

114132
```shell
115133
$ kubectl get opestacksource.migration
116134
NAME STATUS
117135
devstack clusterReady
118136
```
137+
</TabItem>
138+
</Tabs>
119139

120140
### VirtualMachineImport
121-
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.
141+
142+
The VirtualMachineImport CRD provides a way for users to define a source VM and
143+
map to the actual source cluster to perform VM export/import.
122144

123145
A sample VirtualMachineImport looks like this:
124146

147+
<Tabs>
148+
<TabItem value="vmware" label="VMWare" default>
149+
125150
```yaml
126151
apiVersion: migration.harvesterhci.io/v1beta1
127152
kind: VirtualMachineImport
128153
metadata:
129154
name: alpine-export-test
130155
namespace: default
131-
spec:
156+
spec:
132157
virtualMachineName: "alpine-export-test"
158+
folder: "/vm-foler"
133159
networkMapping:
134-
- sourceNetwork: "dvSwitch 1"
135-
destinationNetwork: "default/vlan1"
136-
- sourceNetwork: "dvSwitch 2"
137-
destinationNetwork: "default/vlan2"
138-
sourceCluster:
160+
- sourceNetwork: "dvSwitch 1"
161+
destinationNetwork: "default/vlan1"
162+
- sourceNetwork: "dvSwitch 2"
163+
destinationNetwork: "default/vlan2"
164+
sourceCluster:
139165
name: vcsim
140166
namespace: default
141167
kind: VmwareSource
142168
apiVersion: migration.harvesterhci.io/v1beta1
169+
storageClass: "harvester-longhorn"
143170
```
144171

145-
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
146-
147-
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.
148-
149-
The list of items in `networkMapping` will define how the source network interfaces are mapped to the Harvester Networks.
150-
151-
If a match is not found, each unmatched network interface is attached to the default `managementNetwork`.
152-
153-
Once the virtual machine has been imported successfully, the object will reflect the status:
154-
155-
```shell
156-
$ kubectl get virtualmachineimport.migration
157-
NAME STATUS
158-
alpine-export-test virtualMachineRunning
159-
openstack-cirros-test virtualMachineRunning
160-
161-
```
162-
163-
Similarly, users can define a VirtualMachineImport for an OpenStack source as well:
172+
This will trigger the controller to export the VM named "alpine-export-test"
173+
from the folder "/vm-folder" on the VMWare source cluster to be exported,
174+
processed and recreated into the harvester cluster
175+
</TabItem>
176+
<TabItem value="openstack" label="OpenStack">
164177

165178
```yaml
166179
apiVersion: migration.harvesterhci.io/v1beta1
167180
kind: VirtualMachineImport
168181
metadata:
169182
name: openstack-demo
170183
namespace: default
171-
spec:
184+
spec:
172185
virtualMachineName: "openstack-demo" #Name or UUID for instance
186+
folder: "/vm-folder"
173187
networkMapping:
174-
- sourceNetwork: "shared"
175-
destinationNetwork: "default/vlan1"
176-
- sourceNetwork: "public"
177-
destinationNetwork: "default/vlan2"
178-
sourceCluster:
188+
- sourceNetwork: "shared"
189+
destinationNetwork: "default/vlan1"
190+
- sourceNetwork: "public"
191+
destinationNetwork: "default/vlan2"
192+
sourceCluster:
179193
name: devstack
180194
namespace: default
181195
kind: OpenstackSource
182196
apiVersion: migration.harvesterhci.io/v1beta1
197+
storageClass: "harvester-longhorn"
183198
```
184199

185-
:::note
186-
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.
187-
:::
200+
:::note
201+
OpenStack allows users to have multiple instances with the same name. In such a
202+
scenario, users are advised to use the Instance ID. The reconciliation logic
203+
tries to perform a name-to-ID lookup when a name is used.
204+
:::
205+
</TabItem>
206+
</Tabs>
207+
208+
This can take a while based on the size of the virtual machine, but users should
209+
see `VirtualMachineImages` created for each disk in the defined virtual machine.
210+
211+
The list of items in `networkMapping` will define how the source network
212+
interfaces are mapped to the Harvester Networks.
213+
214+
If a match is not found, each unmatched network interface is attached to the
215+
default `managementNetwork`.
216+
217+
Once the virtual machine has been imported successfully, the object will reflect
218+
the status:
219+
220+
```shell
221+
$ kubectl get virtualmachineimport.migration
222+
NAME STATUS
223+
alpine-export-test virtualMachineRunning
224+
openstack-cirros-test virtualMachineRunning
225+
```

0 commit comments

Comments
 (0)