Skip to content

Commit ddd2c95

Browse files
skopacz1skopacz1
authored
Merge pull request #80845 from skopacz1/OSDOCS-11757
OSDOCS#11757: Adding nodes to on-premise clusters
2 parents 172fbdb + d316aac commit ddd2c95

File tree

6 files changed

+410
-0
lines changed

6 files changed

+410
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2652,6 +2652,8 @@ Topics:
26522652
File: nodes-nodes-working
26532653
- Name: Managing nodes
26542654
File: nodes-nodes-managing
2655+
- Name: Adding worker nodes to an on-premise cluster
2656+
File: nodes-nodes-adding-node-iso
26552657
# Hiding this assembly per @rphillips: "We are trying to enable the feature, but there are cases we are running into where networking does not get enabled at boot."
26562658
# - Name: Managing graceful node shutdown
26572659
# File: nodes-nodes-graceful-shutdown

‎modules/adding-node-iso-configs.adoc

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *nodes/nodes/nodes-nodes-adding-node-iso.adoc
4+
5+
:_mod-docs-content-type: REFERENCE
6+
[id="adding-node-iso-configs_{context}"]
7+
= Cluster configuration reference
8+
9+
When creating the ISO image, configurations are retrieved from the target cluster and are applied to the new nodes.
10+
Any configurations for your cluster are applied to the nodes unless you override the configurations in either the `nodes-config.yaml` file or any flags you add to the `oc adm node-image create` command.
11+
12+
[id="adding-node-iso-yaml-config_{context}"]
13+
== YAML file parameters
14+
15+
Configuration parameters that can be specified in the `nodes-config.yaml` file are described in the following table:
16+
17+
.`nodes-config.yaml` parameters
18+
[cols=".^4l,.^3,.^2",options="header"]
19+
|====
20+
|Parameter|Description|Values
21+
22+
|hosts:
23+
|Host configuration.
24+
|An array of host configuration objects.
25+
26+
|hosts:
27+
hostname:
28+
|Hostname.
29+
Overrides the hostname obtained from either the Dynamic Host Configuration Protocol (DHCP) or a reverse DNS lookup.
30+
Each host must have a unique hostname supplied by one of these methods, although configuring a hostname through this parameter is optional.
31+
|String.
32+
33+
|hosts:
34+
interfaces:
35+
|Provides a table of the name and MAC address mappings for the interfaces on the host.
36+
If a `NetworkConfig` section is provided in the `nodes-config.yaml` file, this table must be included and the values must match the mappings provided in the `NetworkConfig` section.
37+
|An array of host configuration objects.
38+
39+
|hosts:
40+
interfaces:
41+
name:
42+
|The name of an interface on the host.
43+
|String.
44+
45+
|hosts:
46+
interfaces:
47+
macAddress:
48+
|The MAC address of an interface on the host.
49+
|A MAC address such as the following example: `00-B0-D0-63-C2-26`.
50+
51+
|hosts:
52+
rootDeviceHints:
53+
|Enables provisioning of the {op-system-first} image to a particular device.
54+
The node-adding tool examines the devices in the order it discovers them, and compares the discovered values with the hint values.
55+
It uses the first discovered device that matches the hint value.
56+
|A dictionary of key-value pairs.
57+
For more information, see "Root device hints" in the "Setting up the environment for an OpenShift installation" page.
58+
59+
|hosts:
60+
rootDeviceHints:
61+
deviceName:
62+
|The name of the device the {op-system} image is provisioned to.
63+
|String.
64+
65+
|hosts:
66+
networkConfig:
67+
|The host network definition.
68+
The configuration must match the Host Network Management API defined in the link:https://nmstate.io/[nmstate documentation].
69+
|A dictionary of host network configuration objects.
70+
71+
|====
72+
73+
74+
[id="adding-node-iso-flags-config_{context}"]
75+
== Command flag options
76+
77+
You can use command flags with the `oc adm node-image create` command to configure the nodes you are creating.
78+
79+
The following table describes command flags that are not limited to the single-node use case:
80+
81+
.General command flags
82+
[cols=".^4,.^3,.^2",options="header"]
83+
|====
84+
|Flag|Description|Values
85+
86+
|`--certificate-authority`
87+
|The path to a certificate authority bundle to use when communicating with the managed container image registries.
88+
If the `--insecure` flag is used, this flag is ignored.
89+
|String
90+
91+
|`--dir`
92+
|The path containing the configuration file, if provided.
93+
This path is also used to store the generated artifacts.
94+
|String
95+
96+
|`--insecure`
97+
|Allows push and pull operations to registries to be made over HTTP.
98+
|Boolean
99+
100+
|`-o`, `--output-name`
101+
|The name of the generated output image.
102+
|String
103+
104+
|`-a`, `--registry-config`
105+
|The path to your registry credentials.
106+
Alternatively, you can specify the `REGISTRY_AUTH_FILE` environment variable.
107+
The default paths are `${XDG_RUNTIME_DIR}/containers/auth.json`, `/run/containers/${UID}/auth.json`, `${XDG_CONFIG_HOME}/containers/auth.json`, `${DOCKER_CONFIG}`, `~/.docker/config.json`, `~/.dockercfg.`
108+
The order can be changed through the deprecated `REGISTRY_AUTH_PREFERENCE` environment variable to a "docker" value, in order to prioritize Docker credentials over Podman.
109+
|String
110+
111+
|`--skip-verification`
112+
|An option to skip verifying the integrity of the retrieved content.
113+
This is not recommended, but might be necessary when importing images from older image registries.
114+
Bypass verification only if the registry is known to be trustworthy.
115+
|Boolean
116+
117+
|====
118+
119+
The following table describes command flags that can be used only when creating a single node:
120+
121+
.Single-node only command flags
122+
[cols=".^4,.^3,.^2",options="header"]
123+
|====
124+
|Flag|Description|Values
125+
126+
|`-c`, `--cpu-architecture`
127+
|The CPU architecture to be used to install the node.
128+
This flag can be used to create only a single node, and the `--mac-address` flag must be defined.
129+
|String
130+
131+
|`--hostname`
132+
|The hostname to be set for the node.
133+
This flag can be used to create only a single node, and the `--mac-address` flag must be defined.
134+
|String
135+
136+
|`-m`, `--mac-address`
137+
|The MAC address used to identify the host to apply configurations to.
138+
This flag can be used to create only a single node, and the `--mac-address` flag must be defined.
139+
|String
140+
141+
|`--network-config-path`
142+
|The path to a YAML file containing NMState configurations to be applied to the node.
143+
This flag can be used to create only a single node, and the `--mac-address` flag must be defined.
144+
|String
145+
146+
|`--root-device-hint`
147+
|A hint for specifying the storage location for the image root filesystem. The accepted format is `<hint_name>:<value>`.
148+
This flag can be used to create only a single node, and the `--mac-address` flag must be defined.
149+
|String
150+
151+
|`-k`, `--ssh-key-path`
152+
|The path to the SSH key used to access the node.
153+
This flag can be used to create only a single node, and the `--mac-address` flag must be defined.
154+
|String
155+
|====
156+
157+
////
158+
Content to be added here. If the nodes-config.yaml has similar configuration options to the agent-config.yaml, is there a chance that we can duplicate or reuse some of the configuration reference we have for the Agent Installer?
159+
160+
Here's the reference doc for agent-config.yaml: https://docs.openshift.com/container-platform/4.16/installing/installing_with_agent_based_installer/installation-config-parameters-agent.html#agent-configuration-parameters_installation-config-parameters-agent
161+
////

