Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

OSDOCS#8773: Agent configuration reference assembly #69292

Merged
merged 1 commit into from
Jan 18, 2024
Merged

OSDOCS#8773: Agent configuration reference assembly #69292

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions _topic_maps/_topic_map.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -353,6 +353,8 @@ Topics:
File: prepare-pxe-assets-agent
- Name: Preparing an Agent-based installed cluster for the multicluster engine for Kubernetes
File: preparing-an-agent-based-installed-cluster-for-mce
- Name: Installation configuration parameters for the Agent-based Installer
File: installation-config-parameters-agent
- Name: Installing on a single node
Dir: installing_sno
Distros: openshift-enterprise
Expand Down
19 changes: 19 additions & 0 deletions ...installing_with_agent_based_installer/installation-config-parameters-agent.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
:_mod-docs-content-type: ASSEMBLY
[id="installation-config-parameters-agent"]
= Installation configuration parameters for the Agent-based Installer
include::_attributes/common-attributes.adoc[]
:context: installation-config-parameters-agent

toc::[]

Before you deploy an {product-title} cluster using the Agent-based Installer, you provide parameters to customize your cluster and the platform that hosts it.
When you create the `install-config.yaml` and `agent-config.yaml` files, you must provide values for the required parameters, and you can use the optional parameters to customize your cluster further.

include::modules/installation-configuration-parameters.adoc[leveloffset=+1]

include::modules/agent-configuration-parameters.adoc[leveloffset=+1]

[role="_additional-resources"]
.Additional resources
* xref:../../installing/installing_with_agent_based_installer/prepare-pxe-assets-agent.adoc#prepare-pxe-assets-agent[Preparing PXE assets for {product-title}]
* xref:../../installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc#root-device-hints_ipi-install-installation-workflow[Root device hints]
124 changes: 124 additions & 0 deletions modules/agent-configuration-parameters.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
// Module included in the following assemblies:
//
// * installing/installing_with_agent_based_installer/installation-config-parameters-agent.adoc

:_mod-docs-content-type: CONCEPT
[id="agent-configuration-parameters_{context}"]
= Available Agent configuration parameters
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing blank line after header?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, thank you


The following tables specify the required and optional Agent configuration parameters that you can set as part of the Agent-based installation process.

These values are specified in the `agent-config.yaml` file.

[NOTE]
====
These settings are used for installation only, and cannot be modified after installation.
====

[id="agent-configuration-parameters-required_{context}"]
== Required configuration parameters

Required Agent configuration parameters are described in the following table:

.Required parameters
[cols=".^2l,.^3,.^5a",options="header"]
|====
|Parameter|Description|Values

|apiVersion:
|The API version for the `agent-config.yaml` content.
The current version is `v1beta1`.
The installation program might also support older API versions.
|String

|metadata:
|Kubernetes resource `ObjectMeta`, from which only the `name` parameter is consumed.
|Object

|metadata:
name:
|The name of the cluster.
Comment on lines +34 to +40
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The parameter metadata.name is optional; however, when included in the agent-config file, it takes precedence over the value specified in the install-config file.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If included in the agent-config file, the metadata.name parameter neither takes precedence nor serves as a required or optional setting; rather, it is simply ignored, and the value specified in the install-config file is used.
@bfournie please confirm.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The metadata name and namespace are required. From the agent-config.yaml defintion: https://github.com/openshift/installer/blob/master/pkg/types/agent/agent_config_type.go#L19-L20

However they are not validated or used. As Manoj indicated, the fields are ignored

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll add a sentence to this entry stating "The value entered in the agent-config.yaml file is ignored, and the instead the value specified in the install-config.yaml file is used."

Let me know if that sounds right, or if I need to add to/change that sentence.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That sounds right, although I did discover that if the install-config.yaml is ALSO not supplied that a default cluster name of agent-cluster will be used, see https://github.com/openshift/installer/blob/master/pkg/asset/agent/installconfig.go#L253-L258

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bfournie just out of curiosity, how is this value a required parameter in both the agent-config and install-config files if the installation proceeds without them specified? I'm not familiar with OCP configuration, does "required" not mean "necessary for the installation and thus the installer will terminate with an error without this value"?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bfournie If the value is not specified in the install-config, the following error message will be generated: "FATAL failed to fetch Agent Manifests: failed to load asset "Install Config": invalid install-config configuration: metadata.name: Invalid value: "": a lowercase RFC 1123 subdomain must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character"

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the install-config.yaml, if it's provided the metadata.name must be included. However install-config.yaml is optional for the agent installer (when using just the ZTP manifests). In that case the cluster name will be set to agent-cluster

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Proposed sentence to add to metadata.name descriptions for both agent-config and install-config:

"When you do not provide metadata.name through either the install-config.yaml or agent-config.yaml files, for example when you use only ZTP manifests, the cluster name will be set to agent-cluster."

DNS records for the cluster are all subdomains of `{{.metadata.name}}.{{.baseDomain}}`.
The value entered in the `agent-config.yaml` file is ignored, and instead the value specified in the `install-config.yaml` file is used.
When you do not provide `metadata.name` through either the `install-config.yaml` or `agent-config.yaml` files, for example when you use only ZTP manifests, the cluster name is set to `agent-cluster`.
|String of lowercase letters and hyphens (`-`), such as `dev`.
|====


[id="agent-configuration-parameters-optional_{context}"]
== Optional configuration parameters

Optional Agent configuration parameters are described in the following table:

.Optional parameters
[cols=".^2l,.^4,.^4a",options="header"]
|====
|Parameter|Description|Values

|rendezvousIP:
|The IP address of the node that performs the bootstrapping process as well as running the `assisted-service` component.
You must provide the rendezvous IP address when you do not specify at least one host's IP address in the `networkConfig` parameter.
If this address is not provided, one IP address is selected from the provided hosts' `networkConfig`.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We probably should define here in more details how the the RendezvousIP is selected from the hosts if not provided. TBD.

|IPv4 or IPv6 address.

|bootArtifactsBaseURL:
|The URL of the server to upload Preboot Execution Environment (PXE) assets to when using the Agent-based Installer to generate an iPXE script.
For more information, see "Preparing PXE assets for {product-title}".
|String.

|additionalNTPSources:
|A list of Network Time Protocol (NTP) sources to be added to all cluster hosts, which are added to any NTP sources that are configured through other means.
|List of hostnames or IP addresses.

|hosts:
|Host configuration.
An optional list of hosts.
The number of hosts defined must not exceed the total number of hosts defined in the `install-config.yaml` file, which is the sum of the values of the `compute.replicas` and `controlPlane.replicas` parameters.
skopacz1 marked this conversation as resolved.
Show resolved Hide resolved
|An array of host configuration objects.

|hosts:
skopacz1 marked this conversation as resolved.
Show resolved Hide resolved
hostname:
|Hostname.
Overrides the hostname obtained from either the Dynamic Host Configuration Protocol (DHCP) or a reverse DNS lookup.
Each host must have a unique hostname supplied by one of these methods, although configuring a hostname through this parameter is optional.
|String.

|hosts:
interfaces:
|Provides a table of the name and MAC address mappings for the interfaces on the host.
If a `NetworkConfig` section is provided in the `agent-config.yaml` file, this table must be included and the values must match the mappings provided in the `NetworkConfig` section.
|An array of host configuration objects.

|hosts:
interfaces:
name:
|The name of an interface on the host.
|String.

|hosts:
interfaces:
macAddress:
|The MAC address of an interface on the host.
|A MAC address such as the following example: `00-B0-D0-63-C2-26`

|hosts:
rootDeviceHints:
|Enables provisioning of the {op-system-first} image to a particular device.
The installation program examines the devices in the order it discovers them, and compares the discovered values with the hint values.
It uses the first discovered device that matches the hint value.
This is the device that the operating system is written on during installation.
|A dictionary of key-value pairs.
For more information, see "Root device hints" in the "Setting up the environment for an OpenShift installation" page.

|hosts:
rootDeviceHints:
deviceName:
|The name of the device the {op-system} image is provisioned to.
|String.

|hosts:
networkConfig:
|The host network definition.
The configuration must match the Host Network Management API defined in the link:https://nmstate.io/[nmstate documentation].
|A dictionary of host network configuration objects.
|====
Loading