Skip to content

KubeVirt#

Installation requirements KubeVirt#

  • Golden image with Hystax Acura Controller and Hystax Cloud Agent.

  • Resources to launch a virtual machine instance created from the Hystax Acura Golden image:

    • 8 vCPUs,
    • 16GB RAM,
    • 250GB SSD disk.

  • Resources to launch a virtual machine for the Hystax Cloud Agent. Created in each target / failover namespace:

    • 2 vCPUs,
    • 4GB RAM,
    • 20GB disk.

  • Network connectivity between source site and Hystax Acura VM instance via ports tcp/443 and udp/12201.

  • Network connectivity for Acura user via tcp/443 (UI/API) and tcp/4443 (Initial configuration UI, closes after).

Installation steps#

Cloud configuration#

KubeVirt includes a service called the Containerized Data Importer (CDI), which can either download a VM image from a provided URL or accept image data directly from a client. Below is an example of the latter:

1. Forward port.

In the first terminal, forward the CDI Upload Proxy to your local machine:

kubectl port-forward --namespace kubevirt deployment/cdi-uploadproxy 8443:8443

If the command fails, verify that the namespace is correct. Run kubectl get deployment -A to list all deployments across all namespaces and find where cdi-uploadproxy is located.

2. Upload image.

In the second terminal, upload the controller and Cloud Agent images as new Persistent Volume Claims:

virtctl image-upload pvc acura-controller-pvc --size=200Gi --storage-class=**<STORAGE-CLASS>** --volume-mode=block --access-mode=ReadWriteOnce --image-path=**<CONTROLLER-IMAGE-PATH>** --uploadproxy-url=https://127.0.0.1:8443 --insecure

virtctl image-upload pvc acura-cloudagent-pvc --size=10Gi --storage-class=**<STORAGE-CLASS>** --volume-mode=block --access-mode=ReadWriteMany --image-path=**<AGENT-IMAGE-PATH>** --uploadproxy-url=https://127.0.0.1:8443 --insecure

Replace:

  • <CONTROLLER-IMAGE-PATH> with the controller image file name (including extension).
  • <AGENT-IMAGE-PATH> with the Cloud Agent image file name (including extension).
  • <STORAGE-CLASS> with one of the available storage classes. Run kubectl get sc to list them.

3. Deploy instance.

Save the following configuration as acura-controller.yaml and run kubectl apply -f acura-controller.yaml to create the controller VM.

Sample Acura VM config:

apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: acura-controller
spec:
  runStrategy: Always
  template:
    metadata:
      name: acura-controller
    spec:
      domain:
        cpu:
          cores: 4
        resources:
          requests:
            memory: "16Gi"
        devices:
          disks:
          - name: rootdisk
            disk:
              bus: virtio
          - disk:
              bus: virtio
            name: cloudinitdisk
          interfaces:
          - name: default
            masquerade: {}
      networks:
      - name: default
        pod: {}
      volumes:
      - name: rootdisk
        persistentVolumeClaim:
          claimName: acura-controller-pvc
      - name: cloudinitdisk
        cloudInitNoCloud:
          userData: |-
            #cloud-config

Notes:

  • Do not deploy the Cloud Agent instance manually. Acura automatically creates Cloud Agent instances with ephemeral disks, using the Cloud Agent PVC as a template.

  • In this example, Acura ports are not exposed to the outside world. Use an appropriate method of exposing ports to allow connections from the source site and for user operations.

Pass Acura initial configuration#

Once the VM is started, wait approximately 20 minutes for it to boot up, then open its EIP in a web browser. Please accept the certificate warnings so that you are redirected to the initial configuration page.

Step 1. Admin user creation.

Enter the organization name and new Hystax Admin User credentials into the Setup Wizard. This is the user account for logging in to Hystax Acura Control Panel and managing the system. If there are any errors, the system notifies you.

Step1

Step 2. SMTP configuration.

Fill in your Hystax License key that was supposed to be shared with you in advance as well as the settings for accessing your mail server used to send notifications from Acura and generate periodic reports.

Warning

SMTP server with TLS/SSL encryption is required to proceed with deployment.

A sample notification is sent to the specified "Test email" to verify the functionality when you click "Next".

Step2

Step 3. Target cloud configuration.

