Update Service Mesh docs

Documentation/internals/cilium_operator.rst

@@ -220,3 +220,26 @@ constructs to derivative CNP/CCNP objects without these fields.
 
 For more information, see how Cilium network policies incorporate the
 use of ``toGroups`` to :ref:`lock down external access using AWS security groups<aws_metadata_with_policy>`.
+
+Ingress and Gateway API Support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When Ingress or Gateway API support is enabled, the Cilium Operator performs the
+task of parsing Ingress or Gateway API objects and converting them into
+``CiliumEnvoyConfig`` objects used for configuring the per-node Envoy proxy.
+
+Additionally, Secrets used by Ingress or Gateway API objects will be synced to
+a Cilium-managed namespace that the Cilium Agent is then granted access to. This
+reduces the permissions required of the Cilium Agent.
+
+Mutual Authentication Support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When Cilium's Mutual Authentication Support is enabled, the Cilium Operator is
+responsible for ensuring that each Cilium Identity has an associated identity
+in the certificate management system. It will create and delete identity
+registrations in the configured certificate management section as required.
+The Cilium Operator does not, however have any to the key material in the
+identities.
+
+That information is only shared with the Cilium Agent via other channels.

Documentation/network/servicemesh/gateway-api/gateway-api.rst

@@ -10,7 +10,20 @@
 Gateway API Support
 *******************
 
-Cilium supports Gateway API v0.7.0 for below resources, all the Core conformance
+What is Gateway API?
+####################
+
+Gateway API is a Kubernetes SIG-Network subproject to design a successor for
+the Ingress object. It is a set of resources that model service networking in
+Kubernetes, and is designed to be role-oriented, portable, expressive, and
+extensible.
+
+See the `Gateway API site <https://gateway-api.sigs.k8s.io/>`__ for more details.
+
+Cilium Gateway API Support
+##########################
+
+Cilium supports Gateway API v0.7.1 for below resources, all the Core conformance
 tests are passed.
 
 - `GatewayClass <https://gateway-api.sigs.k8s.io/api-types/gatewayclass/>`_
@@ -36,9 +49,9 @@ Cilium's Gateway API features:
    splitting
    header
 
-More examples can be found `upstream repository <https://github.com/kubernetes-sigs/gateway-api/tree/v0.7.0/examples/standard>`_.
+More examples can be found in the `upstream repository <https://github.com/kubernetes-sigs/gateway-api/tree/v0.7.1/examples/standard>`_.
 
 Troubleshooting
 ###############
 
-.. include:: troubleshooting.rst
+.. include:: troubleshooting.rst

Documentation/network/servicemesh/index.rst

@@ -6,8 +6,50 @@
 
 .. _servicemesh_root:
 
+************
 Service Mesh
-------------
+************
+
+What is Service Mesh?
+#####################
+
+With the introduction of distributed applications, additional visibility,
+connectivity, and security requirements have surfaced. Application components
+communicate over untrusted networks across cloud and premises boundaries,
+load-balancing is required to understand application protocols, resiliency is
+becoming crucial, and security must evolve to a model where sender and receiver
+can authenticate each other’s identity. In the early days of distributed
+applications, these requirements were resolved by directly embedding the
+required logic into the applications. A service mesh extracts these features out
+of the application and offers them as part of the infrastructure for all
+applications to use and thus no longer requires to change each application.
+
+Looking at the feature set of a service mesh today, it can be summarized as follows:
+
+- **Resilient Connectivity**: Service to service communication must be possible across
+  boundaries such as clouds, clusters, and premises. Communication must be
+  resilient and fault tolerant.
+- **L7 Traffic Management**: Load balancing, rate limiting, and resiliency must be
+  L7-aware (HTTP, REST, gRPC, WebSocket, …).
+- **Identity-based Security**: Relying on network identifiers to achieve security is
+  no longer sufficient, both the sending and receiving services must be able to
+  authenticate each other based on identities instead of a network identifier.
+- **Observability & Tracing**: Observability in the form of tracing and metrics is
+  critical to understanding, monitoring, and troubleshooting application stability,
+  performance, and availability.
+- **Transparency**: The functionality must be available to applications in a
+  transparent manner, i.e. without requiring to change application code.
+
+
+Why Cilium Service Mesh?
+########################
+
+Since its early days, Cilium has been well aligned with the service mesh concept
+by operating at both the networking and the application protocol layer to provide
+connectivity, load-balancing, security, and observability. For all network
+processing including protocols such as IP, TCP, and UDP, Cilium uses eBPF as the
+highly efficient in-kernel datapath. Protocols at the application layer such as
+HTTP, Kafka, gRPC, and DNS are parsed using a proxy such as Envoy. 
 
 .. toctree::
    :maxdepth: 2

Documentation/network/servicemesh/ingress.rst

@@ -106,7 +106,21 @@ Supported Ingress Annotations
      - ``disabled``
 
 Additionally, cloud-provider specific annotations for the LoadBalancer service
-are supported. Please refer to the `Kubernetes documentation <https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer>`_
+are supported.
+
+By default, annotations with values beginning with:
+
+* ``service.beta.kubernetes.io``
+* ``service.kubernetes.io``
+* ``cloud.google.com``
+
+will be copied from an Ingress object to the generated LoadBalancer service objects.
+
+This setting is controlled by the Cilium Operator's ``ingress-lb-annotation-prefixes``
+config flag, and can be configured in Cilium's Helm ``values.yaml``
+using the ``ingressController.ingressLBAnnotationPrefixes`` setting.
+
+Please refer to the `Kubernetes documentation <https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer>`_
 for more details.
 
 Examples

Documentation/network/servicemesh/l7-traffic-management.rst

@@ -16,11 +16,30 @@ and CiliumClusterwideEnvoyConfig).
 Prerequisites
 #############
 
-* Cilium must be configured with ``kubeProxyReplacement`` as partial
-  or strict. Please refer to :ref:`kube-proxy replacement <kubeproxy-free>`
+* Cilium must be configured with ``kubeProxyReplacement`` as ``true``.
+  Please refer to :ref:`kube-proxy replacement <kubeproxy-free>`
   for more details.
 * The minimum supported Kubernetes version for Ingress is 1.19.
 
+Caveats
+#######
+
+* ``CiliumEnvoyConfig`` resources have only minimal validation performed, and
+  do not have a defined conflict resolution behavior. This means that if you
+  create multiple CECs that modify the same parts of Envoy's config, the results
+  may be unpredictable.
+* In addition to this minimal validation, ``CiliumEnvoyConfig`` has minimal
+  feedback to the user about the correctness of the configuration. So in the
+  event a CEC does produce an undesirable outcome, troubleshooting will require
+  inspecting the Envoy config and logs, rather than being able to look at the
+  ``CiliumEnvoyConfig`` in question.  
+* ``CiliumEnvoyConfig`` is used by Cilium's Ingress and Gateway API support to
+  direct traffic through the per-node Envoy proxies. If you create CECs that
+  conflict with or modify the autogenerated config, results may be unpredictable.
+  Be very careful using CECs for these use cases. The above risks are managed
+  by ensuring that all config generated by Cilium is semantically valid, as far
+  as possible.
+
 .. include:: installation.rst
 
 Supported Envoy API Versions

Documentation/spelling_wordlist.txt

@@ -141,6 +141,7 @@ au
 auth
 autoMount
 autocompletion
+autogenerated
 automount
 autoscaler
 awk
@@ -619,6 +620,7 @@ subdirectories
 subfeatures
 subnet
 subnets
+subproject
 subregister
 subregisters
 subtypes