Merge pull request #87228 from DCChadwick/osdocs8646b

OSDOCS-8646: Rewriting introduction to networking (ContentX)

Author: mburke5678

_topic_maps/_topic_map.yml

@@ -1333,8 +1333,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));
+----