[SRVLOGIC-443] Document Kubernetes service discovery

modules/serverless-logic-service-discovery.adoc

@@ -0,0 +1,109 @@
+// Module included in the following assemblies:
+//
+// * serverless/serverless-logic/serverless-logic-configuring-workflow-services.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="serverless-logic-kubernetes-service-discovery_{context}"]
+= Kubernetes service discovery
+
+[role="_abstract"]
+You can use Kubernetes service discovery to reference Kubernetes resources using a custom URI for HTTP requests. The {ServerlessLogicOperatorName} resolves this URI into a network endpoint (URL) during workflow deployment.
+
+[NOTE]
+====
+Service discovery triggers a scan of workflow configuration parameters. If application startup time is critical, consider using a static URL instead.
+====
+
+== URI pattern for service discovery
+
+Service discovery URIs follow a structure based on the Group, Version, and Kind (GVK) of the resource:
+
+[source,terminal]
+----
+kubernetes:<kind>.<version>.<group>/<namespace>/<resource_name>?<attribute_name>=<attribute_value>
+----
+where:
+
+`<kind>.<version>.<group>`:: Specifies the GVK of the resource.
+`<namespace>`:: Specifies the namespace of the resource. Defaults to current namespace if omitted.
+`<resource_name>`:: Specifies the name of the target resource.
+`<attribute_name>=<attribute_value>`:: Specifies additional resource attributes, such as labels or ports.
+
+Supported schemes and resources::
+
+The service discovery URI supports the following schemes:
+
+* `kubernetes`
+* `openshift`
+* `knative`
++
+For Knative Services, you can use a simplified `knative:<namespace>/<service_name>` pattern.
+
++
+--
+The following table lists the supported Kubernetes resources for GVK identifiers:
+
+[cols="1,1", options="header"]
+|===
+| Resource | GVK identifier
+
+| Kubernetes Service
+| `services.v1`
+
+| Knative Service
+| `services.v1.serving.knative.dev`
+
+| Pod
+| `pods.v1`
+
+| Deployment
+| `deployments.v1.apps`
+
+| DeploymentConfig
+| `deploymentconfigs.v1.apps.openshift.io`
+
+| StatefulSet
+| `statefulsets.v1.apps`
+
+| Route
+| `routes.v1.route.openshift.io`
+
+| Ingress
+| `ingresses.v1.networking.k8s.io`
+|===
+--
+
+Query parameters::
+Query parameters allow the Operator to filter or select specific resources when multiple matches exist.
++
+--
+The following table lists the supported query parameters:
+
+[cols="1,2,1", options="header"]
+|===
+|Parameter|Purpose|Example
+
+|label
+|Filter resources when multiple resources match. Supports multiple labels joined with `&`.
+|`label=app=myapp&env=prod`
+
+|port
+|Select a specific port if multiple ports are exposed.
+|`port=http`
+|===
+--
+
+== Service discovery resolution
+
+The Operator performs Kubernetes service discovery during the deployment of a managed workflow. It scans the associated workflow config map for URIs that match the discovery pattern, parses each URI, queries the Kubernetes API, and writes the resolved endpoints to an operator-managed config map.
+
+The Operator resolves resources differently based on their type:
+
+* *Direct URL resolution*: For `Service`, `KnativeService`, `Ingress`, or `Route` resources, the Operator returns the service URL or host IP. The Operator automatically uses `https` if TLS is detected.
+* *Indirect service resolution*: For `Pod`, `Deployment`, `DeploymentConfig`, or `StatefulSet` resources, the Operator checks for an associated service. If found, the Operator returns the service URL.
+* *Error handling*: If URI parsing fails or the resource does not exist, the Operator logs an exception. If a resource exists but has no associated service, the Operator issues a warning.
+
+[IMPORTANT]
+====
+The Operator fully controls the operator-managed config map. It overwrites any manual edits during the next reconciliation cycle.
+====

serverless-logic/serverless-logic-configuring-workflow-services.adoc

@@ -15,4 +15,6 @@ include::modules/serverless-logic-modifying-managed-properties-workflow-services
 
 include::modules/serverless-logic-defining-global-managed-properties.adoc[leveloffset=+1]
 
+include::modules/serverless-logic-service-discovery.adoc[leveloffset=+1]
+
 include::modules/serverless-logic-customizing-podspec-definition.adoc[leveloffset=+1]