Skip to content

Commit 0a81439

Browse files
StephenJamesSmithStephenJamesSmith
committed
TELCODOCS-1109: First draft
1 parent 04d3fa6 commit 0a81439

8 files changed

+268
-0
lines changed

‎hardware_enablement/kmm-kernel-module-management.adoc

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,29 @@ include::modules/kmm-building-and-signing-a-moduleloader-container-image.adoc[le
8383
.Additional resources
8484
For information on creating a service account, see link:https://docs.openshift.com/container-platform/4.12/authentication/understanding-and-creating-service-accounts.html#service-accounts-managing_understanding-service-accounts[Creating service accounts].
8585
86+
// Added for TELCODOCS-1109
87+
include::modules/kmm-hub-hub-and-spoke.adoc[leveloffset=+1]
88+
[role="_additional-resources"]
89+
.Additional resources
90+
* link:https://www.redhat.com/en/technologies/management/advanced-cluster-management[Red{nbsp}Hat Advanced Cluster Management (RHACM)]
91+
92+
include::modules/kmm-hub-kmm-hub.adoc[leveloffset=+2]
93+
[role="_additional-resources"]
94+
.Additional resources
95+
* link:https://openshift-kmm.netlify.app/documentation/install/[Installing KMM]
96+
97+
include::modules/kmm-hub-installing-kmm-hub.adoc[leveloffset=+2]
98+
[role="_additional-resources"]
99+
.Additional resources
100+
* link:https://catalog.redhat.com/software/containers/kmm/kernel-module-management-hub-operator-bundle/63d84cc33862da54bb19b8c6?architecture=amd64&image=654273ac86f7e537ae452f6ehttps://catalog.redhat.com/software/containers/kmm/kernel-module-management-hub-operator-bundle/63d84cc33862da54bb19b8c6?architecture=amd64&image=654273ac86f7e537ae452f6e[KMM Operator bundle]
101+
102+
include::modules/kmm-hub-installing-kmm-hub-olm.adoc[leveloffset=+3]
103+
include::modules/kmm-hub-installing-kmm-hub-creating-resources.adoc[leveloffset=+3]
104+
105+
include::modules/kmm-hub-using-the-managedclustermodule.adoc[leveloffset=+2]
106+
include::modules/kmm-hub-running-kmm-on-the-spoke.adoc[leveloffset=+2]
107+
108+
86109
// Added for TELCODOCS-1277
87110
include::modules/kmm-customizing-upgrades-for-kernel-modules.adoc[leveloffset=+1]
88111

‎modules/kmm-hub-hub-and-spoke.adoc

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hardware_enablement/kmm-kernel-module-management.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="kmm-hub-hub-and-spoke_{context}"]
7+
= KMM hub and spoke
8+
9+
In hub and spoke scenarios, many spoke clusters are connected to a central, powerful hub cluster. Kernel Module Management (KMM) depends on Red{nbsp}Hat Advanced Cluster Management (RHACM) to operate in hub and spoke environments.
10+
11+
KMM is compatible with hub and spoke environments through decoupling KMM features. A `ManagedClusterModule` Custom Resource Definition (CRD) is provided to wrap the existing `Module` CRD and extend it to select Spoke clusters. Also provided is KMM-Hub, a new standalone controller that builds images and signs modules on the hub cluster.
12+
13+
In hub and spoke setups, spokes are focused, resource-constrained clusters that are centrally managed by a hub cluster. Spokes run the single-cluster edition of KMM, with those resource-intensive features disabled. To adapt KMM to this environment, you should reduce the workload running on the spokes to the minimum, while the hub takes care of the expensive tasks.
14+
15+
Building kernel module images and signing the `.ko` files, should run on the hub. The scheduling of the Module Loader and Device Plugin `DaemonSets` can only happen on the spokes.

