From a376cf6240921a6c917da1478347c9498a6b9ef0 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Wed, 16 Oct 2024 16:00:33 +0000 Subject: [PATCH] Build .adoc Files for GitHub Pages from bdb7c3608274e2ebe3d29cb6d6bdc12cc9ebef0d --- .gitignore | 100 +++++ apis.html | 1000 +++++++++++++++++++++++++++++++++++++++++++ index.html | 482 +++++++++++++++++++++ user-guide.html | 1081 +++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 2663 insertions(+) create mode 100644 .gitignore create mode 100644 apis.html create mode 100644 index.html create mode 100644 user-guide.html diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..977ec0e2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,100 @@ +# tools for the development +/openapi-gen +/operator-sdk + +#envtest temporal files +testbin/* + +# dry-run folder, used to generate manifest for inspection +dry-run/* + +# Test binary, build with `go test -c` +*.test + +# Output of the go coverage tool, specifically when used with LiteIDE +cover.out + +# Auto generated files +bin/* + +# Created by https://www.gitignore.io/api/go,vim,emacs,visualstudiocode +### Emacs ### +# -*- mode: gitignore; -*- +*~ +\#*\# +/.emacs.desktop +/.emacs.desktop.lock +*.elc +auto-save-list +tramp +.\#* +# Org-mode +.org-id-locations +*_archive +# flymake-mode +*_flymake.* +# eshell files +/eshell/history +/eshell/lastdir +# elpa packages +/elpa/ +# reftex files +*.rel +# AUCTeX auto folder +/auto/ +# cask packages +.cask/ +dist/ +# Flycheck +flycheck_*.el +# server auth directory +/server/ +# projectiles files +.projectile +projectile-bookmarks.eld +# directory configuration +.dir-locals.el +# saveplace +places +# url cache +url/cache/ +# cedet +ede-projects.el +# smex +smex-items +# company-statistics +company-statistics-cache.el +# anaconda-mode +anaconda-mode/ +### Go ### +# Binaries for programs and plugins +*.exe +*.exe~ +*.dll +*.so +*.dylib +# Test binary, build with 'go test -c' +*.test +# Output of the go coverage tool, specifically when used with LiteIDE +*.out +### Vim ### +# swap +.sw[a-p] +.*.sw[a-p] +# session +Session.vim +# temporary +.netrwhist +# auto-generated tag files +tags +### VisualStudioCode ### +.vscode/* +.history +# End of https://www.gitignore.io/api/go,vim,emacs,visualstudiocode +## idea ## +.idea/ + +#bundle +bundle/ + +bundle.Dockerfile diff --git a/apis.html b/apis.html new file mode 100644 index 00000000..71106495 --- /dev/null +++ b/apis.html @@ -0,0 +1,1000 @@ + + + + + + + +WildFly Operator - API Documentation + + + + + +
+
+
+
+

This document describes the types introduced by the WildFly Operator to be consumed by users.

+
+
+
+
+

WildFlyServer

+
+
+

WildFlyServer defines a custom WildFly resource.

+
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescriptionSchemeRequired

metadata

Standard object’s metadata (more info)

metav1.ObjectMeta

false

spec

Specification of the desired behaviour of the WildFly deployment (more info)

WildFlyServerSpec

true

status

Most recent observed status of the WildFly deployment. Read-only. (more info)

WildFlyServerStatus

false

+
+
+
+

WildFlyServerList

+
+
+

WildFlyServerList defines a list of WildFly deployments

+
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescriptionSchemeRequired

metadata

Standard list’s metadata (more info)

metav1.ListMeta

false

items

List of WildFlyServer

[]WildFlyServer

true

+
+
+
+

WildFlyServerSpec

+
+
+

WildFlyServerSpec is a specification of the desired behavior of the WildFly resource.

+
+
+

It uses a StatefulSet with a pod spec that mounts the volume specified by storage on /opt/jboss/wildfly/standalone/data.

+
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescriptionSchemeRequired

applicationImage

Name of the application image to be deployed

string

true

bootableJar

BootableJar specifies whether the application image is using WildFly S2I Builder/Runtime images or Bootable Jar. If omitted, +it defaults to false (application image is expected to use WildFly S2I Builder/Runtime images)

