Skip to content

Commit

Permalink
Merge pull request #27 from acend/instance-types
Browse files Browse the repository at this point in the history 
Proofread instance types and preferences chapter
  • Loading branch information
@phil-pona
phil-pona authored Oct 2, 2024
2 parents 3ea1b50 + ff917a0 commit 87bb94b
Show file tree
Hide file tree
Showing 5 changed files with 149 additions and 107 deletions.
16 changes: 8 additions & 8 deletions content/en/docs/instance-types-and-preferences/_index.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
---
title: "Instance Types and Preferences"
title: "Instance types and preferences"
weight: 3
labfoldernumber: "03"
description: >
Learn how to use and define Instance Types and Preferences.
Learn how to use and define instance types and preferences
---

In this section we will see how we can define Instance Types and Preferences. These provide a way to define a set of
In this section we will see how we can define instance types and preferences. These provide a way to define a set of
runtime characteristics like resources or performance settings which can then be reused.


## Lab Goals
## Lab goals

* Know the benefit of `VirtualMachineInstancetype` and `VirtualMachinePreference`
* Examine Common Instance types and Preferences.
* Deploy VMs with a common Instance type.
* Define your own Instance type and Preference settings.
* Use your custom Instance types with your VMs.
* Examine common instance types and preferences
* Deploy VMs with a common instance type
* Define your own instance type and preference settings
* Use your custom instance types with your VMs
128 changes: 76 additions & 52 deletions content/en/docs/instance-types-and-preferences/common-instancetypes.md
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,32 @@
---
title: "Common types and preferences"
title: "Common instance types and preferences"
weight: 32
labfoldernumber: "03"
description: >
Discover and use common Instancetypes and Preferences provided by KubeVirt.
Discover and use common instance types and preferences provided by KubeVirt
---

