Skip to content

Commit 8e966cd

Browse files
lahinsonlahinson
authored
Merge pull request #81178 from lahinson/osdocs-11001-add-virt-links
[OSDOCS-11001]: Adding more virt docs for HCP
2 parents e5d9c45 + 1e7947e commit 8e966cd

File tree

9 files changed

+330
-0
lines changed

9 files changed

+330
-0
lines changed

‎hosted_control_planes/hcp-deploy/hcp-deploy-virt.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@ include::modules/hcp-virt-create-hc-console.adoc[leveloffset=+2]
4242

4343
* To create credentials that you can reuse when you create a hosted cluster with the console, see link:https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_management_for_kubernetes/2.11/html/clusters/cluster_mce_overview#creating-a-credential-for-an-on-premises-environment[Creating a credential for an on-premises environment].
4444

45+
* To access the hosted cluster, see xref:../../hosted_control_planes/hcp-manage/hcp-manage-virt.adoc#hcp-virt-access_hcp-manage-virt[Accessing the hosted cluster].
46+
4547
include::modules/hcp-virt-ingress-dns.adoc[leveloffset=+1]
4648

4749
[id="hcp-virt-ingress-dns-custom"]

‎hosted_control_planes/hcp-manage/hcp-manage-virt.adoc‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,47 @@ include::_attributes/common-attributes.adoc[]
66

77
toc::[]
88

9+
After you deploy a hosted cluster on {VirtProductName}, you can manage the cluster by completing the following procedures.
10+
11+
include::modules/hcp-virt-access.adoc[leveloffset=+1]
12+
13+
[id="hcp-virt-storage"]
14+
== Configuring storage for {hcp} on {VirtProductName}
15+
16+
If you do not provide any advanced storage configuration, the default storage class is used for the KubeVirt virtual machine (VM) images, the KubeVirt Container Storage Interface (CSI) mapping, and the etcd volumes.
17+
18+
The following table lists the capabilities that the infrastructure must provide to support persistent storage in a hosted cluster:
19+
20+
.Persistent storage modes in a hosted cluster
21+
|===
22+
| Infrastructure CSI provider | Hosted cluster CSI provider | Hosted cluster capabilities | Notes
23+
24+
| Any RWX `Block` CSI provider
25+
| `kubevirt-csi`
26+
| Basic: RWO `Block` and `File`, RWX `Block` and `Snapshot`
27+
| Recommended
28+
29+
| Any RWX `Block` CSI provider
30+
| {rh-storage-first} external mode
31+
| {rh-storage-first} feature set
32+
|
33+
34+
| Any RWX `Block` CSI provider
35+
| {rh-storage-first} internal mode
36+
| {rh-storage-first} feature set
37+
| Do not use
38+
39+
|===
40+
41+
include::modules/hcp-virt-map-storage.adoc[leveloffset=+2]
42+
include::modules/hcp-virt-csi-snapshot.adoc[leveloffset=+2]
43+
include::modules/hcp-virt-multiple-snapshots.adoc[leveloffset=+2]
44+
include::modules/hcp-virt-root-volume.adoc[leveloffset=+2]
45+
include::modules/hcp-virt-image-caching.adoc[leveloffset=+2]
46+
47+
[role="_additional-resources"]
48+
.Additional resources
49+
50+
* xref:../../virt/virtual_machines/creating_vms_custom/virt-creating-vms-by-cloning-pvcs.adoc#smart-cloning_virt-creating-vms-by-cloning-pvcs[Cloning a data volume using smart-cloning]
51+
52+
include::modules/hcp-virt-etcd-storage.adoc[leveloffset=+2]

‎modules/hcp-virt-access.adoc‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hosted_control_planes/hcp-manage/hcp-manage-virt.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="hcp-virt-access_{context}"]
7+
= Accessing the hosted cluster
8+
9+
You can access the hosted cluster by either getting the `kubeconfig` file and `kubeadmin` credential directly from resources, or by using the `hcp` command line interface to generate a `kubeconfig` file.
10+
11+
.Prerequisites
12+
13+
To access the hosted cluster by getting the `kubeconfig` file and credentials directly from resources, you need to be familiar with the access secrets for hosted control plane clusters. The secrets are stored in the hosted cluster (hosting) namespace. The _hosted cluster (hosting)_ namespace contains hosted cluster resources, and the _hosted control plane_ namespace is where the hosted control plane runs.
14+
15+
The secret name formats are as follows:
16+
17+
** `kubeconfig` secret: `<hosted_cluster_namespace>-<name>-admin-kubeconfig` (clusters-hypershift-demo-admin-kubeconfig)
18+
** `kubeadmin` password secret: `<hosted_cluster_namespace>-<name>-kubeadmin-password` (clusters-hypershift-demo-kubeadmin-password)
19+
20+
The `kubeconfig` secret contains a Base64-encoded `kubeconfig` field, which you can decode and save into a file to use with the following command:
21+
22+
[source,terminal]
23+
----
24+
$ oc --kubeconfig <hosted_cluster_name>.kubeconfig get nodes
25+
----
26+
27+
The `kubeadmin` password secret is also Base64-encoded. You can decode it and use the password to log in to the API server or console of the hosted cluster.
28+
29+
.Procedure
30+
31+
* To access the hosted cluster by using the `hcp` CLI to generate the `kubeconfig` file, take the following steps:
32+
33+
. Generate the `kubeconfig` file by entering the following command:
34+
+
35+
[source,terminal]
36+
----
37+
$ hcp create kubeconfig --namespace <hosted_cluster_namespace> --name <hosted_cluster_name> > <hosted_cluster_name>.kubeconfig
38+
----
39+
40+
. After you save the `kubeconfig` file, you can access the hosted cluster by entering the following example command:
41+
+
42+
[source,terminal]
43+
----
44+
$ oc --kubeconfig <hosted_cluster_name>.kubeconfig get nodes
45+
----