bool

false

configMaps

List of ConfigMap names to mount as volumes in the containers. Each config map is mounted as a read-only volume under /etc/configmaps/<config map name>

string[]

false

deactivateTransactionRecovery

DeactivateTransactionRecovery disables the process of recoverying transactions (false if omitted)

bool

false

disableHTTPRoute

Disable the creation a route to the HTTP port of the application service (false if omitted)

bool

false

env

List of environment variable present in the containers

[]corev1.EnvVar

false

envFrom

List of environment variable present in the containers from source (either ConfigMap or Secret)

[]corev1.EnvFromSource

false

livenessProbe

Defines the periodic probe of container liveness. Container will be restarted if the probe fails

*ProbeSpec

false

readinessProbe

defines the periodic probe of container service readiness. Container will be removed from service endpoints if the probe fails

*ProbeSpec

false

replicas

Replicas is the desired number of replicas for the application

int32

true

resources

Resources spec to specify the request or limits of the Stateful Set. If omitted, the namespace defaults are used (more info).

*Resources

false

secrets

List of secret names to mount as volumes in the containers. Each secret is mounted as a read-only volume under /etc/secrets/<secret name>

string[]

false

securityContext

SecurityContext spec to define privilege and access control settings for the pod containers created by the Stateful set. If omitted default privileges are used (more info)

*corev1.SecurityContext

false

serviceAccountName

Name of the ServiceAccount to use to run the WildFlyServer Pods

string

false

sessionAffinity

If connections from the same client IP are passed to the same WildFlyServer instance/pod each time (false if omitted)

bool

false

standaloneConfigMap

spec to specify how standalone configuration can be read from a ConfigMap

*StandaloneConfigMapSpec

false

startupProbe

Indicates that the Pod has successfully initialized. If specified, no other probes are executed until this completes successfully. If this probe fails, the Pod will be restarted, just as if the livenessProbe failed. This can be used to provide different probe parameters at the beginning of a Pod’s lifecycle, when it might take a long time to load data or warm a cache, than during steady-state operation. Contrary to the livenessProbe and readinessProbe, the startupProbe will not be created by default unless it is explicitly configured.

*ProbeSpec

false

storage

Storage spec to specify how storage should be used. If omitted, an EmptyDir is used (that will not persist data across pod restart)

*StorageSpec

false

+
+
+
+

ProbeSpec

+
+
+

ProbeSpec describes a health check to be performed against a container to determine whether it is alive or ready to receive traffic. The Operator configures the exec/httpGet fields of the Probe. Notice these fields are not exposed to the user since they are an implementation detail that depends on the server image used to create the application image.

+
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescriptionSchemeRequired

ProbeHandler

Defines a specific action between Exec or HTTPGet action that should be taken in a probe. If Exec and HTTPGet handlers are both defined, the Operator will configure the Exec handler and will ignore the HTTPGet one.

*ProbeHandler

false

failureThreshold

Minimum consecutive failures for the probe to be considered failed after having succeeded. Defaults to 3. Minimum value is 1.

integer

false

initialDelaySeconds

Number of seconds after the container has started before probes are initiated. It defaults to 60 seconds for liveness probe. It defaults to 10 seconds for readiness probe. It defaults to 0 seconds for startup probe. Minimum value is 0.

integer

false

periodSeconds

How often (in seconds) to perform the probe. Default to 10 seconds. Minimum value is 1.

integer

false

successThreshold

Minimum consecutive successes for the probe to be considered successful after having failed. Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1.

integer

false

timeoutSeconds

Number of seconds after which the probe times out. Defaults to 1 second. Minimum value is 1.

integer

false

+
+
+
+

ProbeHandler

+
+
+

ProbeHandler defines a specific action between Exec or HTTPGet that should be taken in a probe. If Exec and HTTPGet handlers are both defined, the Operator will configure the Exec handler and will ignore the HTTPGet one.

+
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescriptionSchemeRequired

Exec

Specifies a command action to take.

ExecAction

false

HTTPGet

HTTPGet specifies the http request to perform.

HTTPGetAction

false

+
+
+
+

Resources

+
+
+

