OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Importing a VMware virtual machine or template

You can import a single VMware virtual machine or template into your OpenShift Container Platform cluster.

If you import a VMware template, the wizard creates a virtual machine based on the template.

Importing a VMware virtual machine or template is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.

The import process uses the VMware Virtual Disk Development Kit (VDDK) to copy the VMware virtual disk. You can download the VDDK SDK, build a VDDK image, upload image to your image registry, and add it to the v2v-vmware ConfigMap.

You can import the VMware VM with the virtual machine wizard and then update the virtual machine’s network name.

Configuring an image registry for the VDDK image

You can configure either an internal OpenShift Container Platform image registry or a secure external image registry for the VDDK image.

Storing the VDDK image in a public registry might violate the terms of the VMware license.

Configuring an internal image registry

You can configure the internal OpenShift Container Platform image registry on bare metal by updating the Image Registry Operator configuration.

Changing the image registry’s management state

To start the image registry, you must change the Image Registry Operator configuration’s managementState from Removed to Managed.

Procedure

  • Change managementState Image Registry Operator configuration from Removed to Managed. For example:

    $ oc patch configs.imageregistry.operator.openshift.io cluster --type merge --patch '{"spec":{"managementState":"Managed"}}'

Configuring registry storage for bare metal

As a cluster administrator, following installation you must configure your registry to use storage.

Prerequisites

  • Cluster administrator permissions.

  • A cluster on bare metal.

  • Persistent storage provisioned for your cluster, such as Red Hat OpenShift Container Storage.

    OpenShift Container Platform supports ReadWriteOnce access for image registry storage when you have only one replica. To deploy an image registry that supports high availability with two or more replicas, ReadWriteMany access is required.

  • Must have 100Gi capacity.

Procedure

  1. To configure your registry to use storage, change the spec.storage.pvc in the configs.imageregistry/cluster resource.

    When using shared storage, review your security settings to prevent outside access.

  2. Verify that you do not have a registry pod:

    $ oc get pod -n openshift-image-registry

    If the storage type is emptyDIR, the replica number cannot be greater than 1.

  3. Check the registry configuration:

    $ oc edit configs.imageregistry.operator.openshift.io
    Example output
    storage:
  pvc:
    claim:

    Leave the claim field blank to allow the automatic creation of an image-registry-storage PVC.

  4. Check the clusteroperator status:

    $ oc get clusteroperator image-registry

Configuring access to an internal image registry

You can access the OpenShift Container Platform internal registry directly, from within the cluster, or externally, by exposing the registry with a route.

Accessing registry directly from the cluster

You can access the registry from inside the cluster.

Procedure

Access the registry from the cluster by using internal routes:

  1. Access the node by getting the node’s address:

    $ oc get nodes
$ oc debug nodes/<node_address>

  2. In order to have access to tools such as oc and podman on the node, run the following command:

    sh-4.2# chroot /host

  3. Log in to the container image registry by using your access token:

    sh-4.2# oc login -u kubeadmin -p <password_from_install_log> https://api-int.<cluster_name>.<base_domain>:6443
sh-4.2# podman login -u kubeadmin -p $(oc whoami -t) image-registry.openshift-image-registry.svc:5000

    You should see a message confirming login, such as:

    Login Succeeded!

    You can pass any value for the user name; the token contains all necessary information. Passing a user name that contains colons will result in a login failure.

    Since the Image Registry Operator creates the route, it will likely be similar to default-route-openshift-image-registry.<cluster_name>.

  4. Perform podman pull and podman push operations against your registry:

    You can pull arbitrary images, but if you have the system:registry role added, you can only push images to the registry in your project.

    In the following examples, use:

    Component Value

    <registry_ip>

    172.30.124.220

    <port>

    5000

    <project>

    openshift

    <image>

    image

    <tag>

    omitted (defaults to latest)

    1. Pull an arbitrary image:

      $ podman pull name.io/image

    2. Tag the new image with the form <registry_ip>:<port>/<project>/<image>. The project name must appear in this pull specification for OpenShift Container Platform to correctly place and later access the image in the registry:

      $ podman tag name.io/image image-registry.openshift-image-registry.svc:5000/openshift/image

      You must have the system:image-builder role for the specified project, which allows the user to write or push an image. Otherwise, the podman push in the next step will fail. To test, you can create a new project to push the image.

    3. Push the newly-tagged image to your registry:

      $ podman push image-registry.openshift-image-registry.svc:5000/openshift/image

Exposing a secure registry manually

Instead of logging in to the OpenShift Container Platform registry from within the cluster, you can gain external access to it by exposing it with a route. This allows you to log in to the registry from outside the cluster using the route address, and to tag and push images using the route host.

Prerequisites:

  • The following prerequisites are automatically performed:

    • Deploy the Registry Operator.

    • Deploy the Ingress Operator.