‎modules/hcp-virt-csi-snapshot.adoc‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hosted_control_planes/hcp-manage/hcp-manage-virt.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="hcp-virt-csi-snapshot_{context}"]
7+
= Mapping a single KubeVirt CSI volume snapshot class
8+
9+
You can expose your infrastructure volume snapshot class to the hosted cluster by using KubeVirt CSI.
10+
11+
.Procedure
12+
13+
* To map your volume snapshot class to the hosted cluster, use the `--infra-volumesnapshot-class-mapping` argument when creating a hosted cluster. Run the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ hcp create cluster kubevirt \
18+
--name <hosted_cluster_name> \ <1>
19+
--node-pool-replicas <worker_node_count> \ <2>
20+
--pull-secret <path_to_pull_secret> \ <3>
21+
--memory <memory> \ <4>
22+
--cores <cpu> \ <5>
23+
--infra-storage-class-mapping=<infrastructure_storage_class>/<hosted_storage_class> \ <6>
24+
--infra-volumesnapshot-class-mapping=<infrastructure_volume_snapshot_class>/<hosted_volume_snapshot_class> <7>
25+
----
26+
+
27+
<1> Specify the name of your hosted cluster, for instance, `example`.
28+
<2> Specify the worker count, for example, `2`.
29+
<3> Specify the path to your pull secret, for example, `/user/name/pullsecret`.
30+
<4> Specify a value for memory, for example, `8Gi`.
31+
<5> Specify a value for CPU, for example, `2`.
32+
<6> Replace `<infrastructure_storage_class>` with the storage class present in the infrastructure cluster. Replace `<hosted_storage_class>` with the storage class present in the hosted cluster.
33+
<7> Replace `<infrastructure_volume_snapshot_class>` with the volume snapshot class present in the infrastructure cluster. Replace `<hosted_volume_snapshot_class>` with the volume snapshot class present in the hosted cluster.
34+
+
35+
[NOTE]
36+
====
37+
If you do not use the `--infra-storage-class-mapping` and `--infra-volumesnapshot-class-mapping` arguments, a hosted cluster is created with the default storage class and the volume snapshot class. Therefore, you must set the default storage class and the volume snapshot class in the infrastructure cluster.
38+
====

‎modules/hcp-virt-etcd-storage.adoc‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hosted_control_planes/hcp-manage/hcp-manage-virt.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="hcp-virt-etcd-storage_{context}"]
7+
= Configuring etcd storage
8+
9+
At cluster creation time, you can configure the storage class that is used to host etcd data by using the `--etcd-storage-class` argument.
10+
11+
.Procedure
12+
13+
* To configure a storage class for etcd, run the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ hcp create cluster kubevirt \
18+
--name <hosted_cluster_name> \ <1>
19+
--node-pool-replicas <worker_node_count> \ <2>
20+
--pull-secret <path_to_pull_secret> \ <3>
21+
--memory <memory> \ <4>
22+
--cores <cpu> \ <5>
23+
--etcd-storage-class=<etcd_storage_class_name> <6>
24+
----
25+
+
26+
<1> Specify the name of your hosted cluster, for instance, `example`.
27+
<2> Specify the worker count, for example, `2`.
28+
<3> Specify the path to your pull secret, for example, `/user/name/pullsecret`.
29+
<4> Specify a value for memory, for example, `8Gi`.
30+
<5> Specify a value for CPU, for example, `2`.
31+
<6> Specify the etcd storage class name, for example, `lvm-storageclass`. If you do not provide an `--etcd-storage-class` argument, the default storage class is used.