‎modules/kmm-hub-installing-kmm-hub-creating-resources.adoc

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hardware_enablement/kmm-kernel-module-management.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="kmm-hub-installing-kmm-hub-creating-resources_{context}"]
7+
= Installing KMM-Hub by creating KMM resources
8+
9+
.Procedure
10+
11+
* If you want to install KMM-Hub programmatically, you can use the following resources to create
12+
the `Namespace`, `OperatorGroup` and `Subscription` resources:
13+
14+
[source,yaml]
15+
----
16+
---
17+
apiVersion: v1
18+
kind: Namespace
19+
metadata:
20+
name: openshift-kmm-hub
21+
---
22+
apiVersion: operators.coreos.com/v1
23+
kind: OperatorGroup
24+
metadata:
25+
name: kernel-module-management-hub
26+
namespace: openshift-kmm-hub
27+
---
28+
apiVersion: operators.coreos.com/v1alpha1
29+
kind: Subscription
30+
metadata:
31+
name: kernel-module-management-hub
32+
namespace: openshift-kmm-hub
33+
spec:
34+
channel: stable
35+
installPlanApproval: Automatic
36+
name: kernel-module-management-hub
37+
source: redhat-operators
38+
sourceNamespace: openshift-marketplace
39+
----

‎modules/kmm-hub-installing-kmm-hub-olm.adoc

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hardware_enablement/kmm-kernel-module-management.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="kmm-hub-installing-kmm-hub-olm_{context}"]
7+
= Installing KMM-Hub using the Operator Lifecycle Manager
8+
9+
Use the *Operators* section of the OpenShift console to install KMM-Hub.

‎modules/kmm-hub-installing-kmm-hub.adoc

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hardware_enablement/kmm-kernel-module-management.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="kmm-hub-installing-kmm-hub_{context}"]
7+
= Installing KMM-Hub
8+
9+
You can use one of the following methods to install KMM-Hub:
10+
11+
* Using the Operator Lifecycle Manager (OLM)
12+
* Creating KMM resources

‎modules/kmm-hub-kmm-hub.adoc

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hardware_enablement/kmm-kernel-module-management.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="kmm-hub-kmm-hub_{context}"]
7+
= KMM-Hub
8+
9+
The KMM project provides KMM-Hub, an edition of KMM dedicated to hub clusters. KMM-Hub monitors all kernel versions running on the spokes and determines the nodes on the cluster that should receive a kernel module.
10+
11+
KMM-Hub runs all compute-intensive tasks such as image builds and kmod signing, and prepares the trimmed-down `Module` to be transferred to the spokes through RHACM.
12+
13+
[NOTE]
14+
====
15+
KMM-Hub cannot be used to load kernel modules on the hub cluster. Install the regular edition of KMM to load kernel modules.
16+
====

