The module lifecycle stage: General Availability

Environment requirements

The provider requires the following:

  • A working zVirt installation with an accessible API
  • zVirt version 4.0–4.4
  • A user with the permissions listed in the “User permissions” section
  • A storage domain with an uploaded cloud image of the operating system
  • A virtual machine template prepared from the cloud image

If the zVirt API uses a self-signed certificate, pass the CA certificate in the caBundle parameter or set the insecure parameter to true.

User permissions

Deckhouse Platform does not require the SuperUser role for the zVirt user. It is enough to assign the following predefined zVirt roles to the user on the objects the cluster works with:

Role Object Purpose
UserVmManager zVirt cluster from the clusterID parameter Creating, starting, stopping, and deleting node virtual machines, creating their network interfaces, attaching and detaching disks
UserTemplateBasedVm Virtual machine template Creating virtual machines from the template
DiskOperator Storage domains that contain the template disk and where disks for etcd and cluster volumes are created Creating, resizing, attaching, detaching, and deleting disks
VnicProfileUser vNIC profile Creating a virtual machine network interface from the vNIC profile
TagManager Entire system (system permission) Creating the cluster tag and assigning it to virtual machines of CloudEphemeral nodes

The TagManager role is assigned only on the entire system, because zVirt checks the tag management permission at this level.

The TagManager role is administrative. With it, the user can view all objects via the zVirt API but can modify only the objects on which the roles from the table are assigned to the user.

zVirt assigns some roles to the Everyone group by default, so you do not need to assign them to the user separately:

  • UserTemplateBasedVm on a template created with the “Allow all users to access this Template” checkbox selected
  • VnicProfileUser on a public vNIC profile
  • CpuProfileOperator on the cluster CPU profile
  • DiskProfileUser on the disk profiles of storage domains

If these permissions were removed in your zVirt installation, assign the roles to the user.

To assign a role on an object:

  1. Open the object in the zVirt Administration Portal, for example, a cluster in the “Compute → Clusters” section.
  2. Go to the “Permissions” tab and click “Add”.
  3. Select the user and the role and save the permission.

Assign the TagManager role in the “Administration → Configure” section on the “System Permissions” tab.

Prepare an operating system image

Operating system (OS) vendors usually provide special cloud builds of their OSes for virtualization environments. These builds contain virtual hardware drivers, cloud-init, and virtualization guest agents and are distributed as IMG or QCOW2 disk images. Use these cloud images as the OS of the cluster nodes.

The OS cloud image must be placed in the zVirt disk storage. To upload the image to the storage:

  1. Open the zVirt Administration Portal and go to the “Storage → Disks” section.
  2. Upload the OS cloud image to the storage.

    Starting the upload of the OS cloud image to the storage

    Uploading the OS cloud image to the storage

  3. Wait until the image upload is complete. The OK status must appear in the “Status” column.

    Finishing the upload of the OS cloud image to the storage

Prepare a virtual machine template

The provider supports working with only one disk in the virtual machine template. Make sure the template contains only one disk.

The template is created from a virtual machine (VM) with the OS cloud image attached. To prepare the template:

  1. In the zVirt Administration Portal, go to the “Compute → Virtual Machines” section and create a VM. In the “General” section, set the following parameters:

    • “Template”: Blank.
    • “Operating System”: The OS of the cloud image.
    • “Optimized for”: “High Performance”.
    • “Instance Images”: Click “Attach”, select the uploaded OS cloud image, select the checkbox in the “OS” column to make the disk bootable, and select the “VirtIO” interface. Do not create or attach other disks.

    General section

  2. Do not attach network interfaces. Deckhouse Platform creates a network interface when it creates a VM for a node.

    Network interfaces

  3. Leave the other parameters at their defaults and create the VM.
  4. When the VM is created, select it in the list, open the additional actions menu (⋮), and select “Make Template”.

    Creating a template

  5. Specify the template name and enable the “Seal Template (Linux only)” parameter. The other template parameters are optional.

    Template parameters

  6. Wait until the template is created. While the template is being created, the VM and the cloud image disk are in the “Image Locked” state. The created template is displayed in the “Compute → Templates” section.

    Template check

Replacing the OS image

The template parameter of ZvirtInstanceClass defines the image for CloudEphemeral nodes. With a ModuleConfig-based provider configuration, this parameter also defines the image for CloudPermanent nodes and master nodes.

With a ZvirtClusterConfiguration-based configuration, the image for CloudPermanent nodes and master nodes is set by template in nodeGroups[].instanceClass and masterNodeGroup.instanceClass, respectively.

The replacement procedure is described in “How do I replace the OS image in a cloud cluster?”.

Credentials Secret

The zVirt user login and password are stored in a separate Secret rather than in the ModuleConfig. The module reads it and passes the credentials to its components that access the zVirt API.

The Secret is created during cluster installation together with the other resources of the initial configuration. The Secret must meet the following requirements:

  • The name is d8-credentials and the namespace is d8-cloud-provider-zvirt.
  • The type is cloud-provider.deckhouse.io/credentials.
  • The authScheme field is set to userPassword.
  • The identity field contains the zVirt user login.
  • The secret field contains the zVirt user password.
apiVersion: v1
kind: Secret
metadata:
  name: d8-credentials
  namespace: d8-cloud-provider-zvirt
type: cloud-provider.deckhouse.io/credentials
stringData:
  authScheme: userPassword
  identity: <USERNAME>
  secret: <PASSWORD>

Replace <USERNAME> and <PASSWORD> with the zVirt user login and password.

A Secret that does not meet these requirements fails the check both during cluster installation and when applied in a running cluster.

To change the credentials, update the identity and secret fields:

d8 k -n d8-cloud-provider-zvirt edit secret d8-credentials

In clusters migrated to ModuleConfig, the login and password are moved to this Secret from the provider.username and provider.password parameters of the ZvirtClusterConfiguration resource.