Create Harvester glossary per customer request #539

jillian-maroket · 2024-03-29T09:08:22Z

I created this glossary in response to the customer request described in SURE-6084. The customer has specific terminology concerns so I prioritized those in this PR. I intend to expand the list over time and align with Rancher's glossary (WIP) whenever possible.

Let me know if I misrepresented anything and if you'd like any terms added to this MVP.

Note: Please ignore the formatting for now. The doc team is testing out a glossary structure that should eventually be used across the board.

Preview: https://66068b01f4b89bcb3f637b95--harvester-preview.netlify.app/v1.4/glossary

cc: @asettle @rebeccazzzz

harvesterhci-io-github-bot · 2024-03-29T09:35:05Z

✅ Deploy Preview for harvester-preview ready!

Name	Link
🔨 Latest commit	`95e92ee`
🔍 Latest deploy log	https://app.netlify.com/sites/harvester-preview/deploys/6615ed5548b76b4e4a8ed77c
😎 Deploy Preview	https://6615ed5548b76b4e4a8ed77c--harvester-preview.netlify.app

jillian-maroket · 2024-04-03T02:50:34Z

The Subscription Terms for SUSE Subscription Offerings document contains a glossary. I lifted the definition of "Harvester hypervisor" from that doc. Their definition of "Harvester node" seems to be incorrect so I wrote a different definition.

m-ildefons

I found the formulations around guest clusters and guest cluster nodes unclear.

m-ildefons · 2024-04-03T07:50:43Z

docs/glossary.md

+
+## **guest cluster** / **guest Kubernetes cluster**
+
+Group of integrated Kubernetes worker machines that are running in a VM that is part of a Harvester cluster. Guest clusters form the underlying infrastructure for running containerized workloads.


Formulation a bit unclear. Is the guest cluster part of the Harvester cluster, or is it a separate cluster of VM workload on top of the Harvester cluster?
Is a guest cluster required for containerized workloads or can container workloads not also be deployed directly on the Harvester cluster?
Also is this a group of K8s workers in a single VM, or a group of VMs, each being a K8s worker node?

I thought the situation with a guest cluster was like this:

┌─────────────────────────────────────────────────────────────────────────┐ │ Harvester Cluster │ │ ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐ │ │ │Physical Server │ │Physical Server │ │Physical Server │ │ │ │ │ │ │ │ │ │ │ │Harvester Node 1 │ │Harvester Node 2 │ │Harvester Node 3 │ │ │ ├───────────────────┤ ├───────────────────┤ ├───────────────────┤ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────────────┼─┼───────────────────┼─┼───────────────────┼─────┐ │ │ │ │ Guest Cluster │ │ │ │ │ │ │ │ │ │ ┌───────────┐ │ │ ┌───────────┐ │ │ ┌───────────┐ │ │ │ │ │ │ │VM │ │ │ │VM │ │ │ │VM │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │K8s Node 1 │ │ │ │K8s Node 2 │ │ │ │K8s Node 3 │ │ │ │ │ │ │ ├───────────┤ │ │ ├───────────┤ │ │ ├───────────┤ │ ... │ │ │ │ │ │Containers/│ │ │ │Containers/│ │ │ │Containers/│ │ │ │ │ │ │ │Pods │ │ │ │Pods │ │ │ │Pods │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └───────────┘ │ │ └───────────┘ │ │ └───────────┘ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─────────────────┼─┼───────────────────┼─┼───────────────────┼─────┘ │ │ │ │ │ │ │ │ │ │ └───────────────────┘ └───────────────────┘ └───────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘

Formulation a bit unclear. Is the guest cluster part of the Harvester cluster, or is it a separate cluster of VM workload on top of the Harvester cluster?

The latter. I'd suggest wording it something like: ...machines that are running in VMs on top of a Harvester cluster" (note: "VMs" plural, and "on top of" as you suggested).

Is a guest cluster required for containerized workloads or can container workloads not also be deployed directly on the Harvester cluster?