‎modules/adding-node-iso-flags.adoc

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *nodes/nodes/nodes-nodes-adding-node-iso.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="adding-node-iso-flags_{context}"]
7+
= Adding a node with command flags
8+
9+
You can add a single node to your cluster by using command flags to specify configurations for the new node.
10+
11+
.Prerequisites
12+
13+
* You have installed the OpenShift CLI (`oc`)
14+
* You have an active connection to your target cluster
15+
* You have a kubeconfig file available
16+
17+
.Procedure
18+
19+
. Generate the ISO image by running the following command. The MAC address must be specified using a command flag. See the "Cluster configuration reference" section for more flags that you can use with this command.
20+
+
21+
[source,terminal]
22+
----
23+
$ oc adm node-image create --mac-address=<mac_address>
24+
----
25+
+
26+
--
27+
where:
28+
29+
`<mac_address>`:: Specifies the MAC address of the node that is being added.
30+
--
31+
+
32+
[IMPORTANT]
33+
====
34+
In order for the `create` command to fetch a release image that matches the target cluster version, you must specify a valid pull secret.
35+
You can specify the pull secret either by using the `--registry-config` flag or by setting the `REGISTRY_AUTH_FILE` environment variable beforehand.
36+
====
37+
+
38+
[TIP]
39+
====
40+
To see additional flags that can be used to configure your node, run the following `oc adm node-image create --help` command.
41+
====
42+
43+
. Verify that a new `node.<arch>.iso` file is present in the asset directory.
44+
The asset directory is your current directory, unless you specified a different one when creating the ISO image.
45+
46+
. Boot the node with the generated ISO image.
47+
48+
. Track progress of the node creation by running the following command:
49+
+
50+
[source,terminal]
51+
----
52+
$ oc adm node-image monitor <ip_address>
53+
----
54+
+
55+
--
56+
where:
57+
58+
`<ip_address>`:: Specifies a list of the IP addresses of the nodes that are being added.
59+
--
60+
+
61+
[NOTE]
62+
====
63+
If reverse DNS entries are not available for your node, the `oc adm node-image monitor` command skips checks for pending certificate signing requests (CSRs).
64+
If these checks are skipped, you must manually check for CSRs by running the `oc get csr` command.
65+
====
66+
67+
. Approve the pending CSRs by running the following command for each CSR:
68+
+
69+
[source,terminal]
70+
----
71+
$ oc adm certificate approve <csr_name>
72+
----

