Skip to content

Commit 4d6771f

Browse files
jeana-redhatjeana-redhat
authored
Merge pull request #48121 from jeana-redhat/OSDOCS-3645-aws-gcp-capi-tp
[OSDOCS-3645]: AWS and GCP CAPI TP
2 parents 9255490 + 49ccbf9 commit 4d6771f

15 files changed

+675
-4
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1901,6 +1901,8 @@ Topics:
19011901
File: adding-vsphere-compute-user-infra
19021902
- Name: Adding compute machines to bare metal
19031903
File: adding-bare-metal-compute-user-infra
1904+
- Name: Managing machines with the Cluster API
1905+
File: capi-machine-management
19041906
- Name: Deploying machine health checks
19051907
File: deploying-machine-health-checks
19061908
---

‎machine_management/capi-machine-management.adoc

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
:_content-type: ASSEMBLY
2+
[id="capi-machine-management"]
3+
= Managing machines with the Cluster API
4+
include::_attributes/common-attributes.adoc[]
5+
:context: capi-machine-management
6+
7+
toc::[]
8+
9+
:FeatureName: Managing machines with the Cluster API
10+
include::snippets/technology-preview.adoc[]
11+
12+
The link:https://cluster-api.sigs.k8s.io/[Cluster API] is an upstream project that is integrated into {product-title} as a Technology Preview for Amazon Web Services (AWS) and Google Cloud Platform (GCP) clusters. You can use the Cluster API to create and manage machine sets and machines in your {product-title} cluster. This capability is in addition or an alternative to managing machines with the Machine API.
13+
14+
For {product-title} {product-version} clusters, you can use the Cluster API to perform node host provisioning management actions after the cluster installation finishes. This system enables an elastic, dynamic provisioning method on top of public or private cloud infrastructure.
15+
16+
With the Cluster API Technology Preview, you can create compute machines and machine sets on {product-title} clusters for supported providers. You can also explore the features that are enabled by this implementation that might not be available with the Machine API.
17+
18+
[discrete]
19+
[id="cluster-api-benefits_{context}"]
20+
== Benefits
21+
22+
By using the Cluster API, {product-title} users and developers are able to realize the following advantages:
23+
24+
* The option to use upstream community Cluster API infrastructure providers which might not be supported by the Machine API.
25+
26+
* The opportunity to collaborate with third parties who maintain machine controllers for infrastructure providers.
27+
28+
* The ability to use the same set of Kubernetes tools for infrastructure management in {product-title}.
29+
30+
* The ability to create machine sets using the Cluster API that support features that are not available with the Machine API.
31+
32+
[discrete]
33+
[id="capi-tech-preview-limitations"]
34+
== Limitations
35+
36+
Using the Cluster API to manage machines is a Technology Preview feature and has the following limitations:
37+
38+
* Only AWS and GCP clusters are supported.
39+
40+
* To use this feature, you must enable the `ClusterAPIEnabled` xref:../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling-features-about_nodes-cluster-enabling[feature gate] in the `TechPreviewNoUpgrade` feature set. Enabling this feature set cannot be undone and prevents minor version updates.
41+
42+
* You must create the primary resources that the Cluster API requires manually.
43+
44+
* Control plane machines cannot be managed by the Cluster API.
45+
46+
* Migration of existing machine sets created by the Machine API to Cluster API machine sets is not supported.
47+
48+
* Full feature parity with the Machine API is not available.
49+
50+
//Cluster API architecture
51+
include::modules/cluster-api-architecture.adoc[leveloffset=+1]
52+
53+
[role="_additional-resources"]
54+
.Additional resources
55+
* xref:../operators/operator-reference.adoc#cluster-capi-operator_platform-operators-ref[Cluster CAPI Operator]
56+
57+
[id="capi-sample-yaml-files"]
58+
== Sample YAML files
59+
60+
For the Cluster API Technology Preview, you must create the primary resources that the Cluster API requires manually. The example YAML files in this section demonstrate how to make these resources work together and configure settings for the machines that they create that are appropriate for your environment.
61+
62+
//Sample YAML for a CAPI cluster resource
63+
include::modules/capi-yaml-cluster.adoc[leveloffset=+2]
64+
65+
The remaining Cluster API resources are provider-specific. Refer to the example YAML files for your cluster:
66+
67+
* xref:../machine_management/capi-machine-management.adoc#capi-sample-yaml-files-aws[Sample YAML files for configuring Amazon Web Services clusters]
68+
69+
* xref:../machine_management/capi-machine-management.adoc#capi-sample-yaml-files-gcp[Sample YAML files for configuring Google Cloud Platform clusters]
70+
71+
[id="capi-sample-yaml-files-aws"]
72+
=== Sample YAML files for configuring Amazon Web Services clusters
73+
74+
Some Cluster API resources are provider-specific. The example YAML files in this section show configurations for an Amazon Web Services (AWS) cluster.
75+
76+
//Sample YAML for a CAPI AWS provider resource
77+
include::modules/capi-yaml-infrastructure-aws.adoc[leveloffset=+4]
78+
79+
//Sample YAML for CAPI AWS machine template resource
80+
include::modules/capi-yaml-machine-template-aws.adoc[leveloffset=+4]
81+
82+
//Sample YAML for a CAPI AWS machine set resource
83+
include::modules/capi-yaml-machine-set-aws.adoc[leveloffset=+4]
84+
85+
[id="capi-sample-yaml-files-gcp"]
86+
=== Sample YAML files for configuring Google Cloud Platform clusters
87+
88+
Some Cluster API resources are provider-specific. The example YAML files in this section show configurations for a Google Cloud Platform (GCP) cluster.
89+
90+
//Sample YAML for a CAPI GCP provider resource
91+
include::modules/capi-yaml-infrastructure-gcp.adoc[leveloffset=+4]
92+
93+
//Sample YAML for CAPI GCP machine template resource
94+
include::modules/capi-yaml-machine-template-gcp.adoc[leveloffset=+4]
95+
96+
//Sample YAML for a CAPI GCP machine set resource
97+
include::modules/capi-yaml-machine-set-gcp.adoc[leveloffset=+4]
98+
99+
//Creating a CAPI machine set
100+
include::modules/capi-machine-set-creating.adoc[leveloffset=+1]
101+
102+
//Troubleshooting clusters that use the Cluster API
103+
include::modules/capi-troubleshooting.adoc[leveloffset=+1]

