Applied changes from PR#800 ranjinimn suggestions/proposals (first review)

Signed-off-by: Antonio Alonso Alarcon <[email protected]>

Author: antaloala

asciidoc/product/atip-requirements.adoc

@@ -62,22 +62,28 @@ To use the directed network provisioning workflow, the management cluster must h
 
 === Port requirements
 
-To operate properly, a SUSE Telco Cloud deployment requires a number of ports to be reachable on the Management and the Downstream Kubernetes cluster nodes.
+To operate properly, a SUSE Telco Cloud deployment requires a number of ports to be reachable on the management and the downstream Kubernetes cluster nodes.
 
-NOTE: The exact list depends on the deployed optional components and the selected deployment options (e.g., CNI plugin).
+[NOTE]
+====
+The exact list depends on the deployed optional components and the selected deployment options (e.g., CNI plug-in).
+====
 
 ==== Management Nodes
 
-The following table lists the opened ports in nodes running the Management cluster:
+The following table lists the opened ports in nodes running the management cluster:
 
-NOTE: CNI plugin related ports are not included in this list, those being detailed in a following section (see below).
+[NOTE]
+====
+For CNI plug-in related ports, see <<cni-specific-port-requirements,CNI specific port requirements>>.
+====
 
 |===
 | Protocol | Port | Source | Description
 | TCP
 | 22
-| Any source requiring SSH access
-| SSH access to mgmt. cluster nodes
+| Any source that requires SSH access
+| SSH access to management cluster nodes
 
 | TCP
 | 80
@@ -92,35 +98,35 @@ NOTE: CNI plugin related ports are not included in this list, those being detail
 | TCP
 | 2379
 | RKE2 (management cluster) server nodes
-| etcd client port
+| `etcd` client port
 
 | TCP
 | 2380
 | RKE2 (management cluster) server nodes
-| etcd peer port
+| `etcd` peer port
 
 | TCP
 | 6180
 | Any BMC^(1)^ previously instructed by `Metal^3^/ironic` to pull an IPA^(2)^ ramdisk image from this exposed port (non-TLS)
-| `Ironic` httpd non-TLS web server serving IPA^(2)^ iso images for virtual media based boot  +
+| `Ironic` httpd non-TLS web server serving IPA^(2)^ ISO images for virtual media based boot  +
  +
-NOTE: In case this port is enabled, the functionally equivalent but TLS-enabled one (see below) is not opened
+ In case this port is enabled, the functionally equivalent but TLS-enabled one (see below) is not opened
 
 | TCP
 | 6185
 | Any BMC^(1)^ previously instructed by `Metal^3^/ironic` to pull an IPA^(2)^ ramdisk image from this exposed port (TLS)
-| `Ironic` httpd TLS-enabled web server serving IPA^(2)^ iso images for virtual media based boot +
+| `Ironic` httpd TLS-enabled web server serving IPA^(2)^ ISO images for virtual media based boot +
  +
-NOTE: In case this port is enabled, the functionally equivalent but TLS-disabled one (see above) is not opened
+ In case this port is enabled, the functionally equivalent but TLS-disabled one (see above) is not opened
 
 | TCP
 | 6385
 | Any `Metal^3^/ironic` IPA^(1)^ ramdisk image deployed & running in an "enrolled" `BareMetalHost` instance
-|Ironic API
+| Ironic API
 
 | TCP
 | 6443
-| Any management cluster node; any external (to the mgmt. cluster) kubernetes client
+| Any management cluster node; any external (to the management cluster) Kubernetes client
 | Kubernetes API
 
 | TCP
@@ -136,7 +142,7 @@ NOTE: In case this port is enabled, the functionally equivalent but TLS-disabled
 | TCP
 | 10250
 | Any management cluster node
-| kubelet metrics
+| `kubelet` metrics
 
 | TCP/UDP/SCTP
 | 30000-32767
@@ -148,9 +154,13 @@ NOTE: In case this port is enabled, the functionally equivalent but TLS-disabled
 
 ==== Downstream Nodes
 
-In SUSE Telco Cloud, before any (downstream) server becomes part of a running downstream kubernetes cluster (or runs itself a single-node downstream kubernetes cluster), it is required to go through some of the https://github.com/metal3-io/baremetal-operator/blob/main/docs/baremetalhost-states.md[BaremetalHost Provisioning states].
+In SUSE Telco Cloud, before any (downstream) server becomes part of a running downstream Kubernetes cluster (or runs itself a single-node downstream Kubernetes cluster), it is required to go through some of the https://github.com/metal3-io/baremetal-operator/blob/main/docs/baremetalhost-states.md[BaremetalHost Provisioning states].
 
