Skip to content

Commit b0a071d

Browse files
jeana-redhatjeana-redhat
authored
Merge pull request #52802 from jeana-redhat/OSDOCS-4238-CPMS-setup-and-limitations
[OSDOCS-4238]: CPMSO getting started and limitations
2 parents 26a1715 + 05bd888 commit b0a071d

File tree

8 files changed

+207
-16
lines changed

8 files changed

+207
-16
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1967,8 +1967,8 @@ Topics:
19671967
Topics:
19681968
- Name: About the Control Plane Machine Set Operator
19691969
File: cpmso-about
1970-
#- Name: Getting started
1971-
# File: cpmso-getting-started
1970+
- Name: Getting started
1971+
File: cpmso-getting-started
19721972
- Name: Control Plane Machine Set Operator configuration
19731973
File: cpmso-configuration
19741974
#- Name: Using the Control Plane Machine Set Operator

‎machine_management/control_plane_machine_management/cpmso-about.adoc

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,23 @@ include::modules/cpmso-overview.adoc[leveloffset=+1]
2222
[id="cpmso-limitations_{context}"]
2323
== Limitations
2424

25-
In {product-title} {product-version}, the Control Plane Machine Set Operator has the following limitations:
25+
The Control Plane Machine Set Operator has the following limitations:
26+
27+
* The Operator requires the Machine API to be operational and is therefore not supported on clusters with manually provisioned machines.
28+
29+
* Only Amazon Web Services (AWS), Microsoft Azure, and VMware vSphere clusters are supported.
2630

2731
* Only clusters with three control plane machines are supported.
2832

2933
* Horizontal scaling of the control plane is not supported.
34+
35+
* Deploying Azure control plane machines on Ephemeral OS disks increases risk for data loss and is not supported.
36+
37+
* Deploying control plane machines as AWS Spot Instances or Azure Spot VMs is not supported.
38+
+
39+
[IMPORTANT]
40+
====
41+
Attempting to deploy control plane machines as AWS Spot Instances or Azure Spot VMs might cause the cluster to lose etcd quorum. A cluster that loses all control plane machines simultaneously is unrecoverable.
42+
====
43+
44+
* Making changes to the control plane machine set during or prior to installation is not supported. You must make any changes to the control plane machine set only after installation.

‎machine_management/control_plane_machine_management/cpmso-getting-started.adoc

Lines changed: 43 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,37 +6,71 @@ include::_attributes/common-attributes.adoc[]
66

77
toc::[]
88

9-
For AWS, {product-title} clusters that are created with version 4.12 or later use the Control Plane Machine Set Operator by default.
9+
The process for getting started with the Control Plane Machine Set Operator depends on the state of the `ControlPlaneMachineSet` custom resource (CR) in your cluster.
1010

11-
To use this Operator on AWS clusters that are upgraded to {product-title} version 4.12 or later from an earlier version, you must xref:../../machine_management/control_plane_machine_management/cpmso-getting-started.adoc#cpmso-activating_cpmso-getting-started[activate the Operator].
11+
Clusters with an active generated CR:: Clusters that have a generated CR with an active state use the Operator by default. No administrator action is required.
12+
//+
13+
//AWS clusters that are created with {product-title} version 4.12 or later use the Control Plane Machine Set Operator by default.
1214

