This is unreleased documentation for SUSE® Virtualization v1.6 (Dev).

Virtualization Management

With Rancher’s virtualization management capabilities, you can import and manage multiple SUSE Virtualization clusters. It provides a solution that unifies virtualization and container management from a single pane of glass.

Additionally, SUSE Virtualization leverages Rancher’s existing capabilities, such as authentication and RBAC control for multi-tenancy support.

For information about deploying Rancher and provisioning Kubernetes clusters using various cloud providers, see Deploying SUSE Rancher Prime Server.

Importing SUSE Virtualization cluster

Check and prepare the container image.

To facilitate the importing task, a new pod named cattle-cluster-agent-*** will be created on the SUSE Virtualization cluster. The container image used for this pod depends on the version of your Rancher server (for example, the image rancher/rancher-agent:v2.7.9 is used if you are running Rancher v2.7.9). Moreover, this dynamic image is not packed into the SUSE Virtualization ISO and is instead pulled from the repository during importing.

If your SUSE Virtualization cluster is not directly accessible from the internet, perform one of the following actions:
- Configure a private registry for the cluster and add the image. Harvester will automatically pull the image from this registry.
- If you configured an HTTP proxy for accessing external services, verify that it is working as expected. The DNS servers that you specified in the Harvester configuration should be able to resolve the domain name docker.io.
- Download the image using the command docker pull rancher/rancher-agent:v2.7.9 && docker save -o rancher-agent.tar rancher/rancher-agent:v2.7.9. Next, create a copy of the downloaded image in each cluster node, and then import the image to containerd using the command sudo -i ctr --namespace k8s.io image import rancher-agent.tar. Finally, run sudo -i crictl image ls | grep "rancher-agent" on each node to ensure that the image is ready.
Once the Rancher server is up and running, log in and click the hamburger menu and choose the Virtualization Management tab. Select Import Existing to import the downstream SUSE Virtualization cluster into the Rancher server.
Specify the Cluster Name and click Create. You will then see the registration guide; please open the dashboard of the target SUSE Virtualization cluster and follow the guide accordingly.
Once the agent node is ready, you should be able to view and access the imported SUSE Virtualization cluster from the Rancher server and manage your VMs accordingly.

Whenever the agent node becomes stuck, run the command kubectl get pod cattle-cluster-agent-*** -n cattle-system -oyaml on the SUSE Virtualization cluster. If the following message is displayed, check the information in step 1, kill this pod and then a new pod will be created automatically to restart the importing process.
```
  ...
  state:
    waiting:
      message: Back-off pulling image "rancher/rancher-agent:v2.7.9"
      reason: ImagePullBackOff
  ...
```
From the SUSE Virtualization UI, you can click the hamburger menu to navigate back to the Rancher multi-cluster management page.

In the Rancher Kubernetes cluster, create a new Cluster resource.

Example:

  apiVersion: provisioning.cattle.io/v1
  kind: Cluster
  metadata:
    name: harvester-cluster-name
    namespace: fleet-default
    labels:
      provider.cattle.io: harvester
    annotations:
      field.cattle.io/description: Human readable cluster description
  spec:
    agentEnvVars: []

Once the status of the Cluster resource is updated, obtain the cluster ID (format: c-m-foobar) from the .status.clusterName property.
Create a ClusterRegistrationToken using the cluster ID in the namespace with the same name as the cluster ID. You must specify the cluster ID in the token’s .spec.clusterName field.

Example:
```
  apiVersion: management.cattle.io/v3
  kind: ClusterRegistrationToken
  metadata:
    name: default-token
    namespace: c-m-foobar
  spec:
    clusterName: c-m-foobar
```
Once the status of the ClusterRegistrationToken is updated, obtain the value of the token’s .status.manifestUrl property.
In the SUSE Virtualization cluster, patch the setting cluster-registration-url and specify the URL obtained from the cluster registration token’s .status.manifestUrl property in the value field.

Example:
```
  apiVersion: harvesterhci.io/v1beta1
  kind: Setting
  metadata:
    name: cluster-registration-url
  value: https://rancher.example.com/v3/import/abcdefghijkl1234567890-c-m-foobar.yaml
```