‎modules/capi-machine-set-creating.adoc

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * machine_management/capi-machine-management.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="capi-machine-set-creating_{context}"]
7+
= Creating a Cluster API machine set
8+
9+
You can create machine sets that use the Cluster API to dynamically manage the machine compute resources for specific workloads of your choice.
10+
11+
.Prerequisites
12+
13+
* Deploy an {product-title} cluster.
14+
* Enable the use of the Cluster API.
15+
* Install the OpenShift CLI (`oc`).
16+
* Log in to `oc` as a user with `cluster-admin` permission.
17+
18+
.Procedure
19+
20+
. Create a YAML file that contains the cluster custom resource (CR) and is named `<cluster_resource_file>.yaml`.
21+
+
22+
If you are not sure which value to set for the `<cluster_name>` parameter, you can check the value for an existing Machine API machine set in your cluster.
23+
24+
.. To list the Machine API machine sets, run the following command:
25+
+
26+
[source,terminal]
27+
----
28+
$ oc get machinesets -n openshift-machine-api <1>
29+
----
30+
<1> Specify the `openshift-machine-api` namespace.
31+
+
32+
.Example output
33+
[source,terminal]
34+
----
35+
NAME DESIRED CURRENT READY AVAILABLE AGE
36+
agl030519-vplxk-worker-us-east-1a 1 1 1 1 55m
37+
agl030519-vplxk-worker-us-east-1b 1 1 1 1 55m
38+
agl030519-vplxk-worker-us-east-1c 1 1 1 1 55m
39+
agl030519-vplxk-worker-us-east-1d 0 0 55m
40+
agl030519-vplxk-worker-us-east-1e 0 0 55m
41+
agl030519-vplxk-worker-us-east-1f 0 0 55m
42+
----
43+
44+
.. To display the contents of a specific machine set CR, run the following command:
45+
+
46+
[source,terminal]
47+
----
48+
$ oc get machineset <machineset_name> \
49+
-n openshift-machine-api \
50+
-o yaml
51+
----
52+
+
53+
.Example output
54+
[source,yaml]
55+
----
56+
...
57+
template:
58+
metadata:
59+
labels:
60+
machine.openshift.io/cluster-api-cluster: agl030519-vplxk <1>
61+
machine.openshift.io/cluster-api-machine-role: worker
62+
machine.openshift.io/cluster-api-machine-type: worker
63+
machine.openshift.io/cluster-api-machineset: agl030519-vplxk-worker-us-east-1a
64+
...
65+
----
66+
<1> The cluster ID, which you use for the `<cluster_name>` parameter.
67+
68+
. Create the cluster CR by running the following command:
69+
+
70+
[source,terminal]
71+
----
72+
$ oc create -f <cluster_resource_file>.yaml
73+
----
74+
+
75+
.Verification
76+
+
77+
To confirm that the cluster CR is created, run the following command:
78+
+
79+
[source,terminal]
80+
----
81+
$ oc get cluster
82+
----
83+
+
84+
.Example output
85+
[source,terminal]
86+
----
87+
NAME PHASE AGE VERSION
88+
<cluster_name> Provisioning 4h6m
89+
----
90+
91+
. Create a YAML file that contains the infrastructure CR and is named `<infrastructure_resource_file>.yaml`.
92+
93+
. Create the infrastructure CR by running the following command:
94+
+
95+
[source,terminal]
96+
----
97+
$ oc create -f <infrastructure_resource_file>.yaml
98+
----
99+
+
100+
.Verification
101+
+
102+
To confirm that the infrastructure CR is created, run the following command:
103+
+
104+
[source,terminal]
105+
----
106+
$ oc get <infrastructure_kind>
107+
----
108+
+
109+
where `<infrastructure_kind>` is the value that corresponds to your platform.
110+
+
111+
.Example output
112+
[source,terminal]
113+
----
114+
NAME CLUSTER READY VPC BASTION IP
115+
<cluster_name> <cluster_name> true
116+
----
117+
118+
. Create a YAML file that contains the machine template CR and is named `<machine_template_resource_file>.yaml`.
119+
120+
. Create the machine template CR by running the following command:
121+
+
122+
[source,terminal]
123+
----
124+
$ oc create -f <machine_template_resource_file>.yaml
125+
----
126+
+
127+
.Verification
128+
+
129+
To confirm that the machine template CR is created, run the following command:
130+
+
131+
[source,terminal]
132+
----
133+
$ oc get <machine_template_kind>
134+
----
135+
+
136+
where `<machine_template_kind>` is the value that corresponds to your platform.
137+
+
138+
.Example output
139+
[source,terminal]
140+
----
141+
NAME AGE
142+
<template_name> 77m
143+
----
144+
145+
. Create a YAML file that contains the machine set CR and is named `<machine_set_resource_file>.yaml`.
146+
147+
. Create the machine set CR by running the following command:
148+
+
149+
[source,terminal]
150+
----
151+
$ oc create -f <machine_set_resource_file>.yaml
152+
----
153+
+
154+
.Verification
155+
+
156+
To confirm that the machine set CR is created, run the following command:
157+
+
158+
[source,terminal]
159+
----
160+
$ oc get machineset -n openshift-cluster-api <1>
161+
----
162+
<1> Specify the `openshift-cluster-api` namespace.
163+
+
164+
.Example output
165+
[source,terminal]
166+
----
167+
NAME CLUSTER REPLICAS READY AVAILABLE AGE VERSION
168+
<machine_set_name> <cluster_name> 1 1 1 17m
169+
----
170+
+
171+
When the new machine set is available, the `REPLICAS` and `AVAILABLE` values match. If the machine set is not available, wait a few minutes and run the command again.
172+
173+
.Verification
174+
175+
* To verify that the machine set is creating machines according to your desired configuration, you can review the lists of machines and nodes in the cluster.
176+
177+
** To view the list of Cluster API machines, run the following command:
178+
+
179+
[source,terminal]
180+
----
181+
$ oc get machine -n openshift-cluster-api <1>
182+
----
183+
<1> Specify the `openshift-cluster-api` namespace.
184+
+
185+
.Example output
186+
[source,terminal]
187+
----
188+
NAME CLUSTER NODENAME PROVIDERID PHASE AGE VERSION
189+
<machine_set_name>-<string_id> <cluster_name> <ip_address>.<region>.compute.internal <provider_id> Running 8m23s
190+
----
191+
192+
** To view the list of nodes, run the following command:
193+
+
194+
[source,terminal]
195+
----
196+
$ oc get node
197+
----
198+
+
199+
.Example output
200+
[source,terminal]
201+
----
202+
NAME STATUS ROLES AGE VERSION
203+
<ip_address_1>.<region>.compute.internal Ready worker 5h14m v1.24.0+284d62a
204+
<ip_address_2>.<region>.compute.internal Ready master 5h19m v1.24.0+284d62a
205+
<ip_address_3>.<region>.compute.internal Ready worker 7m v1.24.0+284d62a
206+
----