‎modules/kmm-hub-running-kmm-on-the-spoke.adoc

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hardware_enablement/kmm-kernel-module-management.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="kmm-hub-running-kmm-on-the-spoke_{context}"]
7+
= Running KMM on the spoke
8+
9+
After installing KMM on the spoke, no further action is required. Create a `ManagedClusterModule` object from the hub to deploy kernel modules on spoke clusters.
10+
11+
.Procedure
12+
13+
You can install KMM on the spokes cluster through a RHACM `Policy` object.
14+
In addition to installing KMM from the Operator hub and running it in a lightweight spoke mode,
15+
the `Policy` configures additional RBAC required for the RHACM agent to be able to manage `Module` resources.
16+
17+
* Use the following RHACM policy to install KMM on spoke clusters:
18+
+
19+
[source.yaml]
20+
[%collapsible]
21+
----
22+
---
23+
apiVersion: policy.open-cluster-management.io/v1
24+
kind: Policy
25+
metadata:
26+
name: install-kmm
27+
spec:
28+
remediationAction: enforce
29+
disabled: false
30+
policy-templates:
31+
- objectDefinition:
32+
apiVersion: policy.open-cluster-management.io/v1
33+
kind: ConfigurationPolicy
34+
metadata:
35+
name: install-kmm
36+
spec:
37+
severity: high
38+
object-templates:
39+
- complianceType: mustonlyhave
40+
objectDefinition:
41+
apiVersion: v1
42+
kind: Namespace
43+
metadata:
44+
name: openshift-kmm
45+
- complianceType: mustonlyhave
46+
objectDefinition:
47+
apiVersion: operators.coreos.com/v1
48+
kind: OperatorGroup
49+
metadata:
50+
name: kmm
51+
namespace: openshift-kmm
52+
spec:
53+
upgradeStrategy: Default
54+
- complianceType: mustonlyhave
55+
objectDefinition:
56+
apiVersion: operators.coreos.com/v1alpha1
57+
kind: Subscription
58+
metadata:
59+
name: kernel-module-management
60+
namespace: openshift-kmm
61+
spec:
62+
channel: stable
63+
config:
64+
env:
65+
- name: KMM_MANAGED
66+
value: "1"
67+
installPlanApproval: Automatic
68+
name: kernel-module-management
69+
source: redhat-operators
70+
sourceNamespace: openshift-marketplace
71+
- complianceType: mustonlyhave
72+
objectDefinition:
73+
apiVersion: rbac.authorization.k8s.io/v1
74+
kind: ClusterRole
75+
metadata:
76+
name: kmm-module-manager
77+
rules:
78+
- apiGroups: [kmm.sigs.x-k8s.io]
79+
resources: [modules]
80+
verbs: [create, delete, get, list, patch, update, watch]
81+
- complianceType: mustonlyhave
82+
objectDefinition:
83+
apiVersion: rbac.authorization.k8s.io/v1
84+
kind: ClusterRoleBinding
85+
metadata:
86+
name: klusterlet-kmm
87+
subjects:
88+
- kind: ServiceAccount
89+
name: klusterlet-work-sa
90+
namespace: open-cluster-management-agent
91+
roleRef:
92+
kind: ClusterRole
93+
name: kmm-module-manager
94+
apiGroup: rbac.authorization.k8s.io
95+
---
96+
apiVersion: apps.open-cluster-management.io/v1
97+
kind: PlacementRule
98+
metadata:
99+
name: all-managed-clusters
100+
spec:
101+
clusterSelector: <1>
102+
matchExpressions: []
103+
---
104+
apiVersion: policy.open-cluster-management.io/v1
105+
kind: PlacementBinding
106+
metadata:
107+
name: install-kmm
108+
placementRef:
109+
apiGroup: apps.open-cluster-management.io
110+
kind: PlacementRule
111+
name: all-managed-clusters
112+
subjects:
113+
- apiGroup: policy.open-cluster-management.io
114+
kind: Policy
115+
name: install-kmm
116+
----
117+
<1> The `spec.clusterSelector` field can be customized to target select clusters only.

‎modules/kmm-hub-using-the-managedclustermodule.adoc

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * hardware_enablement/kmm-kernel-module-management.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="kmm-hub-using-the-managedclustermodule_{context}"]
7+
= Using the `ManagedClusterModule` CRD
8+
9+
Use the `ManagedClusterModule` Custom Resource Definition (CRD) to configure the deployment of kernel modules on spoke clusters.
10+
This CRD is cluster-scoped, wraps a `Module` spec and adds the following additional fields:
11+
12+
[source,yaml]
13+
----
14+
apiVersion: hub.kmm.sigs.x-k8s.io/v1beta1
15+
kind: ManagedClusterModule
16+
metadata:
17+
name: <my-mcm>
18+
# No namespace, because this resource is cluster-scoped.
19+
spec:
20+
moduleSpec: <1>
21+
selector: <2>
22+
node-wants-my-mcm: 'true'
23+
24+
spokeNamespace: <some-namespace> <3>
25+
26+
selector: <4>
27+
wants-my-mcm: 'true'
28+
----
29+
<1> `moduleSpec`: Contains `moduleLoader` and `devicePlugin` sections, similar to a `Module` resource.
30+
31+
<2> Selects nodes within the `ManagedCluster`.
32+
<3> Specifies in which namespace the `Module` should be created.
33+
<4> Selects `ManagedCluster` objects.
34+
35+
If build or signing instructions are present in `.spec.moduleSpec`, those pods are run on the hub cluster in the operator's namespace.
36+
37+
When the `.spec.selector matches` one or more `ManagedCluster` resources, then KMM-Hub creates a `ManifestWork` resource in the corresponding namespace(s). `ManifestWork` contains a trimmed-down `Module` resource, with kernel mappings preserved but all `build` and `sign` subsections are removed. `containerImage` fields that contain image names ending with a tag are replaced with their digest equivalent.

0 commit comments

Comments
 (0)