[enterprise-4.18] OSDOCS-8646: Rewriting introduction to networking (ContentX)

_topic_maps/_topic_map.yml

@@ -1332,8 +1332,6 @@ Name: Networking
 Dir: networking
 Distros: openshift-enterprise,openshift-origin
 Topics:
-- Name: About networking
-  File: about-networking
 - Name: Understanding networking
   File: understanding-networking
 - Name: Zero trust networking

modules/nw-load-balancing-about.adoc

@@ -0,0 +1,23 @@
+// Module included in the following assemblies:
+//
+// * networking/understanding-networking.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-load-balancing-about_{context}"]
+= Supported load balancers
+
+Load balancing distributes incoming network traffic across multiple servers to maintain the health and efficiency of your clusters by ensuring that no single server bears too much load. Load balancers are devices that perform load balancing. They act as intermediaries between clients and servers to manage and direct traffic based on predefined rules. 
+
+{product-title} supports the following types of load balancers:
+
+* Classic Load Balancer (CLB)
+* Elastic Load Balancing (ELB)
+* Network Load Balancer (NLB)
+* Application Load Balancer (ALB)
+
+ELB is the default load-balancer type for AWS routers. CLB is the default for self-managed environments. NLB is the default for Red Hat OpenShift Service on AWS (ROSA).
+
+[IMPORTANT]
+====
+Use ALB in front of an application but not in front of a router. Using an ALB requires the AWS Load Balancer Operator add-on. This operator is not supported for all {aws-first} regions or for all {product-title} profiles.
+====

modules/nw-load-balancing-configure-define-type.adoc

@@ -0,0 +1,24 @@
+// Module included in the following assemblies:
+//
+// * networking/understanding-networking.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-load-balancing-configure-define-type_{context}"]
+= Define the default load balancer type
+
+When installing the cluster, you can specify the type of load balancer that you want to use. The type of load balancer you choose at cluster installation gets applied to the entire cluster.
+
+This example shows how to define the default load-balancer type for a cluster deployed on {aws-short}.You can apply the procedure on other supported platforms.
+
+[source,yaml]
+----
+apiVersion: v1
+kind: Network
+metadata:
+   name: cluster
+platform:
+  aws: <1>
+    lbType: classic <2>
+----
+<1> The `platform` key represents the platform on which you have deployed your cluster. This example uses `aws`.
+<2> The `lbType` key represents the load balancer type. This example uses the Classic Load Balancer, `classic`.

modules/nw-load-balancing-configure-specify-behavior.adoc