Procedure

You can expose the route by using DefaultRoute parameter in the configs.imageregistry.operator.openshift.io resource or by using custom routes.

To expose the registry using DefaultRoute:

  1. Set DefaultRoute to True:

    $ oc patch configs.imageregistry.operator.openshift.io/cluster --patch '{"spec":{"defaultRoute":true}}' --type=merge

  2. Log in with podman:

    $ HOST=$(oc get route default-route -n openshift-image-registry --template='{{ .spec.host }}')
$ podman login -u $(oc whoami) -p $(oc whoami -t) --tls-verify=false $HOST (1)
    1 --tls-verify=false is needed if the cluster’s default certificate for routes is untrusted. You can set a custom, trusted certificate as the default certificate with the Ingress Operator.

To expose the registry using custom routes:

  1. Create a secret with your route’s TLS keys:

    $ oc create secret tls public-route-tls \
    -n openshift-image-registry \
    --cert=</path/to/tls.crt> \
    --key=</path/to/tls.key>

    This step is optional. If you do not create a secret, the route uses the default TLS configuration from the Ingress Operator.

  2. On the Registry Operator:

    spec:
  routes:
    - name: public-routes
      hostname: myregistry.mycorp.organization
      secretName: public-route-tls
...

    Only set secretName if you are providing a custom TLS configuration for the registry’s route.

Configuring access to an external image registry

If you use an external image registry for the VDDK image, you can add the external image registry’s certificate authorities to the OpenShift Container Platform cluster.

Optionally, you can create a pull secret from your Docker credentials and add it to your service account.

Adding certificate authorities to the cluster

You can add certificate authorities (CAs) to the cluster for use when pushing and pulling images via the following procedure.

Prerequisites

  • You must have cluster administrator privileges.

  • You must have access to the registry’s public certificates, usually a hostname/ca.crt file located in the /etc/docker/certs.d/ directory.

Procedure

  1. Create a ConfigMap in the openshift-config namespace containing the trusted certificates for the registries that use self-signed certificates. For each CA file, ensure the key in the ConfigMap is the registry’s hostname in the hostname[..port] format:

    $ oc create configmap registry-cas -n openshift-config \
--from-file=myregistry.corp.com..5000=/etc/docker/certs.d/myregistry.corp.com:5000/ca.crt \
--from-file=otherregistry.com=/etc/docker/certs.d/otherregistry.com/ca.crt

  2. Update the cluster image configuration:

    $ oc patch image.config.openshift.io/cluster --patch '{"spec":{"additionalTrustedCA":{"name":"registry-cas"}}}' --type=merge

Allowing pods to reference images from other secured registries

The .dockercfg $HOME/.docker/config.json file for Docker clients is a Docker credentials file that stores your authentication information if you have previously logged into a secured or insecure registry.

To pull a secured container image that is not from OpenShift Container Platform’s internal registry, you must create a pull secret from your Docker credentials and add it to your service account.

Procedure

  • If you already have a .dockercfg file for the secured registry, you can create a secret from that file by running:

    $ oc create secret generic <pull_secret_name> \
    --from-file=.dockercfg=<path/to/.dockercfg> \
    --type=kubernetes.io/dockercfg

  • Or if you have a $HOME/.docker/config.json file:

    $ oc create secret generic <pull_secret_name> \
    --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
    --type=kubernetes.io/dockerconfigjson

  • If you do not already have a Docker credentials file for the secured registry, you can create a secret by running:

    $ oc create secret docker-registry <pull_secret_name> \
    --docker-server=<registry_server> \
    --docker-username=<user_name> \
    --docker-password=<password> \
    --docker-email=<email>

  • To use a secret for pulling images for pods, you must add the secret to your service account. The name of the service account in this example should match the name of the service account the pod uses. default is the default service account:

    $ oc secrets link default <pull_secret_name> --for=pull

Creating and using a VDDK image

You can download the VMware Virtual Disk Development Kit (VDDK), build a VDDK image, and push the VDDK image to your image registry. You then add the VDDK image to the v2v-vmware ConfigMap.

Prerequisites

  • You must have access to an OpenShift Container Platform internal image registry or a secure external registry.

Procedure

  1. Create and navigate to a temporary directory:

    $ mkdir /tmp/<dir_name> && cd /tmp/<dir_name>

  2. In a browser, navigate to VMware code and click SDKs.

  3. Under Compute Virtualization, click Virtual Disk Development Kit (VDDK).

  4. Select the latest VDDK release, click Download, and then save the VDDK archive in the temporary directory.

  5. Extract the VDDK archive:

    $ tar -xzf VMware-vix-disklib-<version>.x86_64.tar.gz

  6. Create a Dockerfile:

    $ cat > Dockerfile <<EOF
