diff --git a/docs/docs-content/automation/palette-cli/commands/vmo.md b/docs/docs-content/automation/palette-cli/commands/vmo.md new file mode 100644 index 0000000000..1570b65571 --- /dev/null +++ b/docs/docs-content/automation/palette-cli/commands/vmo.md @@ -0,0 +1,156 @@ +--- +sidebar_label: "VMO" +title: "VMO" +description: "Reference resource for the vmo command." +hide_table_of_contents: false +sidebar_position: 60 +tags: ["palette-cli"] +--- + +Use the `vmo` command to migrate Virtual Machines (VMs) and import and deploy vSphere Open Virtual Appliances (OVAs). +The VMs can then be used with the Virtual Machine Orchestrator (VMO). + +## Subcommands + +- [`deploy-ova`](#deploy-ova) - Deploy an imported vSphere OVA. This command requires you to have an OVA deployment + file. If you do not have one, you can generate an OVA with the `import-ova` subcommand. + +- [`import-ova`](#import-ova) - Import a vSphere OVA. This subcommand will generate an OVA deployment configuration + file. The configuration can then be deployed using the `deploy-ova` subcommand. + +- [`migrate-vm`](#migrate-vm) - Migrate one or more VMware vSphere VMs to Palette VMO. + +## Prerequisites + +- A Healthy VMO cluster. Refer to the [Create a VMO Profile](../../../vm-management/create-vmo-profile.md) for further + guidance. +- One or more VMs hosted in VMware vSphere. Only VMs whose operating systems are included under + [`virt-v2v` supported guest systems](https://libguestfs.org/virt-v2v-support.1.html) can be migrated. + +## Limitations + +- You can only use the `vmo` subcommand with VMs hosted in VMware vSphere. + +## Deploy OVA + +Use the `deploy-ova` subcommand to deploy an imported vSphere OVA to Palette VMO. The following flags are supported by +the `deploy-ova` subcommand. + +| **Short Flag** | **Long Flag** | **Description** | **Type** | +| -------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| `-f` | `--config-file` | Specifies an OVA configuration file. | string | +| `-o` | `--config-only` | Update the OVA configuration file only, without proceeding with the deployment. This flag requires the `--config-file` be specified. | boolean | +| `-s` | `--silent` | Perform a silent OVA deployment. This flag requires the `--config-file` be specified. | boolean | +| `-h` | `--help` | Help for the `deploy-ova` subcommand. | - | + +### Examples + +Deploy a vSphere OVA previously imported to Palette VMO in interactive mode. + +```shell +palette vmo deploy-ova --config-file ~/.palette/vmo/vms/my-ova-name/my-ova-name.yaml +``` + +Update the OVA configuration file without proceeding with the depoyment. + +```shell +palette vmo import-ova --config-file ~/.palette/vmo/vms/my-ova-name/my-ova-name.yaml --config-only +``` + +Deploy a vSphere OVA previously imported to Palette VMO in interactive mode silently, without blocking the terminal. + +```shell +palette vmo deploy-ova --config-file ~/.palette/vmo/vms/my-ova-name/my-ova-name.yaml --silent +``` + +## Import OVA + +Use the `import-ova` subcommand to import a vSphere OVA to Palette VMO. The following flags are supported by the +`import-ova` subcommand. The OVA will be converted to the QCOW2 virtual disk storage format. This subcommand generates +an OVA deployment configuration file. You can then either directly upload the imported image to a `DataVolume` or upload +it a Docker image registry. + +| **Short Flag** | **Long Flag** | **Description** | **Type** | +| -------------- | ---------------- | ----------------------------------------------------------------------------- | -------- | +| `-f` | `--config-file` | Specifies an OVA configuration file. | string | +| `-o` | `--config-only` | Generate the OVA configuration file only, without proceeding with the import. | boolean | +| | `--skip-convert` | Skip OVA conversion to QCOW2 format. | boolean | +| | `--skip-image` | Skip VM image upload. | boolean | +| `-h` | `--help` | Help for the `deploy-ova` subcommand. | - | + +### Examples + +Import a vSphere OVA to Palette VMO in interactive mode. + +```shell +palette vmo import-ova +``` + +Create a configuration file for the OVA import without proceeding with the import. + +```shell +palette vmo import-ova --config-only +``` + +Import an OVA to Palette VMO using a configuration file. The configuration file is generated using the `--config-only` +flag. + +```shell hideCliboard +palette vmo import-ova --config-file ~/.palette/vmo/vms/my-ova-name/my-ova-name.yaml +``` + +Import an OVA to Palette VMO without converting it to QCOW2 format. + +```shell hideCliboard +palette vmo import-ova --skip-convert +``` + +Import an OVA to Palette VMO without uploading it. + +```shell hideCliboard +palette vmo import-ova --skip-image +``` + +## Migrate VM + +Use the `migrate-vm` subcommand to migrate one or more VMs from VMware vSphere to Palette VMO. The following flags are +supported by the `migrate-vm` subcommand. The migration consists of two phases. First, all guest disks are transferred +to Persistent Volumes (PVs) in K8s using KubeVirt CDI and VMware Virtual Disk Development Kit (VDDK). Then, the guest OS +on the root disk is made bootable and drivers are installed using [virt-v2v](https://libguestfs.org/virt-v2v.1.html). +Refer to the +[Migrate a VM to a VMO cluster](../../../vm-management/create-manage-vm/advanced-topics/migrate-vm-kubevirt.md) guide +for further details on migrating a vSphere VM to Palette VMO. + +| **Short Flag** | **Long Flag** | **Description** | **Type** | +| -------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------- | +| `-f` | `--config-file` | Specifies a configuration file for the VM migration. | string | +| `-o` | `--config-only` | Generate the migration configuration file only, without proceeding with the migration. | boolean | +| `-p` | `--update-passwords` | Update the vSphere and ESXi passwords saved in the configuration file. This flag requires the `--config-file` to be specified. | boolean | +| `-h` | `--help` | Help for the `migrate-vm` subcommand. | - | + +### Examples + +Migrate a VM to Palette VMO in interactive mode. + +```shell +palette vmo migrate-vm +``` + +Create a configuration file for the VM migration without proceeding with the migration. + +```shell +palette vmo migrate-vm --config-only +``` + +Migrate a VM using a configuration file. The configuration file is generated using the `--config-only` flag. + +```shell hideCliboard +palette vmo migrate-vm --config-file ~/.palette/vmo/migrations/migration-123/config.yaml +``` + +Update the passwords of an VM migration using a configuration file. The configuration file is generated using the +`--config-only` flag. + +```shell hideCliboard +palette vmo migrate-vm --config-file ~/.palette/vmo/migrations/migration-123/config.yaml --update-passwords +``` diff --git a/docs/docs-content/vm-management/create-manage-vm/advanced-topics/migrate-vm-kubevirt.md b/docs/docs-content/vm-management/create-manage-vm/advanced-topics/migrate-vm-kubevirt.md new file mode 100644 index 0000000000..07147eafc4 --- /dev/null +++ b/docs/docs-content/vm-management/create-manage-vm/advanced-topics/migrate-vm-kubevirt.md @@ -0,0 +1,135 @@ +--- +sidebar_label: "Migrate a VM to a VMO cluster" +title: "Migrate a VM to a VMO cluster" +description: "Learn how to migrate VMs to Palette VMO using the Palette CLI." +icon: " " +hide_table_of_contents: false +sidebar_position: 40 +tags: ["vmo", "palette-cli"] +--- + +During large scale Kubernetes adoptions, workloads are often rehosted or migrated instead of being redeployed from +scratch. This process allows system administrators to copy the application, together with its data, to a Kubernetes +cluster. However, the migration of VMs can be time consuming if done manually, so it is often automated with open-source +tools such as [Forklift](https://github.com/kubev2v/forklift). + +The [Palette CLI](../../../automation/palette-cli/palette-cli.md) provides the ability to migrate Virtual Machines (VMs) +from VMware vSphere to Palette VMO. + +## Limitations + +- You can only migrate VMs hosted in VMware vSphere. +- Only VMs whose operating systems are included under + [`virt-v2v` supported guest systems](https://libguestfs.org/virt-v2v-support.1.html) can be migrated. + +## Prerequisites + +- A Healthy VMO cluster. Refer to the [Create a VMO Profile](../../create-vmo-profile.md) for further guidance. +- A VMware vSphere user account with the necessary permissions to manage the VMs you want to migrate. + - Migration can optionally accelerated by providing credentials for the ESXi hosts where the VMs reside. +- One or more VMs hosted in VMware vSphere. Only VMs whose operating systems are included under + [`virt-v2v` supported guest systems](https://libguestfs.org/virt-v2v-support.1.html) can be migrated. + - The VMs must be powered off before migration. + - Ensure that VMs operating Windows are shut down at the virtualized OS level. + - If you are migrating more than one VM in the same plan, they must all share the same network. +- The Palette CLI installed and setup. Refer to the + [Installation](../../../automation/palette-cli/install-palette-cli.md) guide for further details. +- The kubectl command-line tool should also be installed. Refer to the + [kubectl installation](https://kubernetes.io/docs/tasks/tools/install-kubectl/) guide to learn more. + +:::warning + +The VMO cluster must have access to VMware and the VM you want to migrate. The Palette CLI must have access to both the +VMO cluster and the machines to be migrated. + +::: + +## Migrate VMware vSphere VMs + +1. Download the [Kubeconfig](../../../clusters/cluster-management/kubeconfig.md) file of the VMO cluster to the host + where the Palette CLI is installed. + +2. Open a terminal window and set the environment variable `KUBECONFIG` to point to the file you downloaded. + + ```shell + export KUBECONFIG= + ``` + +3. Optionally, create a namespace where your VM will be migrated. We recommend that you migrate a VM to a dedicated + namespace. + + ```shell + kubectl create namespaces + ``` + +4. Execute the following command to start an interactive shell and begin the migration process to the cluster specified + by the `KUBECONFIG` variable. + + ```shell + palette vmo migrate-vm + ``` + + :::tip + + You can save your configuration to a file, allowing you to revise your configuration and perform the migration later. + + ```shell + palette vmo migrate-vm --config-only + ``` + + ::: + + The Palette CLI prompts you for information regarding the VM you want to migrate, vSphere environment, and resource + configurations. + + | **Parameter** | **Description** | **Values** | + | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | + | **Migration Source Type** | The hypervisor configured on your migration VM. | `vCenter` / `vCenter + ESXi host` | + | **Migration Name** | The name of your migration and its corresponding configuration files. A default name is generated by the Palette CLI. | | + | **Forklift Installation Type** | A cluster to be used for performing the migration. You can either choose to create a local cluster or use the destination cluster. [Forklift](https://github.com/kubev2v/forklift) is installed on the migration cluster. | `Local Kind Cluster` / `Destination Cluster` | + | **Install Forklift?** | Specify whether to install Forklift on the migration cluster. | `Y` / `n` | + | **Migration Namespace** | Namespace where the migration VM is created. The namespace must exist on the cluster. You can enter the namespace you created earlier or use the `default` namespace. | | + | **vSphere Endpoint** | Your vSphere endpoint. You can specify a Full Qualified Domain Name (FQDN) or an IP address. Make sure you specify the endpoint without the HTTP scheme `https://` or `http://`. Example: `vcenter.mycompany.com.` | | + | **vSphere Username (with domain)** | Your vSphere account username. | | + | **vSphere Password** | Your vSphere account password. | | + | **Allow Insecure Connection (Bypass x509 Verification)** | Enabling this option bypasses x509 CA verification. In production environments, enter `N` if using a custom registry with self-signed SSL certificates. Otherwise, enter `Y`. | `Y`/`n` | + | **Datacenter** | The vSphere data center of the VM to migrate. | | + | **Cluster** | The vSphere compute cluster of the VM to migrate. | | + | **ESXi Hypervisor** | The IP address of the node corresponding to the VM to migrate. If you have selected the `vCenter + ESXi host` migration source type, you will need to provide ESXi credentials. | | + | **VM** | The VM to migrate from the selected host. | | + | **Add Another VM?** | Indicate whether you want to select multiple VM from the vSphere environment. | `Y` / `n` | + | **Add Another Host?** | Indicate whether you would like to perform two migrations in the same configuration. | | + | **Destination Network Type** | The network that the VMs will be mapped to in the VMO cluster. | `pod` / `multus` | + | **Destination StorageClass** | The storage class on the destination that will be used to create the VM volumes. | | + | **Destination StorageClass Access Mode** | The configured access mode on the cluster storage class. | `ReadWriteOnce` / `ReadWriteMany` | + +5. The migration begins as soon as you complete the configuration. Execute the following command to watch the migration + status. Replace the `` placeholder with the migration name you have configured. + + ```shell + watch --interval 2 'kubectl --namespace konveyor-forklift get migrations.forklift.konveyor.io -migration' + ``` + + The migration with take approximately 20 minutes, depending on the size of the VM to migrate. Once the migration is + complete, the `watch` command will output the following. + + ```shell + Every 2.0s: kubectl --namespace konveyor-forklift get migrations.forklift.konveyor.io vmo-migration + + NAME READY RUNNING SUCCEEDED FAILED AGE + vmo-migration True True 18m + ``` + +## Validate + +1. Log into [Palette](https://console.spectrocloud.com). + +2. From the left **Main Menu**, select **Clusters**. Then, choose the VMO cluster that you migrated your VM to. The + **Overview** tab appears. + +3. Select the **Virtual Machines** tab. Then, select your migration namespace from the **Namespace** drop-down Menu. + Your migrated VM appears. + +4. Click on the **three-dot Menu** and select **Start**. Your VM is now ready to use. + + ![Start migrated VM](/migrate-vm-kubevirt-guide/vm-management_create-manage-vm_migrate-vm-kubevirt_start_migrated_vm.webp) diff --git a/docs/docs-content/vm-management/vm-management.md b/docs/docs-content/vm-management/vm-management.md index d19fa9070d..a7ed3397a6 100644 --- a/docs/docs-content/vm-management/vm-management.md +++ b/docs/docs-content/vm-management/vm-management.md @@ -54,4 +54,6 @@ and permissions for your VMs. - [Advanced Topics](./create-manage-vm/advanced-topics/advanced-topics.md) +- [Migrate a VM to a VMO cluster](./create-manage-vm/advanced-topics/migrate-vm-kubevirt.md) + - [RBAC](./rbac/rbac.md) diff --git a/static/assets/docs/images/migrate-vm-kubevirt-guide/vm-management_create-manage-vm_migrate-vm-kubevirt_start_migrated_vm.webp b/static/assets/docs/images/migrate-vm-kubevirt-guide/vm-management_create-manage-vm_migrate-vm-kubevirt_start_migrated_vm.webp new file mode 100644 index 0000000000..80b6a77864 Binary files /dev/null and b/static/assets/docs/images/migrate-vm-kubevirt-guide/vm-management_create-manage-vm_migrate-vm-kubevirt_start_migrated_vm.webp differ