Implement ServiceFacade behind an alpha feature gate

[mflendrich]

Is there an existing issue for this?

• I have searched the existing issues

Problem Statement

Implement an abstraction between the Kubernetes Service and Kong Service (proposed name: ServiceFacade - suggestions welcome) that will be usable as a backendRef in Gateway API routes and Ingress.

Design doc link.

This feature should be opt-in:

• the CRD should not be installed "by default" by the user who comes to KIC
• the support for this feature should be hidden behind an alpha feature gate

Proposed Solution

1. create a new ServiceFacade CRD (distributed separately) similar to the resource below:

   apiVersion: configuration.konghq.com/v1beta1
   kind: ServiceFacade
   metadata:
     name: payments-service-group1
     annotations:
       konghq.com/plugins: acl-l1
   spec:
     isFacadeFor:
       apiGroup: v1
       kind: Service
       name: payments-service
     port: 8080

2. Support ServiceFacade in rule types in KIC:
   1. Ingress. allow ServiceFacade to be set as defaultBackend and individual rules' backend
   2. Gateway API: allow all kinds of Gateway API routes to have ServiceFacade as a backendRef
   3. Explicitly not supported (to be optionally implemented later if necessary): TCPIngress, UDPIngress
3. Ensure that setting customizations work on ServiceFacade. This includes
   1. Attaching plugins to a ServiceFacade
   2. More broadly speaking: attaching other types of settings (including proxy/upstream) settings

Additional information

Diagram of the desired use:

Acceptance Criteria

• The ServiceFacade CRD exists and is not installed by default
• The service facade semantics are implemented and only enabled if the service facade alpha feature gate is enabled
• An installation and usage guide for ServiceFacade exists (including alpha warnings)
• If enabled, ServiceFacade works as a backend for Ingress
• Plugin attaching to a ServiceFacade works
• All other customizations configurable on a Service (annotations) work

[czeslavo]

I'd like to make some suggestions and clarify some parts of the suggested solution so that we can include them in the acceptance criteria:

1. The suggested solution says the new CRD should be "distributed separately". Does it mean we'd like to introduce a separate channel for our CRDs (using the Gateway API nomenclature), e.g. "experimental" that would include all standard (GA and beta) CRDs + alpha ones and exclude alpha CRDs from the "standard" channel (the one we implicitly already have)?

2. I'd propose naming the new CRD KongService. My reasoning for this name is that it will map 1-1 with a Kong Service created in Gateway. We could advertise it as a way to force names of Services created in Kong.

3. As Gateway API Routes can have multiple backendRefs in a single rule, how do we handle the case when the new CRD instance is used as one of many in such a group?

   1. Do we create a separate Kong Service entity with Upstream Targets and break the promise to create only one Service in Kong for the new CRD I mentioned in point 2?
   2. Do we forbid using the new CRD in Gateway API Routes with multiple backendRefs?

4. We could use introducing the new CRD as a chance to allow the use of load balancing between multiple Kubernetes Services in Ingress API. We'd only have to allow specifying multiple backendRefs (a term borrowed from Gateway API) in the new CRD instead of just one isFacadeFor. For starters, we could allow only one to be defined, but make the field a slice to not block ourselves from introducing such a change if needed.

[czeslavo]

Notes from a meeting with @mflendrich

1. The suggested solution says the new CRD should be "distributed separately". Does it mean we'd like to introduce a separate channel for our CRDs (using the Gateway API nomenclature), e.g. "experimental" that would include all standard (GA and beta) CRDs + alpha ones and exclude alpha CRDs from the "standard" channel (the one we implicitly already have)?

It would be preferable to not split the CRDs bundles by the criteria mentioned above (GA+ beta vs. alpha). We'd rather prefer to make the decision where a CRD lands (standard or experimental) individually for every CRD. The experimental channel should not be covered in the Helm chart. The name of the new channel is to be discussed ("opt-in" sounds like a good candidate as it emphasizes the nature of this channel - these are opt-in functionalities that are not going to be graduated to beta/GA most probably).

---

2. I'd propose naming the new CRD KongService. My reasoning for this name is that it will map 1-1 with a Kong Service created in Gateway. We could advertise it as a way to force names of Services created in Kong.

Kong prefix could be a good idea, but we should make the name unique in a way it's hard to misjudge it for being just a regular Service, e.g. KongServiceFacade. Let's stick to KongServiceFacade name until we find something better.

---

3. As Gateway API Routes can have multiple backendRefs in a single rule, how do we handle the case when the new CRD instance is used as one of many in such a group?
   1. Do we create a separate Kong Service entity with Upstream Targets and break the promise to create only one Service in Kong for the new CRD I mentioned in point 2?
   2. Do we forbid using the new CRD in Gateway API Routes with multiple backendRefs?

• The decision is to tackle Ingress API first and create a separate issue for Gateway API.
• AI: create a separate issue/spike for figuring out this for Gateway API Routes.

---

4. We could use introducing the new CRD as a chance to allow the use of load balancing between multiple Kubernetes Services in Ingress API. We'd only have to allow specifying multiple backendRefs (a term borrowed from Gateway API) in the new CRD instead of just one isFacadeFor. For starters, we could allow only one to be defined, but make the field a slice to not block ourselves from introducing such a change if needed.

This would be nice-to-have if there would be a use-case for that. This is already supported in Gateway API (multiple backendRefs).