FROM busybox:latest
COPY vmware-vix-disklib-distrib /vmware-vix-disklib-distrib
RUN mkdir -p /opt
ENTRYPOINT ["cp", "-r", "/vmware-vix-disklib-distrib", "/opt"]
EOF

  7. Build the image:

    $ podman build . -t <registry_route_or_server_path>/vddk:<tag> (1)
    1 Specify your image registry:

    • For an internal OpenShift Container Platform registry, use the internal registry route, for example, image-registry.openshift-image-registry.svc:5000/openshift/vddk:<tag>.

    • For an external registry, specify the server name, path, and tag, for example, server.example.com:5000/vddk:<tag>.

  8. Push the image to the registry:

    $ podman push <registry_route_or_server_path>/vddk:<tag>

  9. Ensure that the image is accessible to your OpenShift Container Platform environment.

  10. Edit the v2v-vmware ConfigMap in the openshift-cnv project:

    $ oc edit configmap v2v-vmware -n openshift-cnv

  11. Add the vddk-init-image parameter to the data stanza:

    ...
data:
  vddk-init-image: <registry_route_or_server_path>/vddk:<tag>

Importing a VMware virtual machine or template with the virtual machine wizard

You can import a VMware virtual machine or template using the virtual machine wizard.

Prerequisites

  • You must create a VDDK image, push it to an image registry, and add it to the v2v-vmware ConfigMap.

  • There must be sufficient storage space for the imported disk.

    If you try to import a virtual machine whose disk size is larger than the available storage space, the operation cannot complete. You will not be able to import another virtual machine or to clean up the storage because there are insufficient resources to support object deletion. To resolve this situation, you must add more object storage devices to the storage backend.

  • The VMware virtual machine must be powered off.

Procedure

  1. In the container-native virtualization web console, click Workloads → Virtual Machines.

  2. Click Create Virtual Machine and select Import with Wizard.

  3. In the General screen, perform the following steps:

    1. Select VMware from the Provider list.

    2. Select Connect to New Instance or a saved vCenter instance from the vCenter instance list.

      • If you select Connect to New Instance, fill in the vCenter hostname, Username, and Password.

      • If you select a saved vCenter instance, the wizard connects to the vCenter instance using the saved credentials.

    3. Select a virtual machine or a template to import from the VM or Template to Import list.

    4. Select an operating system.

    5. Select an existing flavor or Custom from the Flavor list.

      If you select Custom, specify the Memory (GB) and the CPUs.

    6. Select a Workload Profile.

    7. If the virtual machine name is already being used by another virtual machine in the namespace, update the name.

    8. Click Next.

  4. In the Networking screen, perform the following steps:

    1. Click the Options menu kebab of a network interface and select Edit.

    2. Enter a valid network interface name.

      The name can contain lowercase letters (a-z), numbers (0-9), and hyphens (-), up to a maximum of 253 characters. The first and last characters must be alphanumeric. The name must not contain uppercase letters, spaces, periods (.), or special characters.

    3. Select the network interface model.

    4. Select the network definition.

    5. Select the network interface type.

    6. Enter the MAC address.

    7. Click Save and then click Next.

  5. In the Storage screen, perform the following steps:

    1. Click the Options menu kebab of a disk and select Edit.

    2. Enter a valid name.

      The name can contain lowercase letters (a-z), numbers (0-9), and hyphens (-), up to a maximum of 253 characters. The first and last characters must be alphanumeric. The name must not contain uppercase letters, spaces, periods (.), or special characters.

    3. Select the interface type.

    4. Select the storage class.

      If you do not select a storage class, container-native virtualization uses the default storage class to create the virtual machine.

    5. Click Save and then click Next.

  6. In the Advanced screen, enter the Hostname and Authorized SSH Keys if you are using cloud-init.

  7. Click Next.

  8. Review your settings and click Create Virtual Machine.

    A Successfully created virtual machine message and a list of resources created for the virtual machine are displayed. The powered off virtual machine appears in Workloads → Virtual Machines.

  9. Click See virtual machine details to view the dashboard of the imported virtual machine.

    If an error occurs, perform the following steps:

    1. Click Workloads → Pods.

    2. Click the Conversion Pod, for example, kubevirt-v2v-conversion-rhel7-mini-1-27b9h.

    3. Click Logs and check for error messages.

See virtual machine wizard fields for more information on the wizard fields.

Updating the imported VMware virtual machine’s NIC name

You must update the NIC name of a virtual machine imported from VMware to conform to container-native virtualization naming conventions.

