docs: add KongServiceFacade docs and examples (#5298)

* docs: add KongServiceFacade docs and examples

* Apply suggestions from code review

Co-authored-by: Michał Flendrich <michal.flendrich@konghq.com>

---------

Co-authored-by: Michał Flendrich <michal.flendrich@konghq.com>

CHANGELOG.md

@@ -100,6 +100,7 @@ Adding a new version? You'll need three changes:
   [#5234](https://github.com/Kong/kubernetes-ingress-controller/pull/5234)
   [#5290](https://github.com/Kong/kubernetes-ingress-controller/pull/5290)
   [#5282](https://github.com/Kong/kubernetes-ingress-controller/pull/5282)
+  [#5298](https://github.com/Kong/kubernetes-ingress-controller/pull/5298)
   [#5302](https://github.com/Kong/kubernetes-ingress-controller/pull/5302)
 - Added support for GRPC over HTTP (without TLS) in Gateway API.
   [#5128](https://github.com/Kong/kubernetes-ingress-controller/pull/5128)

FEATURE_GATES.md

@@ -168,3 +168,96 @@ services: if two HTTPRoute rules use both serviceA and serviceB in their
 backendRefs, KIC will generate a single Kong service with endpoints from both
 serviceA and serviceB, named for the first rule and match indices with that
 combination of Services.
+
+## Using KongServiceFacade
+
+In KIC 3.1.0 we introduced a new feature called `KongServiceFacade`. Currently, we only
+support `KongServiceFacade` to be used as a backend for `networking.k8s.io/v1` `Ingress`es.
+If you find this might be useful to you in other contexts (e.g. Gateway API's `HTTPRoute`s),
+please let us know in the [#5216](https://github.com/Kong/kubernetes-ingress-controller/issues/5216)
+issue tracking this effort.
+
+### Installation
+
+`KongServiceFacade` feature is currently in `Alpha` maturity and is disabled by default.
+To start using it, you must not only enable the feature gate (`KongServiceFacade=true`),
+but also install the `KongServiceFacade` CRD which is distributed in a separate
+package we named `incubator`. You can install it by running:
+
+```shell
+kubectl apply -k 'https://github.com/Kong/kubernetes-ingress-controller/config/crd/incubator?ref=main'
+```
+
+### Usage
+
+Once the CRD is installed and the feature gate is set to `true`, you can start using it by creating
+`KongServiceFacade` objects and use them as your `netv1.Ingress` backends. For example, to create
+a `KongServiceFacade` that points to a service named `my-service` in the `default` namespace and uses
+its port number `80`, you can run:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: incubator.ingress-controller.konghq.com/v1alpha1
+kind: KongServiceFacade
+metadata:
+  name: my-service-facade
+  namespace: default
+  annotations:
+    kubernetes.io/ingress.class: kong
+spec:
+  backendRef:
+    name: my-service
+    port: 80
+EOF
+```
+
+For a complete CRD reference please see the [incubator-crd-reference] document. 
+
+To use the `KongServiceFacade` as a backend for your `netv1.Ingress`, you can create an `Ingress`
+like the following:
+
+```shell
+kubectl apply -f - <<EOF
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: my-ingress
+  namespace: default
+  annotations:
+    konghq.com/strip-path: "true"
+spec:
+  ingressClassName: kong
+  rules:
+  - http:
+      paths:
+      - path: /my-service
+        pathType: Prefix
+        backend:
+          resource:
+            apiGroup: incubator.ingress-controller.konghq.com
+            kind: KongServiceFacade
+            name: my-service-facade
+EOF
+```
+
+Please note the `KongServiceFacade` must be in the same namespace as the `Ingress` that uses it.
+
+An advantage of using `KongServiceFacade` over plain `corev1.Service`s is that you can create multiple
+`KongServiceFacade`s that point to the same `Service` and KIC will always generate one Kong Service per each
+`KongServiceFacade`. That enables you to, e.g., use different `KongPlugin`s for each `KongServiceFacade`
+while still pointing to the same Kubernetes `Service`. A single `KongServiceFacade` may be used in multiple
+`Ingress`es and customization done through the `KongServiceFacade`'s annotations will be honored in all of them
+on a single Kong Service level (no need to duplicate annotations in multiple `Ingress`es).
+
+A recommended, generally available alternative to `KongServiceFacade` exists: you can
+create several Kubernetes `Service`s with the same selector. `KongServiceFacade` should
+be useful if you are unable to use the `Service` alternative. Reasons known at the
+moment of writing are: using certain mesh solutions (Consul Connect) that [impose a
+"single service only" requirement](https://github.com/hashicorp/consul-k8s/issues/68) and (hypothetical) performance implications of
+repetitive kube-proxy reconciliation.
+
+For a complete example of using `KongServiceFacade` for customizing `Service` authentication methods, please
+refer to the [kong-service-facade.yaml] manifest in our examples.
+
+[incubator-crd-reference]: ./docs/incubator-api-reference.md
+[kong-service-facade.yaml]: ./examples/kong-service-facade.yaml

config/crd/incubator/incubator.ingress-controller.konghq.com_kongservicefacades.yaml

@@ -19,12 +19,14 @@ spec:
   - name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: KongServiceFacade allows creating separate Kong Services for
+        description: "KongServiceFacade allows creating separate Kong Services for
           a single Kubernetes Service. It can be used as Kubernetes Ingress' backend
           (via its path's `backend.resource` field). It's designed to enable creating
-          two "virtual" Services in Kong that will point to the same Kubernetes Service,
-          but will have different configuration (e.g. different set of plugins, different
-          load balancing algorithm, etc.).
+          two \"virtual\" Services in Kong that will point to the same Kubernetes
+          Service, but will have different configuration (e.g. different set of plugins,
+          different load balancing algorithm, etc.). \n KongServiceFacade requires
+          `kubernetes.io/ingress.class` annotation with a value matching the ingressClass
+          of the Kong Ingress Controller (`kong` by default) to be reconciled."
         properties:
           apiVersion:
             description: 'APIVersion defines the versioned schema of this representation

docs/incubator-api-reference.md

@@ -0,0 +1,65 @@
+<!-- This document is generated by KIC's 'generate.docs' make target, DO NOT EDIT -->
+
+## Packages
+- [incubator.ingress-controller.konghq.com/v1alpha1](#incubatoringress-controllerkonghqcomv1alpha1)
+
+
+## incubator.ingress-controller.konghq.com/v1alpha1
+
+Package v1alpha1 contains API Schema definitions for the incubator.ingress-controller.konghq.com v1alpha1 API group.
+
+- [KongServiceFacade](#kongservicefacade)
+
+### KongServiceFacade
+
+
+
+KongServiceFacade allows creating separate Kong Services for a single Kubernetes Service. It can be used as Kubernetes Ingress' backend (via its path's `backend.resource` field). It's designed to enable creating two "virtual" Services in Kong that will point to the same Kubernetes Service, but will have different configuration (e.g. different set of plugins, different load balancing algorithm, etc.). <br /><br /> KongServiceFacade requires `kubernetes.io/ingress.class` annotation with a value matching the ingressClass of the Kong Ingress Controller (`kong` by default) to be reconciled.
+
+<!-- kong_service_facade description placeholder -->
+
+| Field | Description |
+| --- | --- |
+| `apiVersion` _string_ | `incubator.ingress-controller.konghq.com/v1alpha1`
+| `kind` _string_ | `KongServiceFacade`
+| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. |
+| `spec` _[KongServiceFacadeSpec](#kongservicefacadespec)_ |  |
+
+
+
+
+### KongServiceFacadeBackend
+
+
+
+KongServiceFacadeBackend is a reference to a Kubernetes Service that is used as a backend for a Kong Service Facade.
+
+
+
+| Field | Description |
+| --- | --- |
+| `name` _string_ | Name is the name of the referenced Kubernetes Service. |
+| `port` _integer_ | Port is the port of the referenced Kubernetes Service. |
+
+
+_Appears in:_
+- [KongServiceFacadeSpec](#kongservicefacadespec)
+
+### KongServiceFacadeSpec
+
+
+
+KongServiceFacadeSpec defines the desired state of KongServiceFacade.
+
+
+
+| Field | Description |
+| --- | --- |
+| `backendRef` _[KongServiceFacadeBackend](#kongservicefacadebackend)_ | Backend is a reference to a Kubernetes Service that is used as a backend for this Kong Service Facade. |
+
+
+_Appears in:_
+- [KongServiceFacade](#kongservicefacade)
+
+
+