13-
For Azure and VMware vSphere clusters, you must xref:../../machine_management/control_plane_machine_management/cpmso-getting-started.adoc#cpmso-creating-cr_cpmso-getting-started[create a `ControlPlaneMachineSet` custom resource (CR)] and then xref:../../machine_management/control_plane_machine_management/cpmso-getting-started.adoc#cpmso-activating_cpmso-getting-started[activate the Operator].
15+
Clusters with an inactive generated CR:: For clusters that include an inactive generated CR, you must review the CR configuration and xref:../../machine_management/control_plane_machine_management/cpmso-getting-started.adoc#cpmso-activating_cpmso-getting-started[activate the CR].
16+
//+
17+
//AWS clusters that are upgraded to {product-title} version 4.12 or later from an earlier version include an inactive generated CR.
18+
19+
Clusters without a generated CR:: For clusters that do not include a generated CR, you must xref:../../machine_management/control_plane_machine_management/cpmso-getting-started.adoc#cpmso-creating-cr_cpmso-getting-started[create and activate a CR] with the appropriate configuration for your cluster.
20+
//+
21+
//For Azure and VMware vSphere clusters
22+
23+
If you are uncertain about the state of the `ControlPlaneMachineSet` CR in your cluster, you can xref:../../machine_management/control_plane_machine_management/cpmso-getting-started.adoc#cpmso-checking-status_cpmso-getting-started[verify the CR status].
24+
25+
[discrete]
26+
[id="cpmso-platform-matrix_{context}"]
27+
== Supported cloud providers
28+
29+
In {product-title} {product-version}, the Control Plane Machine Set Operator is supported for Amazon Web Services (AWS), Microsoft Azure, and VMware vSphere clusters.
30+
31+
The status of the Operator after installation depends on your cloud provider and the version of {product-title} that you installed on your cluster.
1432

1533
.Control Plane Machine Set Operator implementation matrix
16-
[cols="<.^3,^.^2,^.^2"]
34+
[cols="<.^5,^.^4,^.^4,^.^4"]
1735
|====
18-
|Cloud provider |Generated CR provided |Manual CR required
36+
|Cloud provider |Active by default |Generated CR |Manual CR required
1937

2038
|Amazon Web Services (AWS)
2139
|X ^[1]^
40+
|X
2241
|
2342

2443
|Microsoft Azure
2544
|
45+
|
2646
|X
2747

2848
|VMware vSphere
2949
|
30-
|X ^[2]^
50+
|
51+
|X
3152
|====
3253
[.small]
3354
--
34-
1. Clusters installed prior to version 4.12 require Operator activation.
35-
2. This provider does not support failure domains.
55+
1. AWS clusters that are upgraded to version 4.12 from an earlier version require xref:../../machine_management/control_plane_machine_management/cpmso-getting-started.adoc#cpmso-activating_cpmso-getting-started[CR activation].
3656
--
3757

58+
//Checking the Control Plane Machine Set Operator status
59+
include::modules/cpmso-checking-status.adoc[leveloffset=+1]
60+
3861
//Activating the Control Plane Machine Set Operator
3962
include::modules/cpmso-activating.adoc[leveloffset=+1]
4063

64+
[role="_additional-resources"]
65+
.Additional resources
66+
* xref:../../machine_management/control_plane_machine_management/cpmso-configuration.adoc#cpmso-configuration[Control Plane Machine Set Operator configuration]
67+
4168
//Creating a control plane machine set custom resource
42-
include::modules/cpmso-creating-cr.adoc[leveloffset=+1]
69+
include::modules/cpmso-creating-cr.adoc[leveloffset=+1]
70+
71+
[role="_additional-resources"]
72+
.Additional resources
73+
* xref:../../machine_management/control_plane_machine_management/cpmso-configuration.adoc#cpmso-configuration[Control Plane Machine Set Operator configuration]
74+
* xref:../../machine_management/control_plane_machine_management/cpmso-configuration.adoc#cpmso-sample-yaml-aws_cpmso-configuration[Sample YAML for configuring Amazon Web Services clusters]
75+
* xref:../../machine_management/control_plane_machine_management/cpmso-configuration.adoc#cpmso-sample-yaml-azure_cpmso-configuration[Sample YAML for configuring Microsoft Azure clusters]
76+
//todo:* [Sample YAML for configuring VMware vSphere clusters]

‎machine_management/control_plane_machine_management/cpmso-troubleshooting.adoc

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

77
toc::[]
88