‎modules/hcp-virt-image-caching.adoc‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hosted_control_planes/hcp-manage/hcp-manage-virt.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="hcp-virt-image-caching_{context}"]
7+
= Enabling KubeVirt VM image caching
8+
9+
You can use KubeVirt VM image caching to optimize both cluster startup time and storage usage. KubeVirt VM image caching supports the use of a storage class that is capable of smart cloning and the `ReadWriteMany` access mode. For more information about smart cloning, see _Cloning a data volume using smart-cloning_.
10+
11+
Image caching works as follows:
12+
13+
. The VM image is imported to a PVC that is associated with the hosted cluster.
14+
. A unique clone of that PVC is created for every KubeVirt VM that is added as a worker node to the cluster.
15+
16+
Image caching reduces VM startup time by requiring only a single image import. It can further reduce overall cluster storage usage when the storage class supports copy-on-write cloning.
17+
18+
.Procedure
19+
20+
* To enable image caching, during cluster creation, use the `--root-volume-cache-strategy=PVC` argument by running the following command:
21+
+
22+
[source,terminal]
23+
----
24+
$ hcp create cluster kubevirt \
25+
--name <hosted_cluster_name> \ <1>
26+
--node-pool-replicas <worker_node_count> \ <2>
27+
--pull-secret <path_to_pull_secret> \ <3>
28+
--memory <memory> \ <4>
29+
--cores <cpu> \ <5>
30+
--root-volume-cache-strategy=PVC <6>
31+
----
32+
+
33+
<1> Specify the name of your hosted cluster, for instance, `example`.
34+
<2> Specify the worker count, for example, `2`.
35+
<3> Specify the path to your pull secret, for example, `/user/name/pullsecret`.
36+
<4> Specify a value for memory, for example, `8Gi`.
37+
<5> Specify a value for CPU, for example, `2`.
38+
<6> Specify a strategy for image caching, for example, `PVC`.

‎modules/hcp-virt-map-storage.adoc‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hosted_control_planes/hcp-manage/hcp-manage-virt.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="hcp-virt-map-storage_{context}"]
7+
= Mapping KubeVirt CSI storage classes
8+
9+
KubeVirt CSI supports mapping a infrastructure storage class that is capable of `ReadWriteMany` (RWX) access. You can map the infrastructure storage class to hosted storage class during cluster creation.
10+
11+
.Procedure
12+
13+
* To map the infrastructure storage class to the hosted storage class, use the `--infra-storage-class-mapping` argument by running the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ hcp create cluster kubevirt \
18+
--name <hosted_cluster_name> \ <1>
19+
--node-pool-replicas <worker_node_count> \ <2>
20+
--pull-secret <path_to_pull_secret> \ <3>
21+
--memory <memory> \ <4>
22+
--cores <cpu> \ <5>
23+
--infra-storage-class-mapping=<infrastructure_storage_class>/<hosted_storage_class> \ <6>
24+
----
25+
+
26+
<1> Specify the name of your hosted cluster, for instance, `example`.
27+
<2> Specify the worker count, for example, `2`.
28+
<3> Specify the path to your pull secret, for example, `/user/name/pullsecret`.
29+
<4> Specify a value for memory, for example, `8Gi`.
30+
<5> Specify a value for CPU, for example, `2`.
31+
<6> Replace `<infrastructure_storage_class>` with the infrastructure storage class name and `<hosted_storage_class>` with the hosted cluster storage class name. You can use the `--infra-storage-class-mapping` argument multiple times within the `hcp create cluster` command.
32+
33+
After you create the hosted cluster, the infrastructure storage class is visible within the hosted cluster. When you create a Persistent Volume Claim (PVC) within the hosted cluster that uses one of those storage classes, KubeVirt CSI provisions that volume by using the infrastructure storage class mapping that you configured during cluster creation.
34+
35+
[NOTE]
36+
====
37+
KubeVirt CSI supports mapping only an infrastructure storage class that is capable of RWX access.
38+
====
39+
40+
The following table shows how volume and access mode capabilities map to KubeVirt CSI storage classes:
41+
42+
.Mapping KubeVirt CSI storage classes to access and volume modes
43+
|===
44+
| Infrastructure CSI capability | Hosted cluster CSI capability | VM live migration support | Notes
45+
46+
| RWX: `Block` or `Filesystem`
47+
| `ReadWriteOnce` (RWO) `Block` or `Filesystem` RWX `Block` only
48+
| Supported
49+
| Use `Block` mode because `Filesystem` volume mode results in degraded hosted `Block` mode performance. RWX `Block` volume mode is supported only when the hosted cluster is {ocp-short} 4.16 or later.
50+
51+
| RWO `Block` storage
52+
| RWO `Block` storage or `Filesystem`
53+
| Not supported
54+
| Lack of live migration support affects the ability to update the underlying infrastructure cluster that hosts the KubeVirt VMs.
55+
56+
| RWO `FileSystem`
57+
| RWO `Block` or `Filesystem`
58+
| Not supported
59+
| Lack of live migration support affects the ability to update the underlying infrastructure cluster that hosts the KubeVirt VMs. Use of the infrastructure `Filesystem` volume mode results in degraded hosted `Block` mode performance.
60+
61+
|===