Upgrades

To upgrade an imported SUSE Virtualization cluster, you must upgrade Rancher, the Harvester UI Extension, and SUSE Virtualization in a specific order. The Harvester UI Extension is required to access the SUSE Virtualization UI in Rancher v2.10.x and later versions.

Check the support matrix to determine the Rancher and Harvester UI Extension versions that match the SUSE Virtualization cluster.
Upgrade Rancher.
Upgrade the Harvester UI Extension.

For information about upgrading the extension in an air-gapped environment, see Harvester UI extension with Rancher Integration.

Upgrade SUSE Virtualization.

Features in SUSE Virtualization v1.5.0 and later versions are implemented in the Harvester UI Extension. If you do not upgrade Rancher and the Harvester UI Extension, these features may not be available.

Troubleshooting

See Importing of Harvester Clusters into Rancher.

Multi-Tenancy

SUSE Virtualization leverages the existing Rancher RBAC authorization such that users can view and manage a set of resources based on their cluster and project role permissions.

Within Rancher, each person authenticates as a user, which is a login that grants a user access to Rancher. As mentioned in Authentication, users can either be local or external.

Once the user logs into Rancher, their authorization, also known as access rights, is determined by global permissions and cluster and project roles.

Global Permissions: Define user authorization outside the scope of any particular cluster.
Cluster and Project Roles: Define user authorization inside the specific cluster or project where users are assigned the role.

Both global permissions and cluster and project roles are implemented on top of Kubernetes RBAC. Therefore, enforcement of permissions and roles is performed by Kubernetes.

A cluster owner has full control over the cluster and all resources inside it, e.g., hosts, VMs, volumes, images, networks, backups, and settings.
A project user can be assigned to a specific project with permission to manage the resources inside the project.

Managing user access using the built-in role templates and project-scoped RBAC is strongly recommended.

SUSE Virtualization implements its own RBAC model on top of Kubernetes and KubeVirt, integrating with Rancher-style Projects and multi-tenancy logic. During upgrades or reconfiguration, custom RoleBindings referencing only kubevirt.io roles may be lost, reset, or become inconsistent with SUSE Virtualization’s internal state.

Multi-Tenancy Example

The following example provides a good explanation of how the multi-tenant feature works:

First, add new users via the Rancher Users & Authentication page. Then click Create to add two new separated users, such as project-owner and project-readonly respectively.
- A project-owner is a user with permission to manage a list of resources of a particular project, e.g., the default project.
- A project-readonly is a user with read-only permission of a particular project, e.g., the default project.
Click one of the imported SUSE Virtualization clusters after navigating to the SUSE Virtualization UI.
- Click the Projects/Namespaces tab.
- Select a project such as default and click the Edit Config menu to assign the users to this project with appropriate permissions. For example, the project-owner user will be assigned the project owner role.
Continue to add the project-readonly user to the same project with read-only permissions and click Save.
Open an incognito browser and log in as project-owner.
After logging in as the project-owner user, click the Virtualization Management tab. There you should be able to view the cluster and project to which you have been assigned.
Click the Images tab to view a list of images previously uploaded to the harvester-public namespace. You can also upload your own image if needed.
Create a VM with one of the images that you have uploaded.
Log in with another user, e.g., project-readonly, and this user will only have the read permission of the assigned project.

The harvester-public namespace is a predefined namespace accessible to all users assigned to this cluster.

Delete Imported SUSE Virtualization Cluster

Users can delete the imported SUSE Virtualization cluster from the Virtualization Management screen of the Rancher UI. Select the cluster you want to remove and click the Delete button to delete the imported SUSE Virtualization cluster.

You will also need to reset the cluster-registration-url setting on the associated SUSE Virtualization cluster to clean up the Rancher cluster agent.

Please do not run the kubectl delete -f ... command to delete the imported SUSE Virtualization cluster as it will remove the entire cattle-system namespace which is required of the SUSE Virtualization cluster.