Resources defines the configured resources for a WildflyServer resource. If the Resources field is not defined or Request or Limits is empty, this resource is removed from the StatefulSet +The description of this resource is a standard Container resource and uses the scheme for corev1.ResourceRequirements.

+
+
+
+
+

StorageSpec

+
+
+

StorageSpec defines the configured storage for a WildFlyServer resource. If neither an emptyDir nor a volumeClaimTemplate is defined, +a default EmptyDir will be used.

+
+
+

The Operator will configure the StatefulSet using information from this StorageSpec to mount a volume dedicated to the standalone/data directory +used by WildFly to persist its own data (e.g. transaction log). If an EmptyDir is used, the data will not survive a pod restart. If the application deployed on WildFly relies on +transaction, make sure to specify a volumeClaimTemplate that so that the same persistent volume can be reused upon pod restarts.

+
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescriptionSchemeRequired

emptyDir

EmptyDirVolumeSource to be used by the WildFly StatefulSet

*corev1.EmptyDirVolumeSource

false

volumeClaimTemplate

A PersistentVolumeClaim spec to configure Resources requirements to store WildFly standalone data directory. The name of the template is derived from the WildFlyServer name. The corresponding volume will be mounted in ReadWriteOnce access mode.

corev1.PersistentVolumeClaim

false

+
+
+
+

StandaloneConfigMapSpec

+
+
+

StandaloneConfigMapSpec defines how WildFly standalone configuration can be read from a ConfigMap. If omitted, WildFly uses its standalone.xml configuration from its image.

+
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescriptionSchemeRequired

name

Name of the ConfigMap containing the standalone configuration XML file.

string

true

key

Key of the ConfigMap whose value is the standalone configuration XML file. If omitted, the spec will look for the standalone.xml key.

string

false

+
+
+
+

WildFlyServerStatus

+
+
+

WildFlyServerStatus is the most recent observed status of the WildFly deployment. Read-only.

+
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescriptionSchemeRequired

replicas

Replicas is the actual number of replicas for the application

int32

true

selector

selector for pods, used by HorizontalPodAutoscaler

string

false

hosts

Hosts that route to the application HTTP service

[]string

true

pods

Status of the pods

[]PodStatus

true

scalingdownPods

Number of pods which are under scale down cleaning process

int32

true

+
+
+
+

PodStatus

+
+
+

PodStatus is the most recent observed status of a pod running the WildFly application.

+
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescriptionSchemeRequired

name

Name of the Pod

string

true

podIP

IP address allocated to the pod

string

true

recoveryCounter

Counts the recovery attempts when there are in-doubt transactions

state

State of the pod from perspective of scale down process. By default it’s active which means it serves requests.

+
+
+
+ + + \ No newline at end of file diff --git a/index.html b/index.html new file mode 100644 index 00000000..1cf9f9d1 --- /dev/null +++ b/index.html @@ -0,0 +1,482 @@ + + + + + + + +WildFly Operator - Documentation + + + + + +
+
+

WildFly Operator for Kubernetes/OpenShift

+
+
+

The WildFly Operator for Kubernetes provides easy monitoring and configuration for Java applications deployed on WildFly application server using the Source-to-Image (S2I) template for WildFly.

+
+
+

Once installed, the WildFly Operator provides the following features:

+
+
+
    +
  • +

    Create/Destroy: Easily launch an application deployed on WildFly

    +
    • +
  • +

    Simple Configuration: Configure the fundamentals of WildFly-based application including number of nodes, application image, etc.

    +
    • +
+
+
+

The WildFly Operator defines a WildFlyServer custom resource definition (CRD) to control the behaviour of the deployed appliction. The API documentation provides a full description of its capabilities.

+
+
+

The User Guide showcases various features and capabilities provides by the WildFly Operator.

+
+
+
+
+ + + \ No newline at end of file diff --git a/user-guide.html b/user-guide.html new file mode 100644 index 00000000..a3d2e9b8 --- /dev/null +++ b/user-guide.html @@ -0,0 +1,1081 @@ + + + + + + + +WildFly Operator - User Documentation + + + + + +
+
+
+
+

This guide documents the various features and capabilities provides by the WildFly Operator.