Procedure

  1. Log in to the virtual machine.

  2. Go to the /etc/sysconfig/network-scripts directory.

  3. Change the network configuration file name to ifcfg-eth0:

    $ mv vmnic0 ifcfg-eth0 (1)
    1 Additional network configuration files are numbered sequentially, for example, ifcfg-eth1, ifcfg-eth2.

  4. Update the NAME and DEVICE parameters in the network configuration file:

    NAME=eth0
DEVICE=eth0

  5. Restart the network:

    $ systemctl restart network

Troubleshooting a VMware virtual machine import

If an imported virtual machine’s status is Import error: (VMware), you can check the Conversion Pod log for errors:

  1. Obtain the Conversion Pod name:

    $ oc get pods -n <project> | grep v2v (1)
kubevirt-v2v-conversion-f66f7d-zqkz7            1/1     Running     0          4h49m
    1 Specify the project of your imported virtual machine.

  2. Obtain the Conversion Pod log:

    $ oc logs kubevirt-v2v-conversion-f66f7d-zqkz7 -f -n <project>

Error messages

  • If an imported virtual machine event displays the error message, Readiness probe failed, the following error message appears in the Conversion Pod log:

    INFO - have error: ('virt-v2v error: internal error: invalid argument: libvirt domain ‘v2v_migration_vm_1’ is running or paused. It must be shut down in order to perform virt-v2v conversion',)"

    You must ensure that the virtual machine is shut down before importing it.

Known issues

  • Your OpenShift Container Platform environment must have sufficient storage space for the imported disk.

    If you try to import a virtual machine whose disk size is larger than the available storage space, the operation cannot complete. You will not be able to import another virtual machine or to clean up the storage because there are insufficient resources to support object deletion. To resolve this situation, you must add more object storage devices to the storage backend. (BZ#1721504)

  • If you use NFS-backed storage for the 2 GB disk that is attached to the Conversion Pod, you must configure a hostPath volume. (BZ#1814611)

Virtual machine wizard fields

Virtual machine wizard fields

Name Parameter Description

Template

Template from which to create the virtual machine. Selecting a template will automatically complete other fields.

Source

PXE

Provision virtual machine from PXE menu. Requires a PXE-capable NIC in the cluster.

URL

Provision virtual machine from an image available from an HTTP or S3 endpoint.

Container

Provision virtual machine from a bootable operating system container located in a registry accessible from the cluster. Example: kubevirt/cirros-registry-disk-demo.

Disk

Provision virtual machine from a disk.

Operating System

The primary operating system that is selected for the virtual machine.

Flavor

small, medium, large, tiny, Custom

Presets that determine the amount of CPU and memory allocated to the virtual machine. The presets displayed for Flavor are determined by the operating system.

Memory

Size in GiB of the memory allocated to the virtual machine.

CPUs

The amount of CPU allocated to the virtual machine.

Workload Profile

High Performance

A virtual machine configuration that is optimized for high-performance workloads.

Server

A profile optimized to run server workloads.

Desktop

A virtual machine configuration for use on a desktop.

Name

The name can contain lowercase letters (a-z), numbers (0-9), and hyphens (-), up to a maximum of 253 characters. The first and last characters must be alphanumeric. The name must not contain uppercase letters, spaces, periods (.), or special characters.

Description

Optional description field.

Start virtual machine on creation

Select to automatically start the virtual machine upon creation.

Cloud-init fields

Name Description

Hostname

Sets a specific host name for the virtual machine.

Authenticated SSH Keys

The user’s public key that is copied to ~/.ssh/authorized_keys on the virtual machine.

Use custom script

Replaces other options with a field in which you paste a custom cloud-init script.

Networking fields

Name Description

Name

Name for the Network Interface Card.

Model

Indicates the model of the Network Interface Card. Supported values are e1000, e1000e, ne2k_pci, pcnet, rtl8139, and virtIO.

Network

List of available NetworkAttachmentDefinition objects.

Type

List of available binding methods. For the default Pod network, masquerade is the only recommended binding method. For secondary networks, use the bridge binding method. The masquerade method is not supported for non-default networks.

MAC Address

MAC address for the Network Interface Card. If a MAC address is not specified, an ephemeral address is generated for the session.

Storage fields

Name Description

Source

Select a blank disk for the virtual machine or choose from the options available: URL, Container, Attach Cloned Disk, or Attach Disk. To select an existing disk and attach it to the virtual machine, choose Attach Cloned Disk or Attach Disk from a list of available PersistentVolumeClaims (PVCs).

Name

Name of the disk. The name can contain lowercase letters (a-z), numbers (0-9), hyphens (-), and periods (.), up to a maximum of 253 characters. The first and last characters must be alphanumeric. The name must not contain uppercase letters, spaces, or special characters.

Size (GiB)

Size, in GiB, of the disk.

Interface

Type of disk device. Supported interfaces are virtIO, SATA, and SCSI.

Storage class

The StorageClass that is used to create the disk.