diff --git a/docs/src/capi/explanation/index.md b/docs/src/capi/explanation/index.md index 7579ef258..b76885878 100644 --- a/docs/src/capi/explanation/index.md +++ b/docs/src/capi/explanation/index.md @@ -15,9 +15,11 @@ Overview about installation-methods.md -security +ingress +load-balancer capi-ck8s.md in-place-upgrades.md +security ``` diff --git a/docs/src/capi/explanation/ingress.md b/docs/src/capi/explanation/ingress.md new file mode 100644 index 000000000..ad96afca1 --- /dev/null +++ b/docs/src/capi/explanation/ingress.md @@ -0,0 +1,2 @@ +```{include} ../../snap/explanation/ingress.md +``` diff --git a/docs/src/capi/explanation/load-balancer.md b/docs/src/capi/explanation/load-balancer.md new file mode 100644 index 000000000..d4e80f761 --- /dev/null +++ b/docs/src/capi/explanation/load-balancer.md @@ -0,0 +1,2 @@ +```{include} ../../snap/explanation/load-balancer.md +``` diff --git a/docs/src/charm/explanation/index.md b/docs/src/charm/explanation/index.md index 660f34826..6caba45f5 100644 --- a/docs/src/charm/explanation/index.md +++ b/docs/src/charm/explanation/index.md @@ -14,6 +14,8 @@ Overview about installation-methods.md channels +ingress +load-balancer security ``` diff --git a/docs/src/charm/explanation/ingress.md b/docs/src/charm/explanation/ingress.md new file mode 100644 index 000000000..ad96afca1 --- /dev/null +++ b/docs/src/charm/explanation/ingress.md @@ -0,0 +1,2 @@ +```{include} ../../snap/explanation/ingress.md +``` diff --git a/docs/src/charm/explanation/load-balancer.md b/docs/src/charm/explanation/load-balancer.md new file mode 100644 index 000000000..d4e80f761 --- /dev/null +++ b/docs/src/charm/explanation/load-balancer.md @@ -0,0 +1,2 @@ +```{include} ../../snap/explanation/load-balancer.md +``` diff --git a/docs/src/snap/explanation/index.md b/docs/src/snap/explanation/index.md index 678419952..9457c4d0d 100644 --- a/docs/src/snap/explanation/index.md +++ b/docs/src/snap/explanation/index.md @@ -17,6 +17,7 @@ certificates channels clustering ingress +load-balancer epa high-availability security diff --git a/docs/src/snap/explanation/ingress.md b/docs/src/snap/explanation/ingress.md index 09ebf334b..3fd9a79a7 100644 --- a/docs/src/snap/explanation/ingress.md +++ b/docs/src/snap/explanation/ingress.md @@ -17,7 +17,7 @@ services, and external resources, ensuring smooth traffic flow within the cluste The current implementation of {{product}} leverages a widely adopted CNI (Container Network Interface) called [Cilium][Cilium]. If you wish to use a different network plugin -the implementation and configuration falls under your responsibility. +please follow the [alternative-cni] guide. Learn how to use the {{product}} default network in the [networking how-to guide][Network]. @@ -78,8 +78,10 @@ outlining rules that direct traffic to your application's Kubernetes service. +[alternative-cni]: ../howto/networking/alternative-cni [Ingress]: ../howto/networking/default-ingress [Network]: ../howto/networking/default-network +[LoadBalancer]: load-balancer [Cilium]: https://cilium.io/ [network plugin]: https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/ [Service]: https://kubernetes.io/docs/concepts/services-networking/service/ diff --git a/docs/src/snap/explanation/load-balancer.md b/docs/src/snap/explanation/load-balancer.md new file mode 100644 index 000000000..dbb747a91 --- /dev/null +++ b/docs/src/snap/explanation/load-balancer.md @@ -0,0 +1,87 @@ +# Load balancer + +{{ product }}' load balancer feature allows you to expose your workloads +externally and distribute incoming network traffic from outside of your +cluster to the services inside. + +## Kubernetes service types + +Kubernetes allows you to expose your cluster's workloads in the following ways: + +- **ClusterIP**: Exposes the service on a cluster-internal IP. With ClusterIP + the service is only reachable from within the cluster. +- **NodePort**: Exposes the service on each Node's IP at a static port. +- **LoadBalancer**: Exposes a single IP address to distribute the incoming + network traffic across multiple cluster nodes. + +```{note} +The load balancer service type at layer 4 should not be confused with the +Ingress Controller which operates at layer 7 (HTTP/HTTPS) and routes traffic +from outside of your cluster to services inside of your cluster. Learn more +about Ingress in the [Ingress guide][Ingress]. +``` + +## Use case + +The {{ product }}' load balancer feature is suitable for bare-metal setups and +private data-centers. If you are operating {{ product }} in a public cloud you +should evaluate your cloud-provider's load balancing solution as well. + +## IP address allocation + +The load balancer feature assigns and releases IP addresses +for services of type LoadBalancer from a pool of IPs. Learn how to configure +the IP address pool with the [default load balancer] guide. + +## Advertising IP address externally + +The load balancer feature advertises the external IP address of the service +outside of the cluster. To accomplish this, the load balancer uses either Layer +2 mode or Border Gateway Protocol (BGP) Mode. + +### Layer 2 Mode + +In Layer 2 mode, a cluster node takes the +responsibility of spreading the traffic for a service IP to its associated +pods using [kube-proxy]. Traffic routing relies on Address Resolution +Protocol ([ARP]) for IPv4 and Neighbor Discovery Protocol ([NDP]) +for IPv6. While this mode is easy to implement, it is only suitable for +small-scale deployments. Consult the [layer 2 mode documentation] for more +information. + +### BGP Mode + +With BGP mode, neighboring routers exchange routing information +through peering sessions enabling efficient traffic distribution. +Traffic is balanced across nodes ensuring efficient resource utilization. +While this approach is more difficult to implement, it is suitable for +large-scale deployments. Refer to the [bgp mode documentation] for more +details. + +## Traffic flow with a load balancer + +When you expose a service with a load balancer, the following steps occur: + +- A client sends a request to the external IP address allocated by the load + balancer. +- The load balancer decides which Kubernetes node should handle the request + based on the selected underlying mechanism (BGP or Layer 2). +- [kube-proxy] routes the request to a specific pod in the service. + +## Further reading + +- Get started with configuring your cluster's [default load balancer]. +- Create a service of the type LoadBalancer to expose your workloads externally + by following the [upstream guide]. +- Learn more about Ingress in the [Ingress guide][Ingress] + + + +[Ingress]: ingress +[default load balancer]: ../howto/networking/default-loadbalancer +[kube-proxy]: https://kubernetes.io/docs/reference/command-line-tools-reference/kube-proxy/ +[ARP]: https://en.wikipedia.org/wiki/Address_Resolution_Protocol +[NDP]: https://en.wikipedia.org/wiki/Neighbor_Discovery_Protocol +[layer 2 mode documentation]: https://metallb.io/concepts/layer2/ +[bgp mode documentation]: https://metallb.io/concepts/bgp/ +[upstream guide]: https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/#create-a-service diff --git a/docs/src/snap/howto/networking/default-loadbalancer.md b/docs/src/snap/howto/networking/default-loadbalancer.md index f59a30ac4..1bcbb60f0 100644 --- a/docs/src/snap/howto/networking/default-loadbalancer.md +++ b/docs/src/snap/howto/networking/default-loadbalancer.md @@ -78,7 +78,11 @@ The default load-balancer can be disabled again with: sudo k8s disable load-balancer ``` +## Next Step + +- Learn more in the [Load-Balancer] explanation page. [CIDR]: https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing [getting-started-guide]: ../../tutorial/getting-started +[Load-Balancer]: ../../explanation/load-balance-workloads.md