+
+
+

This guide is complemented by the API Documentation.

+
+
+
+
+

Basic Install (Phase I)

+
+
+

The features and capabilities of Basic Install (Phase I) deals with the provisioning, installation and configuration of a Java application managed by the WildFly Operator.

+
+
+
+
+

Specify the Docker Application Image

+
+
+

The applicationImage specifies the Docker application image that contains the Java application. +The operator support two kind of application images:

+
+
+
    +
  • +

    WildFly S2I Builder/Runtime application image. This application image is built by using WildFly S2I. This is the default one.

    +
    • +
  • +

    Bootable Jar application image. This application image is built by using Bootable JAR

    +
    • +
+
+
+
Example of application image configuration
+
+
spec:
+  applicationImage: "quay.io/wildfly-quickstarts/wildfly-operator-quickstart:18.0"
+
+
+
+

The applicationImage accepts different references to Docker image:

+
+
+
    +
  • +

    the name of the image: quay.io/wildfly-quickstarts/wildfly-operator-quickstart

    +
    • +
  • +

    a tag: quay.io/wildfly-quickstarts/wildfly-operator-quickstart:18.0

    +
    • +
  • +

    a digest: quay.io/wildfly-quickstarts/wildfly-operator-quickstart@sha256:0af38bc38be93116b6a1d86a9c78bd14cd527121970899d719baf78e5dc7bfd2

    +
    • +
  • +

    an imagestream tag: wildfly-operator-quickstart:latest

    +
    • +
+
+
+ + + + + +
+
Note
+		 +
+

Using an imatestream tag is supported only on OpenShift and the imagestream must be in the same namespace that the deployed WildFlyServer resource. +The WildFly Operator will trigger new deployment of the application whenever the image corresponding to the imagestream tag changes.

+
+
+
+
+
+
+

Specify a Bootable JAR application image

+
+
+

The bootableJar specifies whether the application image is a Bootable JAR server. If this configuration is unspecified, the WildFly Operator assumes that the application image is an S2I image.

+
+
+
Example of Bootable JAR configuration
+
+
spec:
+  bootableJar: true
+
+
+
+

There are some restrictions about the base image you can use to launch the Bootable JAR:

+
+
+
    +
  • +

    The base image for the Bootable JAR container must be registry.access.redhat.com/ubi8/openjdk-11 or any other Red Hat ubi8 supplying a higher JDK version.

    +
    • +
  • +

    The Bootable JAR must be built for a server configured for the cloud environment. This is done by enabling the cloud configuration item on the wildfly-jar-maven-plugin configuration. See Configuring the server for cloud execution on the wildfly-jar-maven-plugin documentation.

    +
    • +
+
+
+
+
+

Specify the Size of the Application

+
+
+

The replicas specifies the size of the application, i.e. the number of pods that runs the application image.

+
+
+
Example of size configuration
+
+
spec:
+  replicas:2
+
+
+
+
+
+

Specify the Resource requirements for the container

+
+
+

The resources spec is defined in the Resources API Documentation.

+
+
+
Example of resources configuration
+
+
spec:
+  resources:
+    limits:
+      cpu: 500m
+      memory: 2Gi
+    requests:
+      cpu: 100m
+      memory: 1Gi
+
+
+
+

For more examples visit:

+
+
+ +
+
+
+
+

Specify the Storage Requirements for the Server Data Directory

+
+
+

The storage defines the storage requirements for WildFly’s own data. +The application may require persistent storage for some data (e.g. transaction or messaging logs) that must persist across Pod restarts.

+
+
+

If the storage spec is empty, an EmptyDir volume will be used by each pod of the application (but this volume will not persist after its corresponding pod is stopped).

+
+
+ + + + + +
+
Warning
+		 +
+

Using the EmptyDir is especially unsafe for XA transaction processing. +When the application uses the XA transactions then is required to configure the persistent volume claim (example below) +or configure the transaction subsystem to store transaction log in database with +use of JDBC store.

+
+
+
+
+

A volumeClaimTemplate can be specified to configure Resources requirements to store WildFly standalone data directory. +The name of the template is derived from the WildFlyServer name. The corresponding volume will be mounted in ReadWriteOnce access mode.