9+
//todo: add Checking the Control Plane Machine Set Operator status
10+
//include::modules/cpmso-checking-status.adoc[leveloffset=+1]
11+
912
[id="cpmso_ts_ilb_missing_{context}"]
1013
== Internal load balancer missing form Azure provider specification
1114

‎machine_management/control_plane_machine_management/cpmso-using.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,4 @@ include::modules/cpmso-feat-failure-recovery.adoc[leveloffset=+1]
1818
include::modules/cpmso-feat-config-update.adoc[leveloffset=+1]
1919

2020
//Testing changes to the control plane configuration
21-
include::modules/cpmso-feat-test-changes.adoc[leveloffset=+2]
21+
include::modules/cpmso-feat-test-changes.adoc[leveloffset=+2]

‎modules/cpmso-activating.adoc

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,29 @@
44

55
:_content-type: PROCEDURE
66
[id="cpmso-activating_{context}"]
7-
= Activating the Control Plane Machine Set Operator
7+
= Activating the control plane machine set custom resource
88

9-
To use the Control Plane Machine Set Operator on AWS clusters that are upgraded to version 4.12 or later from an earlier version, you must activate the Operator.
9+
To use the Control Plane Machine Set Operator, you must ensure that a `ControlPlaneMachineSet` custom resource (CR) with the correct settings for your cluster exists. On a cluster with a generated CR, you must verify that the configuration in the CR is correct for your cluster and activate it.
10+
11+
[NOTE]
12+
====
13+
For more information about the parameters in the CR, see "Control Plane Machine Set Operator configuration".
14+
====
15+
16+
.Procedure
17+
18+
. View the configuration of the CR by running the following command:
19+
+
20+
[source,terminal]
21+
----
22+
$ oc --namespace openshift-machine-api edit controlplanemachineset.machine.openshift.io cluster
23+
----
24+
25+
. Change the values of any fields that are incorrect for your cluster configuration.
26+
27+
. When the configuration is correct, activate the CR by setting the `.spec.state` field to `Active` and saving your changes.
28+
+
29+
[IMPORTANT]
30+
====
31+
To activate the CR, you must change the `.spec.state` field to `Active` in the same `oc edit` session that you use to update the CR configuration. If the CR is saved with the state left as `Inactive`, the control plane machine set generator resets the CR to its original settings.
32+
====

‎modules/cpmso-checking-status.adoc

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * machine_management/cpmso-getting-started.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="cpmso-checking-status_{context}"]
7+
= Checking the control plane machine set custom resource status
8+
9+
You can verify the existence and status of the `ControlPlaneMachineSet` custom resource (CR).
10+
11+
.Procedure
12+
13+
* Determine the state of the CR by running the following command:
14+
+
15+
[source,terminal]
16+
----
17+
$ oc get controlplanemachineset.machine.openshift.io cluster --namespace openshift-machine-api
18+
----
19+
20+
** A result of `Active` indicates that the `ControlPlaneMachineSet` CR exists and is activated. No administrator action is required.
21+
22+
** A result of `Inactive` indicates that a `ControlPlaneMachineSet` CR exists but is not activated.
23+
24+
** A result of `NotFound` indicates that there is no existing `ControlPlaneMachineSet` CR.
25+
26+
.Next steps
27+
28+
Before using the Operator, you must ensure that a `ControlPlaneMachineSet` CR with the correct settings for your cluster exists.
29+
30+
* If your cluster has an existing CR, you must verify that the configuration in the CR is correct for your cluster.
31+
32+
* If your cluster does not have an existing CR, you must create one with the correct configuration for your cluster.

‎modules/cpmso-creating-cr.adoc

Lines changed: 85 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,88 @@
66
[id="cpmso-creating-cr_{context}"]
77
= Creating a control plane machine set custom resource
88