-* First of all, the Baseboard Management Controller (BMC) for a just enrolled downstream server must be accessible through the out-of-band network, for the ironic service running on the mgmt. cluster to instruct it on the initial steps to take: to get and load an IPA ramdisk image in the BMC offered `virtual media` and power-on the server. Following ports are expected to be exposed from the BMC (they could differ depending on the exact hardware):
+* The Baseboard Management Controller (BMC) for a just declared downstream server must be accessible through the out-of-band network. BMC is instructed (from the ironic service running on the management cluster) on the initial steps to take: 
+. Pull and load the indicated IPA ramdisk image in the BMC offered `virtual media`. 
+. Power-on the server.
+
+Following ports are expected to be exposed from the BMC (they could differ depending on the exact hardware):
 
 |===
 | Protocol | Port | Source | Description
@@ -165,13 +175,13 @@ In SUSE Telco Cloud, before any (downstream) server becomes part of a running do
 | Redfish API access (HTTPS)
 |===
 
-* Once an IPA ramdisk image has been loaded on the target downstream server and used as bootup image (using BMC `virtual media` support) the hardware inspection phase is started. Here below are listed the ports being exposed by a running IPA ramdisk image:
+* Once the IPA ramdisk image loaded on the BMC `virtual media` is used to bootup the downstream server image, the hardware inspection phase begins. The following table lists the ports exposed by a running IPA ramdisk image:
 
 |===
 | Protocol | Port | Source | Description
 | TCP
 | 22
-| Any source requrining SSH access to IPA ramdisk image
+| Any source that requires SSH access to IPA ramdisk image
 | SSH access to a being inspected downstream cluster node
 
 | TCP
@@ -180,15 +190,18 @@ In SUSE Telco Cloud, before any (downstream) server becomes part of a running do
 | Ironic commands towards the running ramdisk image
 |===
 
-* Finally, once the baremetal host has been properly provisioned and has joined a downstream kubernetes cluster, it exposes the following ports:
+* Once the baremetal host is properly provisioned and has joined a downstream Kubernetes cluster, it exposes the following ports:
 
-NOTE: CNI plugin related ports are not included in this list, those being detailed in a following section (see below).
+[NOTE]
+====
+For CNI plug-in related ports, see <<cni-specific-port-requirements,CNI specific port requirements>>.
+====
 
 |===
 | Protocol | Port | Source | Description
 | TCP
 | 22
-| Any source requiring SSH access
+| Any source that requires SSH access
 | SSH access to downstream cluster nodes
 
 | TCP
@@ -204,16 +217,16 @@ NOTE: CNI plugin related ports are not included in this list, those being detail
 | TCP
 | 2379
 | RKE2 (downstream cluster) server nodes
-| etcd client port
+| `etcd` client port
 
 | TCP
 | 2380
 | RKE2 (downstream cluster) server nodes
-| etcd peer port
+| `etcd` peer port
 
 | TCP
 | 6443
-| Any downstream cluster node; any external (to the downstream cluster) kubernetes client.
+| Any downstream cluster node; any external (to the downstream cluster) Kubernetes client.
 | Kubernetes API
 
 | TCP
@@ -224,33 +237,33 @@ NOTE: CNI plugin related ports are not included in this list, those being detail
 | TCP
 | 10250
 | Any downstream cluster node
-| kubelet metrics
+| `kubelet` metrics
 
 | TCP
 | 10255
 | Any downstream cluster node
-| kubelet read-only access
+| `kubelet` read-only access
 
 | TCP/UDP/SCTP
 | 30000-32767
 | Any external (to the downstream cluster) source accessing a service exposed on the primary network through a `spec.type: NodePort` or `spec.type: LoadBalancer` https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types[Service API object]
 | Available `NodePort` port range
 |===
 
-
+[#cni-specific-port-requirements]
 ==== CNI specific port requirements
 
-Each supported CNI variant comes with its own set of port requirements; RKE2 documentation details those per each of the supported CNI plugins, see https://docs.rke2.io/install/requirements#cni-specific-inbound-network-rules
+Each supported CNI variant comes with its own set of port requirements. For more details, refer https://docs.rke2.io/install/requirements#cni-specific-inbound-network-rules[CNI Specific Inbound Network Rules] in RKE2 documentation.
 
-In case of setting `cilium` as default/primary CNI plugin, the following port must be added to the list of externally exposed TCP ports (as provided by RKE2 documentation) when the cilium-operator workload is configured to expose metrics outside the kubernetes cluster it is deployed on (so an external Prometheus server instance running outside that kubernetes cluster can still collect them):
+When `cilium` is set as default/primary CNI plug-in, following TCP port is additionally exposed when the cilium-operator workload is configured to expose metrics outside the Kubernetes cluster on which it is deployed. This ensures that an external `Prometheus` server instance running outside that Kubernetes cluster can still collect these metrics.
 
 NOTE: This is the default option when deploying cilium from SUSE rke2-cilium Helm chart (https://rke2-charts.rancher.io/assets/rke2-cilium/rke2-cilium-<major>.<minor>.<patch>.tgz).
 
 |===
 | Protocol | Port | Source | Description
 | TCP
 | 9963
-| External (to the kubernetes cluster) metrics collector
+| External (to the Kubernetes cluster) metrics collector
 | cilium-operator metrics exposure
 |===