‎modules/adding-node-iso-yaml.adoc

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
// Module included in the following assemblies:
2+
//
3+
// *nodes/nodes/nodes-nodes-adding-node-iso.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="adding-node-iso-yaml_{context}"]
7+
= Adding one or more nodes using a configuration file
8+
9+
You can add one or more nodes to your cluster by using the `nodes-config.yaml` file to specify configurations for the new nodes.
10+
11+
.Prerequisites
12+
13+
* You have installed the OpenShift CLI (`oc`)
14+
* You have an active connection to your target cluster
15+
* You have a kubeconfig file available
16+
17+
.Procedure
18+
19+
. Create a new YAML file that contains configurations for the nodes you are adding and is named `nodes-config.yaml`. You must provide a MAC address for each new node.
20+
+
21+
In the following example file, two new workers are described with an initial static network configuration:
22+
+
23+
.Example `nodes-config.yaml` file
24+
[source,yaml]
25+
----
26+
hosts:
27+
- hostname: extra-worker-1
28+
rootDeviceHints:
29+
deviceName: /dev/sda
30+
interfaces:
31+
- macAddress: 00:00:00:00:00:00
32+
name: eth0
33+
networkConfig:
34+
interfaces:
35+
- name: eth0
36+
type: ethernet
37+
state: up
38+
mac-address: 00:00:00:00:00:00
39+
ipv4:
40+
enabled: true
41+
address:
42+
- ip: 192.168.122.2
43+
prefix-length: 23
44+
dhcp: false
45+
- hostname: extra-worker-2
46+
rootDeviceHints:
47+
deviceName: /dev/sda
48+
interfaces:
49+
- macAddress: 00:00:00:00:00:02
50+
name: eth0
51+
networkConfig:
52+
interfaces:
53+
- name: eth0
54+
type: ethernet
55+
state: up
56+
mac-address: 00:00:00:00:00:02
57+
ipv4:
58+
enabled: true
59+
address:
60+
- ip: 192.168.122.3
61+
prefix-length: 23
62+
dhcp: false
63+
----
64+
65+
. Generate the ISO image by running the following command:
66+
+
67+
[source,terminal]
68+
----
69+
$ oc adm node-image create nodes-config.yaml
70+
----
71+
+
72+
[IMPORTANT]
73+
====
74+
In order for the `create` command to fetch a release image that matches the target cluster version, you must specify a valid pull secret.
75+
You can specify the pull secret either by using the `--registry-config` flag or by setting the `REGISTRY_AUTH_FILE` environment variable beforehand.
76+
====
77+
+
78+
[NOTE]
79+
====
80+
If the directory of the `nodes-config.yaml` file is not specified by using the `--dir` flag, the tool looks for the file in the current directory.
81+
====
82+
83+
. Verify that a new `node.<arch>.iso` file is present in the asset directory.
84+
The asset directory is your current directory, unless you specified a different one when creating the ISO image.
85+
86+
. Boot the selected node with the generated ISO image.
87+
88+
. Track progress of the node creation by running the following command:
89+
+
90+
[source,terminal]
91+
----
92+
$ oc adm node-image monitor <ip_addresses>
93+
----
94+
+
95+
where:
96+
97+
`<ip_addresses>`:: Specifies a list of the IP addresses of the nodes that are being added.
98+
+
99+
[NOTE]
100+
====
101+
If reverse DNS entries are not available for your node, the `oc adm node-image monitor` command skips checks for pending certificate signing requests (CSRs).
102+
If these checks are skipped, you must manually check for CSRs by running the `oc get csr` command.
103+
====
104+
105+
. Approve the CSRs by running the following command for each CSR:
106+
+
107+
[source,terminal]
108+
----
109+
$ oc adm certificate approve <csr_name>
110+
----

0 commit comments

Comments
 (0)