Fill in all the fields by providing cloud configuration details. Use question mark icons to get hints on the fields. After you click "Next", the Setup Wizard validates the entered data and notify you in case of an error.

Step3 KubeVirt

Detailed description of the fields.

Click "Next" to start cloud validation.

Step 4. Log in.

Once the validation is complete, click on the "Log in" button, and log into Acura Control Panel. Accept the certificate warnings if needed.

Step4

Congratulations, you are now ready to use Acura! Just enter the administrator username and password specified on the first step of installation in the login page of the solution.

Operational details and limitations#

Resource IDs and labels

Each Kubernetes resource has a unique ID (metadata.uid). Unfortunately, these UIDs are not indexed: there is no way to find a resource by its ID other than listing everything and checking resources one by one. The only universally indexed fields are name (metadata.name), namespace (metadata.namespace), and labels (metadata.labels).

Therefore, Acura generates its own unique IDs and stores them in the hxreplica/resource-id label for every resource it creates.

Resource names

Names in Kubernetes must be unique, so Acura appends the same unique ID as a name suffix for most resources it creates. Migrated VMs are an exception: users are allowed to specify any name in the migration plan, and Acura uses that exact name without a suffix. Note that the resource ID labels are still present on migrated VMs.

Kubernetes has strict limits on resource name formats. Acura automatically converts invalid resource names into valid ones: uppercase letters become lowercase, and invalid characters are replaced with hyphens. Names that are too long are trimmed, while preserving the unique ID suffix.

Flavor names

KubeVirt flavor names in Acura are synthetic – in {cpu}-{ram} format (just like on VMware). For example, flavor 2-4 creates a VM with 2 CPU cores and 4 GiB of RAM.

Snapshot support

Snapshot support is not implemented in Acura yet. Some Kubernetes storage drivers can create snapshots, but Acura does not support them at the moment. It always runs in snapshot-less mode, with the usual limitations:

  • Only one restore point is kept.

  • The machine is blocked if there are active recoveries.

  • The next replication after recovery will be full.

  • No automated failbacks or failover downloads (failback as reverse migration is possible, though).

Cloud volumes

What Acura calls a “Volume” is called a PersistentVolumeClaim (PVC) in Kubernetes. Cloud volumes created by Acura are PVCs.

You can configure which storage class is used for PVCs either per cloud (in cloud settings) or per VM (in device replication settings). You can specify multiple comma-separated storage classes, using the same rules as for OpenStack volume types.

You can configure the disk bus for migrated VMs using the disk_bus parameter in the migration plan device. The default is virtio, but you can set scsi if needed.

Cloud Agent disks always use the scsi disk bus (both the boot disk and attached disks). This allows for a very high number of attached disks. However, for Cloud Agents, the attachment count is currently limited to 30 disks.

User data support

User data scripts are supported via a cloud-init config drive.

KubeVirt allows inline user data only up to 2048 bytes, so if user data is larger, it must be stored in a Kubernetes Secret. Acura creates this Secret when required and removes it automatically with the VM. For easier cleanup, the Secret ID is saved in the VM label hxreplica/user-data-secret-id.

Resource tagging

Kubernetes calls tags “labels”. Acura uses labels to store resource IDs and for several other purposes. You can also use the insert_default_tag cloud parameter to label all Acura-created resources with a tag name of your choice.

Error handling

In Kubernetes, most resources don’t have explicit error states. If something goes wrong, a resource may simply appear “stuck”, with Kubernetes endlessly retrying an operation. Typically, you check resource events to understand what happened, but there are no “Error” events—only Normal and Warning. This approach works well for declarative deployments, but it poses a challenge for Acura: we perform operations step by step and need to know whether the previous step succeeded.

Acura uses the following approach:

  • Acura checks for a specific success state to determine whether resource deployment completed.

  • For PVCs, success is status.phase == "Bound".

  • For VMs, success is status.printableStatus == "Running".

  • Acura enforces a resource creation timeout. If the timeout is exceeded, Acura raises an error and includes the contents of all Warning events in the description.

  • For PVCs, the timeout is 300 seconds.

  • For VMs, the timeout is 660 seconds.

Hystax Support Portal | Contact Support: [email protected] | Terms of use | © Copyright 2025 | Hystax | All rights reserved