OWLS-89704 - Documented clusterService.sessionAffinity cluster spec element and updated generated desciption. (#3662)

* Documented `clusterService.sessionAffinity` cluster spec element and updated generated description. (#3662)

Co-authored-by: Rosemary Marano <[email protected]>

Author: ankedia

documentation/4.0/content/managing-domains/domain-resource.md

@@ -71,15 +71,15 @@ $ kubectl describe cluster <cluster-resource-name> -n <namespace>
 
 ### Domain and cluster resource attribute references
 
-The domain resource `metadata` section names the Domain and its namespace.  The name of the Domain is the default value for the `domainUID` which is used by the operator to distinguish domains running in the Kubernetes cluster that may have the same domain name. The Domain name must be unique in the namespace and the `domainUID` should be unique across the cluster.  The `domainUID`, Domain resource name, and domain name (from the WebLogic domain configuration) may all be different. Similarly, the cluster resource `metadata` section names the Cluster and its namespace. The `metadata.name` of a cluster resource must be referenced from the `spec.clusters` field of the domain resource. This name does not need to be the same as the name of the WebLogic cluster. The `spec.clusterName` field of the cluster resource must name the WebLogic cluster from the domain configuration. 
+The domain resource `metadata` section names the Domain and its namespace.  The name of the Domain is the default value for the `domainUID` which is used by the operator to distinguish domains running in the Kubernetes cluster that may have the same domain name. The Domain name must be unique in the namespace and the `domainUID` should be unique across the cluster.  The `domainUID`, Domain resource name, and domain name (from the WebLogic domain configuration) may all be different. Similarly, the cluster resource `metadata` section names the Cluster and its namespace. The `metadata.name` of a cluster resource must be referenced from the `spec.clusters` field of the domain resource. This name does not need to be the same as the name of the WebLogic cluster. The `spec.clusterName` field of the cluster resource must name the WebLogic cluster from the domain configuration.
 
 The domain resource `spec` section describes the intended running state of the domain, including intended runtime state of WebLogic Server instances, and details about Kubernetes Pod or Service generation, such as resource constraints, scheduling requirements, or volume mounts. The cluster resource `spec` section describes the intended number of member servers of that cluster to run and can set or override the other settings inherited from the domain resource.
 
 The operator automatically updates the `status` section of a deployed domain or cluster resource to describe the actual running state, including WebLogic Server instance runtime states and current health.
 
 Here are some references you can use for the fields in these sections:
 
-- See [Domain spec elements](#domain-spec-elements), [Pod Generation](#pod-generation), and [JVM memory and Java option environment variables](#jvm-memory-and-java-option-environment-variables) in this doc.
+- See [Domain and cluster spec elements](#domain-and-cluster-spec-elements), [Pod Generation](#pod-generation), and [JVM memory and Java option environment variables](#jvm-memory-and-java-option-environment-variables) in this doc.
 - See the Domain Resource [reference document](https://github.com/oracle/weblogic-kubernetes-operator/blob/{{< latestMinorVersion >}}/documentation/domains/Domain.md).
 - See the Cluster Resource [reference document](https://github.com/oracle/weblogic-kubernetes-operator/blob/{{< latestMinorVersion >}}/documentation/domains/Cluster.md).
 - Use [kubectl explain](#using-kubectl-explain) from the command line.
@@ -108,9 +108,11 @@ DESCRIPTION:
 ```
 **NOTE**: The `VERSION` field's value may be different, depending on the operator version you are using.
 
-### Domain spec elements
+### Domain and cluster spec elements
 
-The Domain `spec` section contains elements for configuring the domain operation and sub-sections specific to the Administration Server, specific clusters, or specific Managed Servers.
+The Domain `spec` section contains elements for configuring the domain operation and sub-sections specific to the Administration Server, specific clusters, or specific Managed Servers. The Cluster `spec` section contains elements for configuring the lifecycle options for all of the Managed Server members of a WebLogic cluster, including Java options, environment variables, additional Pod content, and the ability to explicitly start, stop, or restart cluster members.
+
+#### Domain spec elements
 
 Elements related to domain identification, container image, and domain home:
 
@@ -206,8 +208,18 @@ The elements `serverStartPolicy`, `serverPod` and `serverService` are repeated u
 Elements related to the customization of liveness and readiness probes:
 * See [Liveness probe customization]({{< relref "/managing-domains/domain-lifecycle/liveness-readiness-probe-customization#liveness-probe-customization" >}}) for details about the elements related to liveness probe customization and [Readiness probe customization]({{< relref "/managing-domains/domain-lifecycle/liveness-readiness-probe-customization#readiness-probe-customization" >}}) for details about the elements related to readiness probe customization.
 
+#### Cluster spec elements
+
+For a complete list of the Cluster spec elements, see [Cluster Spec](https://github.com/oracle/weblogic-kubernetes-operator/blob/{{< latestMinorVersion >}}/documentation/domains/Cluster.md#cluster-spec).
+
+Additional information for the `clusterService.sessionAffinity` element:
+
+* `sessionAffinity`: This is an advanced setting that is applicable only when the `kube-proxy` is running in non-default proxy modes, such as [User space (legacy) proxy mode](https://kubernetes.io/docs/concepts/services-networking/service/#proxy-mode-userspace) and [IPVS proxy mode](https://kubernetes.io/docs/concepts/services-networking/service/#proxy-mode-ipvs). It is used to enable session affinity based on the client's IP addresses. For more information, see the [Virtual IPs and service proxies](https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies). Must be `ClientIP` or `None`. Defaults to `None`.
+
+  **Note:** This setting is not applicable when the `kube-proxy` is running in the default [`iptables` proxy mode](https://kubernetes.io/docs/concepts/services-networking/service/#proxy-mode-iptables).
+
 {{% notice note %}}
-For additional domain resource attribute reference material, see [Domain resource attribute references](#domain-resource-attribute-references).
+For additional domain and cluster resource attribute reference material, see [Domain and cluster resource attribute references](#domain-and-cluster-resource-attribute-references).
 {{% /notice %}}
 
 ### JVM memory and Java option environment variables

documentation/domains/Cluster.json

@@ -129,7 +129,7 @@
       "properties": {
         "sessionAffinity": {
           "default": "None",
-          "description": "Supports \"ClientIP\" and \"None\". Used to maintain session affinity. Enable client IP based session affinity. Must be ClientIP or None. Defaults to None. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies",
+          "description": "Advanced setting to enable client IP based session affinity. Must be ClientIP or None. Defaults to None. More info: https://oracle.github.io/weblogic-kubernetes-operator/managing-domains/domain-resource/#cluster-spec-elements",
           "type": "string"
         },
         "annotations": {

documentation/domains/Cluster.md

@@ -47,7 +47,7 @@ The specification of the operation of the WebLogic cluster. Required.
 | --- | --- | --- |
 | `annotations` | Map | The annotations to be added to generated resources. |
 | `labels` | Map | The labels to be added to generated resources. The label names must not start with "weblogic.". |
-| `sessionAffinity` | string | Supports "ClientIP" and "None". Used to maintain session affinity. Enable client IP based session affinity. Must be ClientIP or None. Defaults to None. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies |
+| `sessionAffinity` | string | Advanced setting to enable client IP based session affinity. Must be ClientIP or None. Defaults to None. More info: https://oracle.github.io/weblogic-kubernetes-operator/managing-domains/domain-resource/#cluster-spec-elements |
 
 ### Server Pod
 

kubernetes/crd/cluster-crd.yaml

@@ -5,7 +5,7 @@ apiVersion: apiextensions.k8s.io/v1
 kind: CustomResourceDefinition
 metadata:
   annotations:
-    weblogic.sha256: 6b6e7832ef6cdeef81d2c704a38636f9d1eb3b9c5fa76be64391d1939943003b
+    weblogic.sha256: 46ef88005b68d9fb13a122b63fece506c555770209221581cb056c15f1ac7e6a
   name: clusters.weblogic.oracle
 spec:
   group: weblogic.oracle
@@ -2868,9 +2868,9 @@ spec:
                 properties:
                   sessionAffinity:
                     default: None
-                    description: 'Supports "ClientIP" and "None". Used to maintain
-                      session affinity. Enable client IP based session affinity. Must
-                      be ClientIP or None. Defaults to None. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies'
+                    description: 'Advanced setting to enable client IP based session
+                      affinity. Must be ClientIP or None. Defaults to None. More info:
+                      https://oracle.github.io/weblogic-kubernetes-operator/managing-domains/domain-resource/#cluster-spec-elements'
                     type: string
                   annotations:
                     additionalProperties:

operator/src/main/java/oracle/kubernetes/weblogic/domain/model/ClusterService.java

@@ -14,9 +14,9 @@
 public class ClusterService extends KubernetesResource {
 
   @Description(
-      "Supports \"ClientIP\" and \"None\". Used to maintain session affinity. Enable client IP based session affinity. "
+      "Advanced setting to enable client IP based session affinity. "
           + "Must be ClientIP or None. Defaults to None. More info: "
-          + "https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies")
+          + "https://oracle.github.io/weblogic-kubernetes-operator/managing-domains/domain-resource/#cluster-spec-elements")
   @Default(strDefault = "None")
   private String sessionAffinity;