9-
To use the Control Plane Machine Set Operator on clusters that do not generate a `ControlPlaneMachineSet` custom resource (CR), you must create the CR manually.
9+
To use the Control Plane Machine Set Operator, you must ensure that a `ControlPlaneMachineSet` custom resource (CR) with the correct settings for your cluster exists. On a cluster without a generated CR, you must create the CR manually and activate it.
10+
11+
[NOTE]
12+
====
13+
For more information about the structure and parameters of the CR, see "Control Plane Machine Set Operator configuration".
14+
====
15+
16+
.Procedure
17+
18+
. Create a YAML file using the following template:
19+
+
20+
--
21+
.Control plane machine set CR YAML file template
22+
[source,yaml]
23+
----
24+
apiVersion: machine.openshift.io/v1
25+
kind: ControlPlaneMachineSet
26+
metadata:
27+
name: cluster
28+
namespace: openshift-machine-api
29+
spec:
30+
replicas: 3
31+
selector:
32+
matchLabels:
33+
machine.openshift.io/cluster-api-cluster: <cluster_id> <1>
34+
machine.openshift.io/cluster-api-machine-role: master
35+
machine.openshift.io/cluster-api-machine-type: master
36+
state: Active <2>
37+
strategy:
38+
type: RollingUpdate <3>
39+
template:
40+
machineType: machines_v1beta1_machine_openshift_io
41+
machines_v1beta1_machine_openshift_io:
42+
failureDomains:
43+
platform: <platform> <4>
44+
<platform_failure_domains> <5>
45+
metadata:
46+
labels:
47+
machine.openshift.io/cluster-api-cluster: <cluster_id> <6>
48+
machine.openshift.io/cluster-api-machine-role: master
49+
machine.openshift.io/cluster-api-machine-type: master
50+
spec:
51+
providerSpec:
52+
value:
53+
<platform_provider_spec> <7>
54+
----
55+
<1> Specify the infrastructure ID that is based on the cluster ID that you set when you provisioned the cluster. You must specify this value when you create a `ControlPlaneMachineSet` CR. If you have the OpenShift CLI (`oc`) installed, you can obtain the infrastructure ID by running the following command:
56+
+
57+
[source,terminal]
58+
----
59+
$ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster
60+
----
61+
<2> Specify the state of the Operator. When the state is `Inactive`, the Operator is not operational. You can activate the Operator by setting the value to `Active`.
62+
+
63+
[IMPORTANT]
64+
====
65+
Before you activate the CR, you must ensure that its configuration is correct for your cluster requirements.
66+
====
67+
<3> Specify the update strategy for the cluster. The allowed values are `OnDelete` and `RollingUpdate`. The default value is `RollingUpdate`.
68+
//Todo: For more information about update strategies, see "Updating the control plane configuration".
69+
<4> Specify your cloud provider platform name. The allowed values are `AWS`, `Azure`, and `VSphere`.
70+
<5> Add the `<platform_failure_domains>` configuration for the cluster. The format and values of this section are provider-specific. For more information, see the sample failure domain configuration for your cloud provider.
71+
+
72+
[NOTE]
73+
====
74+
VMware vSphere does not support failure domains. For vSphere clusters, replace `<platform_failure_domains>` with an empty `failureDomains:` parameter.
75+
====
76+
<6> Specify the infrastructure ID.
77+
<7> Add the `<platform_provider_spec>` configuration for the cluster. The format and values of this section are provider-specific. For more information, see the sample provider specification for your cloud provider.
78+
--
79+
80+
. Refer to the sample YAML for a control plane machine set CR and populate your file with values that are appropriate for your cluster configuration.
81+
82+
. Refer to the sample failure domain configuration and sample provider specification for your cloud provider and update those sections of your file with the appropriate values.
83+
84+
. When the configuration is correct, activate the CR by setting the `.spec.state` field to `Active` and saving your changes.
85+
86+
. Create the CR from your YAML file by running the following command:
87+
+
88+
[source,terminal]
89+
----
90+
$ oc create -f <control_plane_machine_set>.yaml
91+
----
92+
+
93+
where `<control_plane_machine_set>` is the name of the YAML file that contains the CR configuration.

0 commit comments

Comments
 (0)