OSDOCS#8773: Agent configuration reference assembly #69292
Conversation
openshift-ci-robot
added
the
jira/valid-reference
|
@skopacz1: This pull request references OSDOCS-8773 which is a valid jira issue. Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "4.16.0" version, but no target version was set. In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
openshift-ci
bot
added
the
size/L
|
🤖 Thu Jan 18 16:44:11 - Prow CI generated the docs preview: https://69292--ocpdocs-pr.netlify.app |
skopacz1
force-pushed
the
OSDOCS-8773
branch
from
3d0b5cf
to
44931e5
Compare
skopacz1
changed the title
openshift-ci-robot
removed
the
jira/valid-reference
|
@skopacz1: No Jira issue is referenced in the title of this pull request. In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
skopacz1
force-pushed
the
OSDOCS-8773
branch
from
44931e5
to
f2076d9
Compare
| 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 provide values for the required parameters through the command line. You can then modify the `install-config.yaml` and `agent-config.yaml` files to customize your cluster further. |
There was a problem hiding this comment.
Note sure what is meant by "through the command line" here as this is a referring to the yaml file only. There isn't a command to create an agent-config file
There was a problem hiding this comment.
I'm not sure either, I took this wording from similar reference pages in other installer sections and modified it to include agent-config. Would this phrasing seem better to you?
| When you create the `install-config.yaml` and `agent-config.yaml` files, you provide values for the required parameters through the command line. You can then modify the `install-config.yaml` and `agent-config.yaml` files to customize your cluster further. | |
| 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. |
|
|
||
| [NOTE] | ||
| ==== | ||
| After installation, you cannot modify these parameters in the `agent-config.yaml` file. |
There was a problem hiding this comment.
Maybe say that these settings are used for installation only and therefore can't be modified after install.
|
|
||
| |kind: | ||
| |(needs info) | ||
| |(needs info) |
There was a problem hiding this comment.
As this is optional and not needed for the agent-config.yaml it can be removed.
Note that this is the definition of Kind, this resource isn't retrieved in an API
// Kind is a string value representing the REST resource this object represents.
// Servers may infer this from the endpoint the client submits requests to.
There was a problem hiding this comment.
Sounds good, I can delete this parameter
| |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`. |
There was a problem hiding this comment.
We probably should define here in more details how the the RendezvousIP is selected from the hosts if not provided. TBD.
|
|
||
| |additionalNTPSources: | ||
| |(needs info) | ||
| |(needs info) |
There was a problem hiding this comment.
AdditionalNTPSources is a list of NTP sources (hostname or IP) to be added
to all cluster hosts. They are added to any NTP sources that were configured through other means. This is an optional setting.
| |Host name. | ||
| 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. | ||
| |(needs info) |
There was a problem hiding this comment.
This seems reasonable, could also note that the hostname supplied here is optional.
| |hosts: | ||
| interfaces: | ||
| |(needs info) | ||
| |(needs info) |
There was a problem hiding this comment.
The interface table provides a name and mac address mapping for the interfaces on the host. The settings must match the configuration in the NetworkConfig section. This table is optional, but if the NetworkConfig section is included it must also e provided.
| |Enables provisioning of the {op-system-first} image to a particular device. | ||
| It 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. | ||
| |(needs info) |
There was a problem hiding this comment.
Maybe in addition state that this is the device that the OS will be written during installation.
| |(needs info) | ||
|
|
||
| |hosts: | ||
| networkConfig: |
There was a problem hiding this comment.
The networkConfig field is the host network definition. It must match the Network Management API defined in https://nmstate.io/.
| networkConfig: | ||
| |(needs info) | ||
| |(needs info) | ||
|
|
There was a problem hiding this comment.
I think all of the fields below can be removed. The NetworkConfig must match the fields in https://nmstate.io/, its not necessary to redefine them here.
There was a problem hiding this comment.
Sounds good, I'll delete these remaining NetworkConfig parameters
| It 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 will be written on during installation. | ||
| |(needs accepted/valid values) |
There was a problem hiding this comment.
I don't think need to list accepted/valid values here, it should just refer to other section in the docs that describes rootDeviceHints e.g. https://docs.openshift.com/container-platform/4.13/installing/installing_bare_metal_ipi/ipi-install-installation-workflow.html#root-device-hints_ipi-install-installation-workflow
There was a problem hiding this comment.
I still think there might be a need to define the type of data that should be used with this parameter (and all others, even if we don't want to specify which specific values are accepted). Would this be an accurate entry to include here?
A dictionary of key-value pairs. For more information, see Root device hints.
With a link to the section you provide in your comment
| interfaces: | ||
| name: | ||
| |The name of an interface on the host. | ||
| |(needs accepted/valid values) |
There was a problem hiding this comment.
Interface names aren't really checked for validity so don't need to list valid values here.
There was a problem hiding this comment.
If a string of characters is accepted in general, I can just put "String" here. Let me know if that's not accurate.
|
@bfournie and other Agent devs, I think I have enough information to move this PR on to QE review, thanks for all the help! If you'd like to make more comments/feedback while I'm waiting on or implementing QE review, feel free to keep on doing so. |
|
@mhanss could you PTAL when you have a chance! Thank you! |
| |metadata: | ||
| |Kubernetes resource `ObjectMeta`, from which only the `name` parameter is consumed. | ||
| |Object | ||
|
|
||
| |metadata: | ||
| name: | ||
| |The name of the cluster. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
There was a problem hiding this comment.
@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"?
There was a problem hiding this comment.
@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"
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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."
|
@skopacz1 I would suggest omitting unsupported platforms from the install-config in case of agent-based installation. |
|
@mhanss thanks for the feedback, let me know if I'm missing anything or need to further refine this PR. |
| |`alibabacloud`, `aws`, `azure`, `gcp`, `ibmcloud`, `nutanix`, `openstack`, `powervs`, `vsphere`, or `{}` | ||
| endif::agent[] | ||
| ifdef::agent[] | ||
| |`vsphere` |
There was a problem hiding this comment.
@mhanss do I need to add {} and/or external to this parameter?
There was a problem hiding this comment.
I suggest adding the {} as it involves user-provided infrastructure that doesn't require machine configuration through install-config.yaml.
platform: {} or
platform:
baremetal: {}
platform:
vsphere: {}
platform:
external: {}
@bfournie @pawanpinjarkar What are your thoughts on this?
There was a problem hiding this comment.
Until/unless anyone says otherwise, I'll add {} as a valid value for this parameter and for controlPlane.platform, and I can modify as needed.
There was a problem hiding this comment.
@skopacz1 You can set controlPlane.Platform and compute.Platform to {} for agent installer like below:
"controlPlane": {
"name": "master",
"replicas": 1,
"platform": {},
"hyperthreading": "Enabled",
"architecture": "amd64"
},
"compute": [
{
"name": "worker",
"replicas": 0,
"platform": {},
"hyperthreading": "Enabled",
"architecture": "amd64"
}
],
I don't think you need to specify other possible platform values in there. The possible values could be ( no external here),
"controlPlane": {
"name": "master",
"replicas": 1,
"platform": {
"aws": {
"zones": ["us-east", "us-west"],
"type": "test"
}
},
"hyperthreading": "Enabled",
"architecture": "amd64"
},
Here is the schema definition for platform section for controlPlane and compute https://github.com/openshift/installer/blob/master/pkg/types/machinepools.go#L64
Each of the underlying platform schema definition is here https://github.com/openshift/installer/blob/master/pkg/types/machinepools.go#L84 and any specific ones are here https://github.com/openshift/installer/blob/master/pkg/types/aws/machinepool.go#L5
Long story short, for agent installer, you can just set controlPlane.Platform and compute.Platform to {}
There was a problem hiding this comment.
Thanks for the detailed response, Pawan!
| |`alibabacloud`, `aws`, `azure`, `gcp`, `ibmcloud`, `nutanix`, `openstack`, `powervs`, `vsphere`, or `{}` | ||
| endif::agent[] | ||
| ifdef::agent[] | ||
| |`vsphere` |
There was a problem hiding this comment.
@mhanss do I need to add {} and/or external to this parameter?
There was a problem hiding this comment.
Until/unless anyone says otherwise, I'll add {} as a valid value for this parameter and for compute.platform, and I can modify as needed.
| 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`. | ||
| |IPv4 or IPv6 address. | ||
| IPv6 is supported only on bare metal platforms. |
There was a problem hiding this comment.
It is also supported on vSphere platforms.
There was a problem hiding this comment.
Based on our previous conversation I'll remove this line entirely.
There was a problem hiding this comment.
We need to update the network configuration and some other values in the install-config. You can refer to this documentation for guidance on network configuration. https://docs.openshift.com/container-platform/4.14/installing/installing_bare_metal/installation-config-parameters-bare-metal.html#installation-configuration-parameters-network_installation-config-parameters-bare-metal.
- The architecture values for Compute and controlPlane should be either amd64 or arm64.
- In the case of SNO, the controlPlane replicas value can be set to 1.
- IPv6 is supported for both bare-metal and vSphere platforms. Therefore, the statement indicating that IPv6 is only supported for bare-metal can be removed.
There was a problem hiding this comment.
I've taken the following actions in response to this comment:
- Made the network config section in Agent look the same as the network config in the bare metal page you linked to, which includes the content that mentions both IPv4 and IPv6.
- Modified the
compute.architectureandcontrolPlane.architectureparameters to include both of those architectures in the Agent doc. - Modified
controlPlane.replicasto say that1is a valid value for SNO. This change will appear in all the install sections that have this reference info, not just Agent. - Removed content in the Agent page that states either "only IPv4 is supported" or "IPv6 is supported only for bare metal", these changes are applied to both the
install-configandagent-configsections.
| |`alibabacloud`, `aws`, `azure`, `gcp`, `ibmcloud`, `nutanix`, `openstack`, `powervs`, `vsphere`, or `{}` | ||
| endif::agent[] | ||
| ifdef::agent[] | ||
| |`vsphere` or `{}` |
There was a problem hiding this comment.
Include 'baremetal', 'vsphere', as well as {} as supported values, or simply use {} alone.
| |`alibabacloud`, `aws`, `azure`, `gcp`, `ibmcloud`, `nutanix`, `openstack`, `powervs`, `vsphere`, or `{}` | ||
| endif::agent[] | ||
| ifdef::agent[] | ||
| |`vsphere` or `{}` |
There was a problem hiding this comment.
Include 'baremetal', 'vsphere', as well as {} as supported values, or simply use {} alone.
|
thanks @skopacz1, LGTM. |
|
/label peer-review-needed |
openshift-ci
bot
added
the
peer-review-needed
kcarmichael08
added
peer-review-in-progress
| |apiVersion: | ||
| |The API version for the `agent-config.yaml` content. | ||
| The current version is `v1beta1`. | ||
| The installation program may also support older API versions. |
There was a problem hiding this comment.
| The installation program may also support older API versions. | |
| The installation program might also support older API versions. |
See IBM Style
| [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]. |
There was a problem hiding this comment.
| * xref:../../installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc#root-device-hints_ipi-install-installation-workflow[Root device hints]. | |
| * xref:../../installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc#root-device-hints_ipi-install-installation-workflow[Root device hints] |
There was a problem hiding this comment.
This is a duplicate of the comment below, so I'm assuming this is meant for the first list item in this Additional Resources list. I'll remove periods from both items.
| [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]. |
There was a problem hiding this comment.
| * xref:../../installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc#root-device-hints_ipi-install-installation-workflow[Root device hints]. | |
| * xref:../../installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc#root-device-hints_ipi-install-installation-workflow[Root device hints] |
|
|
||
| :_mod-docs-content-type: CONCEPT | ||
| [id="agent-configuration-parameters_{context}"] | ||
| = Available Agent configuration parameters |
There was a problem hiding this comment.
missing blank line after header?
There was a problem hiding this comment.
Good catch, thank you
| name: | ||
| |The name of the 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 the instead the value specified in the `install-config.yaml` file is used. |
There was a problem hiding this comment.
| 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. | |
| The value entered in the `agent-config.yaml` file is ignored, and instead the value specified in the `install-config.yaml` file is used. |
| |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`, this table must be included and the values must match the mappings provided in the `NetworkConfig` section. |
There was a problem hiding this comment.
| If a `NetworkConfig` section is provided in the `agent-config.yaml`, this table must be included and the values must match the mappings provided in the `NetworkConfig` section. | |
| 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. |
| |hosts: | ||
| rootDeviceHints: | ||
| |Enables provisioning of the {op-system-first} image to a particular device. | ||
| It examines the devices in the order it discovers them, and compares the discovered values with the hint values. |
There was a problem hiding this comment.
It = The installation program ?
There was a problem hiding this comment.
I believe so, good catch! Thanks
| ifdef::agent[] | ||
| |compute: | ||
| architecture: | ||
| |Determines the instruction set architecture of the machines in the pool. Currently, clusters with varied architectures are not supported. All pools must specify the same architecture. Valid values are `amd64` and `arm64`. |
There was a problem hiding this comment.
Would the "valid values" part go in the values column?
There was a problem hiding this comment.
Based on the way this attribute is written for other install pages (see lines 458-487) I guess not. I'd prefer to follow the existing format unless you'd prefer me to put these values in the other column.
| ifdef::agent[] | ||
| |controlPlane: | ||
| architecture: | ||
| |Determines the instruction set architecture of the machines in the pool. Currently, clusters with varied architectures are not supported. All pools must specify the same architecture. Valid values are `amd64` and `arm64`. |
There was a problem hiding this comment.
see previous "values" comment
There was a problem hiding this comment.
Based on the way this attribute is written for other install pages (see lines 551-580) I guess not. I'd prefer to follow the existing format unless you'd prefer me to put these values in the other column.
| @@ -173,7 +173,7 @@ EOF | |||
| 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`. | |||
| <2> Optional: Host configuration. 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. | |||
| <3> Optional: 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. | |||
| <4> Enables provisioning of the Red Hat Enterprise Linux CoreOS (RHCOS) image to a particular device. It 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. | |||
| <4> Enables provisioning of the {op-system-first} image to a particular device. It 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. | |||
There was a problem hiding this comment.
It = installation program?
kcarmichael08
added
peer-review-done
|
Reviewed the conditionals in the install config parameters module and they LGTM. |
|
@skopacz1: all tests passed! Full PR test history. Your PR dashboard. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here. |
|
/label merge-review-needed |
openshift-ci
bot
added
the
merge-review-needed
|
/remove-label merge-review-needed |
openshift-ci
bot
removed
the
merge-review-needed
|
/cherrypick enterprise-4.14 |
|
/cherrypick enterprise-4.15 |
|
@ShaunaDiaz: new pull request created: #70531 In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
|
@ShaunaDiaz: new pull request created: #70532 In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
OSDOCS-8773
Version(s):
4.14+
(content should be backported in later doc effort, I believe the main difference would be which platforms are supported)
This PR adds a new assembly containing all the available configuration parameters for the
install-config.yamlandagent-config.yamlfiles used during an Agent-based installation.QE review:
Preview: Installation configuration parameters for the Agent-based Installer