‎modules/capi-troubleshooting.adoc

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * machine_management/capi-machine-management.adoc
4+
5+
:_content-type: REFERENCE
6+
[id="capi-troubleshooting_{context}"]
7+
= Troubleshooting clusters that use the Cluster API
8+
9+
Use the information in this section to understand and recover from issues you might encounter. Generally, troubleshooting steps for problems with the Cluster API are similar to those steps for problems with the Machine API.
10+
11+
The Cluster CAPI Operator and its operands are provisioned in the `openshift-cluster-api` namespace, whereas the Machine API uses the `openshift-machine-api` namespace. When using `oc` commands that reference a namespace, be sure to reference the correct one.
12+
13+
[id="ts-capi-cli_{context}"]
14+
== CLI commands return Cluster API machines
15+
16+
For clusters that use the Cluster API, `oc` commands such as `oc get machine` return results for Cluster API machines. Because the letter `c` precedes the letter `m` alphabetically, Cluster API machines appear in the return before Machine API machines do.
17+
18+
* To list only Machine API machines, use the fully qualified name `machines.machine.openshift.io` when running the `oc get machine` command:
19+
+
20+
[source,terminal]
21+
----
22+
$ oc get machines.machine.openshift.io
23+
----
24+
25+
* To list only Cluster API machines, use the fully qualified name `machines.cluster.x-k8s.io` when running the `oc get machine` command:
26+
+
27+
[source,terminal]
28+
----
29+
$ oc get machines.cluster.x-k8s.io
30+
----

‎modules/capi-yaml-cluster.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+
// * machine_management/capi-machine-management.adoc
4+
5+
:_content-type: REFERENCE
6+
[id="capi-yaml-cluster_{context}"]
7+
= Sample YAML for a Cluster API cluster resource
8+
9+
The cluster resource defines the name and infrastructure provider for the cluster and is managed by the Cluster API. This resource has the same structure for all providers.
10+
11+
[source,yaml]
12+
----
13+
apiVersion: cluster.x-k8s.io/v1beta1
14+
kind: Cluster
15+
metadata:
16+
name: <cluster_name> <1>
17+
namespace: openshift-cluster-api
18+
spec:
19+
infrastructureRef:
20+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
21+
kind: <infrastructure_kind> <2>
22+
name: <cluster_name> <1>
23+
namespace: openshift-cluster-api
24+
----
25+
<1> Specify the name of the cluster.
26+
<2> Specify the infrastructure kind for the cluster. Valid values are:
27+
+
28+
--
29+
* `AWSCluster`: The cluster is running on Amazon Web Services (AWS).
30+
* `GCPCluster`: The cluster is running on Google Cloud Platform (GCP).
31+
--

0 commit comments

Comments
 (0)