+
+
+

The storage spec is defined in the StorageSpec API Documentation.

+
+
+
Example of storage requirement
+
+
spec:
+  storage:
+    volumeClaimTemplate:
+      spec:
+        resources:
+          requests:
+            storage: 3Gi
+
+
+
+

The persistent volume that meets this storage requirement is mounted on the /wildfly/standalone/data directory (corresponding to WildFly’s jboss.server.data.dir path).

+
+
+
+
+

Configure the Application Environment

+
+
+

Environment can be configured using the env spec. +Environment variables can come directly from values (such as the POSTGRESQL_SERVICE_HOST example below) or from secrets (e.g. the POSTGRESQL_USER example below).

+
+
+
Example of environment configuration
+
+
spec:
+  env:
+  - name: POSTGRESQL_SERVICE_HOST
+    value: postgresql
+  - name: POSTGRESQL_SERVICE_PORT
+    value: '5432'
+  - name: POSTGRESQL_DATABASE
+    valueFrom:
+      secretKeyRef:
+        key: database-name
+        name: postgresql
+  - name: POSTGRESQL_USER
+    valueFrom:
+      secretKeyRef:
+        key: database-user
+        name: postgresql
+  - name: POSTGRESQL_PASSWORD
+    valueFrom:
+      secretKeyRef:
+        key: database-password
+        name: postgresql
+
+
+
+
+
+

Configure Secrets

+
+
+

Secrets can be mounted as volumes to be accessed from the application.

+
+
+

The secrets must be created before the WildFly Operator deploys the application. For example we can create a secret named my-secret with a command such as:

+
+
+
+
$ kubectl create secret generic my-secret --from-literal=my-key=devuser --from-literal=my-password='my-very-secure-pasword'
+
+
+
+

Once the secret has been created, we can specify its name in the WildFlyServer Spec to have it mounted as a volume in the pods running the application:

+
+
+
Example of mounting secrets
+
+
spec:
+  secrets:
+    - my-secret
+
+
+
+

The secrets will then be mounted under /etc/secrets/<secret name> and each key/value will be stored in a file (whose name is the key and the content is the value).

+
+
+
Secret is mounted as a volume inside the Pod
+
+
[jboss@quickstart-0 ~]$ ls /etc/secrets/my-secret/
+my-key  my-password
+[jboss@quickstart-0 ~]$ cat /etc/secrets/my-secret/my-key
+devuser
+[jboss@quickstart-0 ~]$ cat /etc/secrets/my-secret/my-password
+my-very-secure-pasword
+
+
+
+
+
+

Configure ConfigMaps

+
+
+

ConfigMaps can be mounted as volumes to be accessed from the application.

+
+
+

The config maps must be created before the WildFly Operator deploys the application. For example we can create a config map named my-config with a command such as:

+
+
+
+
$ kubectl create configmap my-config --from-literal=key1=value1 --from-literal=key2=value2
+configmap/my-config created
+
+
+
+

Once the config map has been created, we can specify its name in the WildFlyServer Spec to have it mounted as a volume in the pods running the application:

+
+
+
Example of mounting config maps
+
+
spec:
+  configMaps:
+  - my-config
+
+
+
+

The config maps will then be mounted under /etc/configmaps/<config map name> and each key/value will be stored in a file (whose name is the key and the content is the value).

+
+
+
Config Map is mounted as a volume inside the Pod
+
+
[jboss@quickstart-0 ~]$ ls /etc/configmaps/my-config/
+key1 key2
+[jboss@quickstart-0 ~]$ cat /etc/configmaps/my-config/key1
+value1
+[jboss@quickstart-0 ~]$ cat /etc/configmaps/my-config/key2
+value2
+
+
+
+
+
+

Bring Your Own Standalone XML Configuration

+
+
+

It is possible to directly provide WildFly standalone configuration instead of the one in the application image (that comes from WildFly S2I).

+
+
+

The standalone XML file must be put in a ConfigMap that is accessible by the operator. +The standaloneConfigMap must provide the name of this ConfigMap as well as the key corresponding to the name of standalone XML file.