The KubeVirt project [Common Instancetypes and Preferences](https://github.com/kubevirt/common-instancetypes) provides a set of Instancetypes and Preferences.
The KubeVirt project provides a set of [common instance types and preferences](https://github.com/kubevirt/common-instancetypes).
In this lab, we are going to have a look at these and how they can help us create virtual machines.


## Deployment of Common Instancetypes and Preferences
## Deployment of common instance types and preferences

The common Instancetypes and Preferences are not available by default. They have to be deployed manually or using a feature gate of the KubeVirt operator.
The common instance types and preferences are not available by default. They have to be deployed manually or by using one of the KubeVirt Operator's feature gates.

You can check the configuration on the KubeVirt CustomResource:

```bash
kubectl get kubevirt kubevirt --namespace=kubevirt -o jsonpath={.spec.configuration.developerConfiguration.featureGates}
```
or

```bash
kubectl get kubevirt kubevirt --namespace=kubevirt -o yaml
```

The relevant section on the CustomResource is the following:

```yaml
apiVersion: kubevirt.io/v1
kind: KubeVirt
Expand All @@ -36,26 +40,28 @@ spec:
[...]
```

With the feature gate enabled, the operator itself takes care of deploying the cluster wide common Instancetypes and Preferences.
With the feature gate enabled, the Operator itself takes care of deploying the cluster wide common instance types and preferences.


### Manually deploy the Common Instancetypes and Preferences
### Manually deploy the common instance types and preferences

This step has been done for your on the Lab cluster.
How to deploy the Common Instancetypes and Preferences on your own cluster can be found in the [documentation](https://kubevirt.io/user-guide/user_workloads/deploy_common_instancetypes/).
This step has been done for your on the lab cluster.
How to deploy the common instance types and preferences on your own cluster can be found in the [documentation](https://kubevirt.io/user-guide/user_workloads/deploy_common_instancetypes/).


## List and inspect Instancetypes
## List and inspect instance types

Be aware that the common instancetypes and preferences are cluster wide. Therefore, the CustomResources are
Be aware that the common instance types and preferences are cluster-wide resources. They are called
`VirtualMachineClusterInstancetype` and `VirtualMachineClusterPreference`.

You can list the available instance types using:

```bash
kubectl get virtualmachineclusterinstancetype
```

Shortened output of the command above:
A shortened output of the command above:

```bash
NAME AGE
cx1.2xlarge 10m
Expand All @@ -79,7 +85,7 @@ u1.small 10m
u1.xlarge 10m
```

As you see the instancetypes follow the naming schema:
As you see the instance types follow a specific naming schema:

```bash
instanceTypeName = seriesName , "." , size;
Expand All @@ -100,19 +106,21 @@ The class `u`, `o`, `cx`, `g`, `m`, `n` and `rt` mean the following:
* **O** (overcommitted) - Based on `u` with the only difference that memory will be overcommitted. Allows higher workload density.
* **CX** (compute exclusive) - Provides exclusive compute resources for compute intensive applications.
* **GN** (gpu nvidia) - Instance type for VMs which consume attached NVIDIA GPUs.
* **M** (memory) - Provides resources for memory intensive applications.
* **N** (network) - Provide resources for network intensive DPDK[^1] applications like Virtual Network Functions.
* **RT** (realtime) - Provide resources for realtime intensive applications.
* **M** (memory) - Provides resources for memory-intensive applications.
* **N** (network) - Provide resources for network-intensive DPDK[^1] applications like Virtual Network Functions (VNF).
* **RT** (realtime) - Provide resources for realtime-intensive applications.

We therefore can say that the classes `u` and `o` are agnostic to the workload. The other classes are optimized for
specific workload.

You may see the details of an instancetype by describing the resource
You may see the details of an instance type by describing the resource:

```bash
kubectl describe virtualmachineclusterinstancetype o1.nano
```

As an example you'll see that the instancetype `o1.nano` has 1 CPU, 512Mi of memory and overcommittes memory by 50%. The following output is shortened:
As an example you will see that the instance type `o1.nano` has 1 CPU, 512Mi memory and overcommits memory by 50%. The following output is shortened:

```
Name: o1.nano
Namespace:
Expand Down Expand Up @@ -143,13 +151,14 @@ Spec:
```


## List and inspect Preferences
## List and inspect preferences

```bash
kubectl get virtualmachineclusterpreference
```

Shortened output of the command above:
A shortened output of the command above:

```
NAME AGE
alpine 10m
Expand All @@ -158,11 +167,12 @@ centos.7 10m
```

You may see the details of a preference by describing the resource:

```bash
kubectl describe virtualmachineclusterpreference cirros
```

As an example you'll see that the instancetype `cirros` has the requirements of 1 CPU, 256Mi memory. The following output is shortened:
As an example you'll see that the instance type `cirros` has the requirements of 1 CPU, 256Mi memory. The following output is shortened:

```
Name: cirros
Expand Down Expand Up @@ -191,14 +201,15 @@ Spec:
```


## Querying for specific instancetypes and preferences with labels
## Querying for specific instance types and preferences with labels


### Instancetypes

These instancetypes are labeled according to their specification. You can use labels to find the correct instancetype.
These instance types are labeled according to their specification. You can use labels to find the correct instance type.

Instance types are known to use the following labels:

Instancetypes are known to use the following labels:
```properties
instancetype.kubevirt.io/common-instancetypes-version: The version of the common-instancetypes project used to generate these resources.
instancetype.kubevirt.io/vendor: The vendor of the resource, this is always kubevirt.io upstream and should be changed by downstream vendors consuming the project.
Expand All @@ -215,12 +226,14 @@ instancetype.kubevirt.io/hugepages: If hugepages are requested by the instance t
instancetype.kubevirt.io/gpus: If GPUs are requested by the instance type.
```

As an example you can query for 4 CPUs:
As an example, you can query for 4 CPUs:

```bash
kubectl get virtualmachineclusterinstancetype --selector instancetype.kubevirt.io/cpu=4
```

Output will list all instancetypes with 4 CPUs:
Output will list all instance types with 4 CPUs:

```
NAME AGE
cx1.xlarge 10m
Expand All @@ -235,7 +248,8 @@ u1.xlarge 10m

### Preferences

Just like instancetypes the preferences are labeled with the following labels:
Just like instance types, preferences are labeled with the following labels:

```properties
instancetype.kubevirt.io/common-instancetypes-version: The version of the common-instancetypes project used to generate these resources.
instancetype.kubevirt.io/vendor: The vendor of the resource, this is always kubevirt.io upstream and should be changed by downstream vendors consuming the project.
Expand All @@ -246,11 +260,13 @@ instancetype.kubevirt.io/arch: The underlying architecture of the workload suppo
```

We can use these labels to query preferences:

```bash
kubectl get virtualmachineclusterpreference --selector instancetype.kubevirt.io/os-type=linux
```

Output will list all preferences targeting the operating system linux (output shortened):
The output will list all preferences targeting the operating system linux (output shortened):

```
NAME AGE
alpine 10m
Expand All @@ -265,42 +281,46 @@ ubuntu 10m
```


## {{% task %}} Find matching Instancetype and preference
## {{% task %}} Find matching instance type and preference

You want to find the optimal configuration of instancetype and preference for a Windows 10 64-bit installation.
According to Microsoft the Windows 10 system requirements[^2] are the following:
You want to find the optimal configuration of instance type and preference for a Windows 10 64-bit virtual machine.
According to Microsoft, the Windows 10 system requirements[^2] are the following:

```
Processor: 1 gigahertz (GHz) or faster processor or SoC
RAM: 2 GB for 64-bit
Hard disk space: 20 GB for 64-bit OS
```

Try to find the best matching instancetype and preference for a Windows 10 minimal installation using label selectors.
Try to find the best matching instance type and preference for a Windows 10 minimal installation using label selectors.

{{% details title="Task Hint" %}}
You can query instance types as follows:

```bash
kubectl get virtualmachineclusterinstancetype \
--selector instancetype.kubevirt.io/cpu=1,instancetype.kubevirt.io/memory=2Gi
```

Will return something like:
Above query will return something like:

```bash
NAME AGE
cx1.medium 10m
o1.small 10m
u1.small 10m
```

You would most likely pick `o1.small` or `u1.small` as your instancetype.

You would most likely pick `o1.small` or `u1.small` as your instance type.

For preferences, you can use the following query:

```bash
kubectl get virtualmachineclusterpreference --selector instancetype.kubevirt.io/os-type=windows
```

Which outputs:

```
NAME AGE
windows.10 10m
Expand All @@ -317,7 +337,7 @@ windows.2k22 10m
windows.2k22.virtio 10m
```

The preferences `windows.10` or `windows.10.virtio` are the best matching.
The preferences `windows.10` or `windows.10.virtio` are the best-matching.

{{% alert title="Note" color="info" %}}
This only fulfills the machines minimal requirements. In a production environment you would most likely size your instance bigger than the minimal requirements.
Expand All @@ -330,10 +350,10 @@ This only fulfills the machines minimal requirements. In a production environmen

Deploy two VMs with different instance types:

* Deploy a cirros VM using an `u` class instancetype and a matching preference.
* Deploy a cirros VM using a `u` class instance type and a matching preference
* Write the VM specification in `{{% param "labsubfolderprefix" %}}{{% param "labfoldernumber" %}}-u1-cirros.yaml`
* Deploy a cirros VM using an `o` class instancetype and the same preference.
* rite the VM specification in `{{% param "labsubfolderprefix" %}}{{% param "labfoldernumber" %}}-o1-cirros.yaml`
* Deploy a cirros VM using a `o` class instance type and the same preference
* Write the VM specification in `{{% param "labsubfolderprefix" %}}{{% param "labfoldernumber" %}}-o1-cirros.yaml`

{{% onlyWhen tolerations %}}

Expand All @@ -345,6 +365,7 @@ Don't forget the `tolerations` from the setup chapter to make sure the VM will b

{{% details title="Solution" %}}
`{{% param "labsfoldername" %}}/{{% param "labsubfolderprefix" %}}{{% param "labfoldernumber" %}}/vm_{{% param "labsubfolderprefix" %}}{{% param "labfoldernumber" %}}-u1-cirros.yaml` specification:

```yaml
apiVersion: kubevirt.io/v1
kind: VirtualMachine
Expand Down Expand Up @@ -390,6 +411,7 @@ spec:
```
`{{% param "labsfoldername" %}}/{{% param "labsubfolderprefix" %}}{{% param "labfoldernumber" %}}/vm_{{% param "labsubfolderprefix" %}}{{% param "labfoldernumber" %}}-o1-cirros.yaml` specification:

```yaml
apiVersion: kubevirt.io/v1
kind: VirtualMachine
Expand Down Expand Up @@ -434,8 +456,7 @@ spec:
userDataBase64: SGkuXG4=
```


Apply and start both VMs with
Apply and start both VMs using:

```bash
kubectl apply -f {{% param "labsfoldername" %}}/{{% param "labsubfolderprefix" %}}{{% param "labfoldernumber" %}}/vm_{{% param "labsubfolderprefix" %}}{{% param "labfoldernumber" %}}-u1-cirros.yaml --namespace=$USER
Expand All @@ -446,26 +467,29 @@ virtctl start {{% param "labsubfolderprefix" %}}{{% param "labfoldernumber" %}}-
{{% /details %}}


## {{% task %}} Inspect difference due to instancetype
## {{% task %}} Instance type differences

The main difference in the instancetypes `u` and `o` are memory overcommitting. Let's inspect our two VMs. What exactly means
overcommitting in the scope of a VirtualMachine instances? Overcommitting means we assign the VM more memory as we request
The main difference in the instance types `u` and `o` are memory overcommitting. Let's inspect our two VMs. What exactly means
overcommitting in the scope of a VirtualMachine instance? Overcommitting means that we assign more memory to a VM than we requested
from the cluster by setting `spec.domain.memory.guest` to a higher value than `spec.domain.resources.requests.memory`.

What would you expect from both VMs?
{{% details title="Task Hint" %}}

* `u` class should have equal request for `spec.domain.memory.guest` and `spec.domain.resources.requests.memory`
* `o` class should have higher request for `spec.domain.memory.guest` as `spec.domain.resources.requests.memory`
{{% details title="Task hint" %}}

* `u` class should have equal requests for `spec.domain.memory.guest` and `spec.domain.resources.requests.memory`
* `o` class should have higher requests for `spec.domain.memory.guest` than `spec.domain.resources.requests.memory`

For both VMs we would expect the guest os to have approximately 512 mb of ram.
For both VMs we would expect the guest OS to have approximately 512Mi of memory.
{{% /details %}}

Check the expectations about memory settings of both VirtualMachine instances `{{% param "labsubfolderprefix" %}}{{% param "labfoldernumber" %}}-u1-cirros`
and `{{% param "labsubfolderprefix" %}}{{% param "labfoldernumber" %}}-o1-cirros`. Do they match our expectations?

{{% details title="Task Hint" %}}
{{% details title="Task hint" %}}

Describe both VirtualMachine instances using:

```bash
kubectl get vmi {{% param "labsubfolderprefix" %}}{{% param "labfoldernumber" %}}-u1-cirros -o yaml --namespace=$USER
kubectl get vmi {{% param "labsubfolderprefix" %}}{{% param "labfoldernumber" %}}-o1-cirros -o yaml --namespace=$USER
Expand All @@ -488,7 +512,7 @@ spec:
[...]
```

`o1-cirros` instance:
The `o1-cirros` instance:

```yaml
apiVersion: kubevirt.io/v1
Expand All @@ -505,7 +529,7 @@ spec:
[...]
```

As we can see in the difference between `spec.domain.memory.guest` and `spec.domain.resources.requests.memory` the `o` class actually overcommits by 50% as defined in the `o1.nano` instance type:
As we can see in the difference between `spec.domain.memory.guest` and `spec.domain.resources.requests.memory`, the `o` class actually overcommits by 50% as defined in the `o1.nano` instance type:

```yaml
apiVersion: instancetype.kubevirt.io/v1beta1
Expand All @@ -521,7 +545,7 @@ spec:
[...]
```

The `.status.memory` of both VirtualMachine instance show that the guest was assigned 512Mi memory.
The `.status.memory` of both VirtualMachine instances shows that the guest was assigned 512Mi memory.

```yaml
apiVersion: kubevirt.io/v1
Expand Down
Loading

0 comments on commit 87bb94b

Please sign in to comment.