‎modules/hcp-virt-multiple-snapshots.adoc‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hosted_control_planes/hcp-manage/hcp-manage-virt.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="hcp-virt-multiple-snapshots_{context}"]
7+
= Mapping multiple KubeVirt CSI volume snapshot classes
8+
9+
You can map multiple volume snapshot classes to the hosted cluster by assigning them to a specific group. The infrastructure storage class and the volume snapshot class are compatible with each other only if they belong to a same group.
10+
11+
.Procedure
12+
13+
* To map multiple volume snapshot classes to the hosted cluster, use the `group` option when creating a hosted cluster. Run the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ hcp create cluster kubevirt \
18+
--name <hosted_cluster_name> \ <1>
19+
--node-pool-replicas <worker_node_count> \ <2>
20+
--pull-secret <path_to_pull_secret> \ <3>
21+
--memory <memory> \ <4>
22+
--cores <cpu> \ <5>
23+
--infra-storage-class-mapping=<infrastructure_storage_class>/<hosted_storage_class>,group=<group_name> \ <6>
24+
--infra-storage-class-mapping=<infrastructure_storage_class>/<hosted_storage_class>,group=<group_name> \
25+
--infra-storage-class-mapping=<infrastructure_storage_class>/<hosted_storage_class>,group=<group_name> \
26+
--infra-volumesnapshot-class-mapping=<infrastructure_volume_snapshot_class>/<hosted_volume_snapshot_class>,group=<group_name> \ <7>
27+
--infra-volumesnapshot-class-mapping=<infrastructure_volume_snapshot_class>/<hosted_volume_snapshot_class>,group=<group_name>
28+
----
29+
+
30+
<1> Specify the name of your hosted cluster, for instance, `example`.
31+
<2> Specify the worker count, for example, `2`.
32+
<3> Specify the path to your pull secret, for example, `/user/name/pullsecret`.
33+
<4> Specify a value for memory, for example, `8Gi`.
34+
<5> Specify a value for CPU, for example, `2`.
35+
<6> Replace `<infrastructure_storage_class>` with the storage class present in the infrastructure cluster. Replace `<hosted_storage_class>` with the storage class present in the hosted cluster. Replace `<group_name>` with the group name. For example, `infra-storage-class-mygroup/hosted-storage-class-mygroup,group=mygroup` and `infra-storage-class-mymap/hosted-storage-class-mymap,group=mymap`.
36+
<7> Replace `<infrastructure_volume_snapshot_class>` with the volume snapshot class present in the infrastructure cluster. Replace `<hosted_volume_snapshot_class>` with the volume snapshot class present in the hosted cluster. For example, `infra-vol-snap-mygroup/hosted-vol-snap-mygroup,group=mygroup` and `infra-vol-snap-mymap/hosted-vol-snap-mymap,group=mymap`.

‎modules/hcp-virt-root-volume.adoc‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hosted_control_planes/hcp-manage/hcp-manage-virt.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="hcp-virt-root-volume_{context}"]
7+
= Configuring KubeVirt VM root volume
8+
9+
At cluster creation time, you can configure the storage class that is used to host the KubeVirt VM root volumes by using the `--root-volume-storage-class` argument.
10+
11+
.Procedure
12+
13+
* To set a custom storage class and volume size for KubeVirt VMs, run the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ hcp create cluster kubevirt \
18+
--name <hosted_cluster_name> \ <1>
19+
--node-pool-replicas <worker_node_count> \ <2>
20+
--pull-secret <path_to_pull_secret> \ <3>
21+
--memory <memory> \ <4>
22+
--cores <cpu> \ <5>
23+
--root-volume-storage-class <root_volume_storage_class> \ <6>
24+
--root-volume-size <volume_size> <7>
25+
----
26+
+
27+
<1> Specify the name of your hosted cluster, for instance, `example`.
28+
<2> Specify the worker count, for example, `2`.
29+
<3> Specify the path to your pull secret, for example, `/user/name/pullsecret`.
30+
<4> Specify a value for memory, for example, `8Gi`.
31+
<5> Specify a value for CPU, for example, `2`.
32+
<6> Specify a name of the storage class to host the KubeVirt VM root volumes, for example, `ocs-storagecluster-ceph-rbd`.
33+
<7> Specify the volume size, for example, `64`.
34+
+
35+
As a result, you get a hosted cluster created with VMs hosted on PVCs.

0 commit comments

Comments
 (0)