+
+
+
Example of bringing its own standalone configuration
+
+
spec:
+  standaloneConfigMap:
+    name: clusterbench-config-map
+    key: standalone-openshift.xml
+
+
+
+

In this example, the clusterbench-config-map must be created before the WildFly Operator deploys the application.

+
+
+
Example of creating a ConfigMap from a standalone XML file
+
+
$ kubectl create configmap clusterbench-config-map --from-file examples/clustering/config/standalone-openshift.xml
+configmap/clusterbench-config-map created
+
+
+
+ + + + + +
+
Note
+		 +
+

This feature is not supported by a Bootable JAR application image. If you enabled it, your application image will not be deployed in the cluster.

+
+
+
+
+
+
+

Monitor WildFly Metrics

+
+
+

If the Prometheus Operator is deployed on the cluster (and the ServiceMonitor Custom Resource Definition is installed), the WildFly operator automatically creates a ServiceMonitor to expose its metrics to Prometheus.

+
+
+
+
+

OpenShift Features

+
+
+

Some Operator features are only available when running on OpenShift if Kubernetes does not provide the required resources to activate these features.

+
+
+

Seamless Upgrades

+
+

On OpenShift, it is possible to use an imagestream tag for the applicationImage to provide seamless upgrades.

+
+
+

The imagestream must be in the same namespace that the deployed WildFlyServer resource. +If that’s the case, the WildFly Operator will trigger new deployment of the application whenever the image corresponding to the imagestream tag changes.

+
+
+

This allows to take full advantage of the OpenShift ecosystem to build the image using BuildConfig in order to trigger new deployments when the code of the application changes (using WebHooks to trigger new builds and then new deployments) or when WildFly S2I images changes (which can also trigger new build).

+
+
+
+

Creation of an HTTP Route

+
+

By default, when the Operator runs on OpenShift, it creates an external route to the HTTP port of the Java application.

+
+
+

This route creation can be disabled by setting disableHTTPRoute to true if you do not wish to create an external route to the Java application.

+
+
+
Example to disable HTTP route
+
+
spec:
+  disableHTTPRoute: true
+
+
+
+
+
+
+

Transaction recovery during scaledown

+
+
+

As the application deployed in the WildFly application server +may use JTA transactions there and the question emerges: what does happen when the cluster is scaled down? +When the number of active WildFly replicas is decreased, still there may be some in-doubt transactions in the transaction log. +When the pod is removed then all the in-progress transactions are stopped and rolled back. +A more troublesome situation occurs when XA transactions are used. +When the XA transaction declares it’s prepared it’s a promise to finish the transaction successfully. +But the transaction manager which made this promise is running inside the WildFly server. +Then simply shutting down such pod may lead to data inconsistencies or data locks.

+
+
+

It must be ensured that all transactions are finished before the number of replicas is really decreased. +For that purpose, the WildFly Operator provides scale down functionality which verifies if all transactions were finished +and only then marks the pod as clean for termination.

+
+
+

Decreasing the replica size in the WildFlyServer customer resource is done at field WildFlyServer.Spec.Replicas (see Specify the Size of the Application). +You can use for example patch command like

+
+
+
+
oc patch wildflyserver <name> -p '[{"op":"replace", "path":"/spec/replicas", "value":0}]' --type json
+
+
+
+

or you can manually edit and change the replica number with oc edit wildflyserver <name>.

+
+
+ + + + + +
+
Note
+		 +Decreasing replica size at the StatefulSet or deleting the Pod itself has no effect and as such changes will be reverted. +
+
+
+ + + + + +
+
Warning
+		 +if you decide to delete whole WildflyServer definition (oc delete wildflyserver <deployment_name>) + then no transaction recovery process is started and the pod is terminated regardless of unfinished transactions. + If you want to remove the deployment in a safe way without data inconsistencies, + you need first to scale down the number of pods to 0, wait until all pods are terminated + and only after that you can delete the WildFlyServer instance +
+
+
+ + + + + +
+
Warning
+		 +Narayana recovery listener has to be enabled in the WildFly transaction subsystem. + Otherwise, scaledown transaction recovery processing is skipped for the particular WildFly pod. + See the recovery-listener attribute of the transaction subsystem. +
+
+
+