Deploying container workloads directly on the Harvester cluster is possible, but is still experimental AIUI (see https://docs.harvesterhci.io/v1.3/rancher/rancher-integration#harvester-baremetal-container-workload-support-experimental)

Also is this a group of K8s workers in a single VM, or a group of VMs, each being a K8s worker node?

Should be a group of VMs - I believe your diagram is correct.

@m-ildefons @tserong Thank you for pointing out the deficiencies of the draft definition. Please check the updated one.

m-ildefons · 2024-04-03T07:50:46Z

docs/glossary.md

+
+## **guest cluster node** / **guest node**
+
+Kubernetes worker machine that uses guest cluster resources to run workloads. 


Again, a bit unclear. Isn't a guest cluster node a VM running on top of Harvester with this VM then running (part of) the guest K8s cluster as workload?

Yup. Maybe say "Kubernetes worker VM"?

@m-ildefons @tserong Again, thank you and please check the updated definition.

m-ildefons

I like this new version much better, well done 👍
But sorry to be so nit-picky here I noticed another formulation that's potentially misleading.

m-ildefons · 2024-04-08T18:55:18Z

docs/glossary.md

+
+**Harvester cluster** 
+
+Group of integrated physical servers (hosts) on which the Harvester hypervisor is installed. These servers pool compute and storage resources to provide an environment for running VMs that can host guest clusters.


I'm not sure pool is the right word here - especially for storage.
While the strict dictionary definition of a pool doesn't specify anything that Harvester doesn't support, storage-pools are usually referring to aggregations of multiple devices in such a way, that the volumes' storage capacities can exceed the capacity of any single device. This specifically is not the case for Longhorn, which provides the (default) storage engine for Harvester workloads. With Longhorn the storage is replicated across devices, but the capacity of the devices isn't pooled together. As a result, the maximum volume size can not exceed the capacity of the individual devices.
While it's theoretically possible to aggregate multiple disks within one node by using Longhorn on top of an LVM, this configuration is AFAIK not supported officially and I'm sure it would be quite a challenge to even set it up with Harvester.
Similarly, the maximum compute a single workload (i.e. VM) on Harvester can have is the compute a single node can provide, so there isn't really any pooling going on.

How about:

These servers manage compute, memory and storage resources together to provide an environment for running VMs.

This should accurately capture that Harvester orchestrates these resources across the entire cluster, but this doesn't imply features that Harvester doesn't support.

I understand your concern about using pool given how Longhorn and single-node clusters function. We can use the wording you suggested (with one small change):

These servers collectively manage compute, memory, and storage resources to provide an environment for running VMs.

tserong

LGTM

m-ildefons

LGTM

bk201

Thanks for the work!

jillian-maroket · 2024-04-10T10:46:48Z

@m-ildefons @tserong @bk201 Thank you for providing such valuable feedback.

Create MVP of Harvester glossary per customer request

65750e6

jillian-maroket assigned bk201, markhillgit and ibrokethecloud Mar 29, 2024

m-ildefons reviewed Apr 3, 2024

View reviewed changes

Improve definitions per reviewer feedback

dd15876

m-ildefons reviewed Apr 8, 2024

View reviewed changes

jillian-maroket unassigned bk201, ibrokethecloud and markhillgit Apr 9, 2024

jillian-maroket requested a review from bk201 April 9, 2024 01:29

jillian-maroket added 2 commits April 10, 2024 09:20

Update Harvester cluster definition per feedback

2970726

Fix typo in Rancher term

95e92ee

tserong approved these changes Apr 10, 2024

View reviewed changes

m-ildefons approved these changes Apr 10, 2024

View reviewed changes

bk201 approved these changes Apr 10, 2024

View reviewed changes

jillian-maroket merged commit d5cbe82 into harvester:main Apr 10, 2024

jillian-maroket mentioned this pull request Apr 10, 2024

Add glossary to all versions #546

Merged

jillian-maroket deleted the glossary-v1 branch June 20, 2025 11:26

jillian-maroket mentioned this pull request Jan 15, 2026

Add glossary entries for commonly used terms #947

Open


		## guest cluster / guest Kubernetes cluster

		Group of integrated Kubernetes worker machines that are running in a VM that is part of a Harvester cluster. Guest clusters form the underlying infrastructure for running containerized workloads.


		## guest cluster node / guest node

		Kubernetes worker machine that uses guest cluster resources to run workloads.


		Harvester cluster

		Group of integrated physical servers (hosts) on which the Harvester hypervisor is installed. These servers pool compute and storage resources to provide an environment for running VMs that can host guest clusters.

Create Harvester glossary per customer request #539

Create Harvester glossary per customer request #539

Uh oh!

Conversation

jillian-maroket commented Mar 29, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

harvesterhci-io-github-bot commented Mar 29, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for harvester-preview ready!

Uh oh!

jillian-maroket commented Apr 3, 2024

Uh oh!

m-ildefons left a comment

Choose a reason for hiding this comment

Uh oh!

m-ildefons Apr 3, 2024

Choose a reason for hiding this comment

Uh oh!

tserong Apr 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jillian-maroket Apr 8, 2024

Choose a reason for hiding this comment

Uh oh!

m-ildefons Apr 3, 2024

Choose a reason for hiding this comment

Uh oh!

tserong Apr 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jillian-maroket Apr 8, 2024

Choose a reason for hiding this comment

Uh oh!

m-ildefons left a comment

Choose a reason for hiding this comment

Uh oh!

m-ildefons Apr 8, 2024

Choose a reason for hiding this comment

Uh oh!

jillian-maroket Apr 10, 2024

Choose a reason for hiding this comment

Uh oh!

tserong left a comment

Choose a reason for hiding this comment

Uh oh!

m-ildefons left a comment

Choose a reason for hiding this comment

Uh oh!

bk201 left a comment

Choose a reason for hiding this comment

Uh oh!

jillian-maroket commented Apr 10, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

jillian-maroket commented Mar 29, 2024 •

edited

Loading

harvesterhci-io-github-bot commented Mar 29, 2024 •

edited

Loading

tserong Apr 4, 2024 •

edited

Loading

tserong Apr 4, 2024 •

edited

Loading