@@ -0,0 +1,35 @@
+// Module included in the following assemblies:
+//
+// * networking/understanding-networking.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-load-balancing-configure-specify-behavior_{context}"]
+= Specify load balancer behavior for an Ingress Controller
+
+After you install a cluster, you can configure your Ingress Controller to specify how services are exposed to external networks, so that you can better control the settings and behavior of a load balancer.
+
+[NOTE]
+====
+Changing the load balancer settings on an Ingress Controller might override the load balancer settings you specified at installation.
+====
+
+[source,yaml]
+----
+apiVersion: v1
+kind: Network
+metadata:
+  name: cluster
+endpointPublishingStrategy:
+  loadBalancer: <1>
+    dnsManagementPolicy: Managed
+    providerParameters:
+      aws:
+        classicLoadBalancer: <2>
+          connectionIdleTimeout: 0s
+        type: Classic
+      type: AWS
+    scope: External
+  type: LoadBalancerService
+----
+<1> The `loadBalancer' field specifies the load balancer configuration settings.
+<2> The `classicLoadBalancer` field sets the load balancer to `classic` and includes settings specific to the CLB on {aws-short}.

modules/nw-load-balancing-configure.adoc

@@ -0,0 +1,9 @@
+// Module included in the following assemblies:
+//
+// * networking/understanding-networking.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-load-balancing-configure_{context}"]
+= Configuring Load balancers
+
+You can define your default load-balancer type during cluster installation. After installation, you can configure your ingress controller to behave in a specific way that is not covered by the global platform configuration that you defined at cluster installation.

modules/nw-understanding-networking-choosing-service-types.adoc

@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+// * networking/understanding-networking.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-understanding-networking-choosing-service-types_{context}"]
+= Choosing between service types and API resources
+
+Service types and API resources offer different benefits for exposing applications and securing network connections. By leveraging the appropriate service type or API resource, you can effectively manage how your applications are exposed and ensure secure, reliable access for both internal and external clients.
+
+{product-title} supports the following service types and API resources:
+
+* Service Types
+
+** `ClusterIP` is intended for internal-only exposure. It is easy to set up and provides a stable internal IP address for accessing services within the cluster. `ClusterIP` is suitable for communication between services within the cluster.
+
+** `NodePort` allows external access by exposing the service on each node's IP at a static port. It is straightforward to set up and useful for development and testing. `NodePort` is good for simple external access without the need for a load balancer from the cloud provider.
+
+** `LoadBalancer` automatically provisions an external load balancer to distribute traffic across multiple nodes.
+It is ideal for production environments where reliable, high-availability access is needed.
+
+** `ExternalName` maps a service to an external DNS name to allow services outside the cluster to be accessed using the service's DNS name. It is good for integrating external services or legacy systems with the cluster.
+
+** Headless service is a DNS name that returns the list of pod IPs without providing a stable `ClusterIP`. This is ideal for stateful applications or scenarios where direct access to individual pod IPs is needed.
+
+* API Resources
+
+** `Ingress` provides control over routing HTTP and HTTPS traffic, including support for load balancing, SSL/TLS termination, and name-based virtual hosting. It is more flexible than services alone and supports multiple domains and paths. `Ingress` is ideal when complex routing is required.
+
+** `Route` is similar to `Ingress` but provides additional features, including TLS re-encryption and passthrough. It simplifies the process of exposing services externally. `Route` is best for when you need advanced features, such as integrated certificate management.
+
+If you need a simple way to expose a service to external traffic, `Route` or `Ingress` might be the best choice. These resources can be managed by a namespace admin or developer. The easiest approach is to create a route, check its external DNS name, and configure your DNS to have a CNAME that points to the external DNS name. 
+
+For HTTP/HTTPS/TLS, `Route` or `Ingress` should suffice. Anything else is more complex and requires a cluster admin to ensure ports are accessible or MetalLB is configured. `LoadBalancer` services are also an option in cloud environments or appropriately configured bare-metal environments.

modules/nw-understanding-networking-common-practices.adoc

@@ -0,0 +1,13 @@
+// Module included in the following assemblies:
+//
+// * networking/understanding-networking.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-understanding-networking-common-practices_{context}"]
+= Common practices for networking services
+
+In {product-title}, services create a single IP address for clients to use, even if multiple pods are providing that service. This abstraction enables seamless scaling, fault tolerance, and rolling upgrades without affecting clients.
+
+Network security policies manage traffic within the cluster. Network controls empower namespace administrators to define ingress and egress rules for their pods. By using network administration policies, cluster administrators can establish namespace policies, override namespace policies, or set default policies when none are defined.
+
+Egress firewall configurations control outbound traffic from pods. These configuration settings ensure that only authorized communication occurs. The ingress node firewall protects nodes by controlling incoming traffic. Additionally, the Universal Data Network manages data traffic across the cluster.

modules/nw-understanding-networking-concepts-components.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * networking/understanding-networking.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-understanding-networking-concepts-components_{context}"]
+= Networking concepts and components
+
+Networking in {product-title} uses several key components and concepts.
+
+* Pods and services are the smallest deployable units in Kubernetes, and services provide stable IP addresses and DNS names for sets of pods. Each pod in a cluster is assigned a unique IP address. Pods use IP addresses to communicate directly with other pods, regardless of which node they are on. The pod IP addresses will change when pods are destroyed and created. Services are also assigned unique IP addresses. A service is associated with the pods that can provide the service. When accessed, the service IP address provides a stable way to access pods by sending traffic to one of the pods that backs the service.
+
+* Route and Ingress APIs define rules that route HTTP, HTTPS, and TLS traffic to services within the cluster. {product-title} provides both Route and Ingress APIs as part of the default installation, but you can add third-party Ingress Controllers to the cluster.
+
+* The Container Network Interface (CNI) plugin manages the pod network to enable pod-to-pod communication.
+
+* The Cluster Network Operator (CNO)  CNO manages the networking plugin components of a cluster. Using the CNO, you can set the network configuration, such as the pod network CIDR and service network CIDR.
+
+* DNS operators manage DNS services within the cluster to ensure that services are reachable by their DNS names.
+
+* Network controls define how pods are allowed to communicate with each other and with other network endpoints. These policies help secure the cluster by controlling traffic flow and enforcing rules for pod communication.
+
+* Load balancing distributes network traffic across multiple servers to ensure reliability and performance.
+
+* Service discovery is a mechanism for services to find and communicate with each other within the cluster.
+
+* The Ingress Operator uses {product-title} Route to manage the router and enable external access to cluster services. 

modules/nw-understanding-networking-controls.adoc

@@ -0,0 +1,15 @@
+// Module included in the following assemblies:
+//
+// * networking/understanding-networking.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-understanding-networking-controls_{context}"]
+= Network controls
+
+Network controls define rules for how pods are allowed to communicate with each other and with other network endpoints. Network controls are implemented at the network level to ensure that only allowed traffic can flow between pods. This helps secure the cluster by restricting traffic flow and preventing unauthorized access.
+
+* Admin network policies (ANP): ANPs are cluster-scoped custom resource definitions (CRDs). As a cluster administrator, you can use an ANP to define network policies at a cluster level. You cannot override these policies by using regular network policy objects. These policies enforce strict network security rules across the entire cluster. ANPs can specify ingress and egress rules to allow administrators to control the traffic that enters and leaves the cluster.
+
+* Egress firewall: The egress firewall restricts egress traffic leaving the cluster. With this firewall, administrators can limit the external hosts that pods can access from within the cluster. You can configure egress firewall policies to allow or deny traffic to specific IP ranges, DNS names, or external services. This helps prevent unauthorized access to external resources and ensures that only allowed traffic can leave the cluster.
+
+* Ingress node firewall: The ingress node firewall controls ingress traffic to the nodes in a cluster. With this firewall, administrators define rules that restrict which external hosts can initiate connections to the nodes. This helps protect the nodes from unauthorized access and ensures that only trusted traffic can reach the cluster.

modules/nw-understanding-networking-dns-example.adoc

@@ -0,0 +1,106 @@
+// Module included in the following assemblies:
+//
+// * networking/understanding-networking.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="nw-understanding-networking-dns-example_{context}"]
+= Example: DNS use case
+
+For this example, a front-end application is running in one set of pods and a back-end service is running in another set of pods. The front-end application needs to communicate with the back-end service. You create a service for the back-end pods that gives it a stable IP address and DNS name. The front-end pods use this DNS name to access the back-end service regardless of changes to individual pod IP addresses.
+
+By creating a service for the back-end pods, you provide a stable IP and DNS name, `backend-service.default.svc.cluster.local`, that the front-end pods can use to communicate with the back-end service. This setup would ensure that even if individual pod IP addresses change, the communication remains consistent and reliable. 
+
+The following steps demonstrate an example of how to configure front-end pods to communicate with a back-end service using DNS.
+
+. Create the back-end service. 
+
+.. Deploy the back-end pods.
++
+[source, yaml]
+----
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: backend-deployment
+  labels:
+    app: backend
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: backend
+  template:
+    metadata:
+      labels:
+        app: backend
+    spec:
+      containers:
+        - name: backend-container
+          image: your-backend-image
+          ports:
+            - containerPort: 8080
+----
+
+.. Define a service to expose the back-end pods.
++
+[source, yaml]
+----
+apiVersion: v1
+kind: Service
+metadata:
+  name: backend-service
+spec:
+  selector:
+    app: backend
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 8080
+----
+
+. Create the front-end pods.
+
+.. Define the front-end pods.
++
+[source, yaml]
+----
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: frontend-deployment
+  labels:
+    app: frontend
+  spec:
+    replicas: 3
+    selector:
+    matchLabels:
+      app: frontend
+   template:
+   metadata:
+     labels:
+       app: frontend
+   spec:
+     containers:
+       - name: frontend-container
+         image: your-frontend-image
+         ports:
+           - containerPort: 80
+----
+
+.. Apply the pod definition to your cluster.
++
+[source,terminal]
+----
+$ oc apply -f frontend-deployment.yaml
+----
+
+. Configure the front-end to communicate with the back-end. 
++
+In your front-end application code, use the DNS name of the back-end service to send requests. For example, if your front-end application needs to fetch data from the back-end pod, your application might include the following code:
++
+[source, JavaScript]
+----
+fetch('http://backend-service.default.svc.cluster.local/api/data')
+  .then(response => response.json())
+  .then(data => console.log(data));
+----

modules/nw-understanding-networking-dns-terms.adoc

@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+//
+// * networking/understanding-networking.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-understanding-networking-dns-terms_{context}"]
+= Key DNS terms
+
+* CoreDNS: CoreDNS is the DNS server and provides name resolution for services and pods.
+
+* DNS names: Services are assigned DNS names based on their namespace and name. For example, a service named `my-service` in the `default` namespace would have the DNS name `my-service.default.svc.cluster.local`.
+
+* Domain names: Domain names are the human-friendly names used to access websites and services, such as `example.com`.
+
+* IP addresses: IP addresses are numerical labels assigned to each device connected to a computer network that uses IP for communication. An example of an IPv4 address is `192.0.2.1`. An example of an IPv6 address is `2001:0db8:85a3:0000:0000:8a2e:0370:7334`.
+
+* DNS servers: DNS servers are specialized servers that store DNS records. These records map domain names to IP addresses. When you type a domain name into your browser, your computer contacts a DNS server to find the corresponding IP address.
+
+* Resolution process: A DNS query is sent to a DNS resolver. The DNS resolver then contacts a series of DNS servers to find the IP address associated with the domain name. The resolver will try using the name with a series of domains, such as `<namespace>.svc.cluster.local`, `svc.cluster.local`, and `cluster.local`. This process stops at the first match. The IP address is returned to your browser and then connects to the web server using the IP address.

modules/nw-understanding-networking-dns.adoc

@@ -0,0 +1,11 @@
+// Module included in the following assemblies:
+//
+// * networking/understanding-networking.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-understanding-networking-dns_{context}"]
+= The Domain Name System (DNS)
+
+The Domain Name System (DNS) is a hierarchical and decentralized naming system used to translate human-friendly domain names, such as www.example.com, into IP addresses that identify computers on a network. DNS plays a crucial role in service discovery and name resolution.
+
+{product-title} provides a built-in DNS to ensure that services can be reached by their DNS names. This helps maintain stable communication even if the underlying IP addresses change. When you start a pod, environment variables for service names, IP addresses, and ports are created automatically to enable the pod to communicate with other services.

modules/nw-understanding-networking-exposing-applications.adoc

@@ -0,0 +1,11 @@
+// Module included in the following assemblies:
+//
+// * networking/understanding-networking.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="nw-understanding-networking-exposing-applications_{context}"]
+= Exposing applications
+
+ClusterIP exposes services on an internal IP within the cluster to make the cluster accessible only to other services within the cluster. The NodePort service type exposes the service on a static port on each node's IP. This service type allows external traffic to access the service. Load balancers are typically used in cloud or bare-metal environments that use MetalLB. This service type provisions an external load balancer that routes external traffic to the service. On bare-metal environments, MetalLB uses VIPs and ARP announcements or BGP announcements.
+
+Ingress is an API object that manages external access to services, such as load balancing, SSL/TLS termination, and name-based virtual hosting. An Ingress Controller, such as NGINX or HAProxy, implements the Ingress API and handles traffic routing based on user-defined rules.