when the scaledown process begins the pod state (oc get pod <pod_name>`) is still marked as Running. +The reason is that the pod needs to be able to finish all the unfinished transactions and which includes the remote EJB calls that target it. +If you want to observe the state of the scaledown processing you need to observe the status of the WildFlyServer instance. +When running oc describe wildflyserver <name> you can see the status of the Pods.

+
+
+

The WildFlyServer.Status.Pods[].State can be one of the following values:

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status.Pod.StateDescription

ACTIVE

The pod is active and processing requests.

SCALING_DOWN_RECOVERY_INVESTIGATION

The pod is under investigation to find out if there are transactions that did not complete their lifecycle successfully.

SCALING_DOWN_RECOVERY_PROCESSING

There are in-doubt transactions in the log store. The pod cannot be terminated until these transactions are either completed or cleaned.

SCALING_DOWN_RECOVERY_HEURISTICS

There are heuristic transactions in the log store. The pod cannot be terminated until these transactions are either completed or cleaned.

SCALING_DOWN_CLEAN

The pod was processed by transaction scaled down processing and is marked as clean to be removed from the cluster.

+
+

For pods in the SCALING_DOWN_RECOVERY_PROCESSING status, each recovery cycle is tracked using the RecoveryCounter (accessible via WildFlyServer.Status.Pods[].RecoveryCounter). This field monitors the operator’s recovery attempts until all in-doubt transactions are successfully completed.

+
+
+

You can observe the overall state of the active and no-active pods by looking at the +WildFlyServer.Status.'Scalingdown Pods' and WildFlyServer.Status.Replicas fields. +The 'Scalingdown Pods' defines the number of pods which are about to be terminated when they are clean of unfinished transactions. +The Replicas defines the current number of running pods. +The WildFlyServer.Spec.Replicas (see Specify the Size of the Application) defines the desired number of the active pods. +If there are no pods in scaledown process the numbers of WildFlyServer.Status.Replicas and WildFlyServer.Spec.Replicas are equals.

+
+
+ + + + + +
+
Note
+		 +
+

This feature is not supported by a Bootable JAR application image. The transaction recovery facility will be ignored for Bootable JAR application images.

+
+
+
+
+ + + + + +
+
Warning
+		 +
+

It’s feasible to disable transaction recovery during scale-down by configuring the property WildFlyServerSpec.DeactivateTransactionRecovery to true (by default, it’s set to false). When DeactivateTransactionRecovery is enabled, in-doubt and heuristic transactions won’t be finalized or reported. +Consequently, this could lead to potential data inconsistency or loss when distributed transactions are employed.

+
+
+
+
+

Transaction scaledown special cases

+
+

Heuristics transactions

+
+

As it’s well-known the transaction may finish either with commit or roll-back. +Unfortunately there is a third outcome which is unknown. +It’s a state when there is no way of automatic transaction recovery and human intervention is needed. +If the transaction is in state of heuristics the pod is marked as SCALING_DOWN_RECOVERY_HEURISTICS +and the administrator needs to manually connect with the jboss-cli to the particular WildFly instance +and to resolve the heuristic transaction.

+
+
+

When all the formerly heuristics records are removed from the transaction object store then the operator +marks the pod as SCALING_DOWN_CLEAN and the pod is terminated.

+
+
+
+

SCALING_DOWN_CLEAN state and StatefulSet behaviour

+
+

There is a special case coming from the design of the StatefulSet that ensures that the network hostname is stable +(it does not change on the pod restart). The StatefulSet depends on ordering of the pods. The pod are named by the defined order. +The StatefulSet then requires the pod-0 not being terminated before the pod-1. First pod-1 is terminated and then pod-0.

+
+
+

From that rule we can observe that if the pod-1 is in state SCALING_DOWN_RECOVERY_HEURISTICS (e.g. contains some heuristic transactions) +then if pod-0 is in the state of SCALING_DOWN_CLEAN in will be lingering at that state until the pod-1 is terminated.

+
+
+

But even the pod is in state SCALING_DOWN_CLEAN the pod is not receiving any new requests +so it’s practically idle.

+
+
+
+
+
+
+ + + \ No newline at end of file