This is an automated email from the ASF dual-hosted git repository.
ricardozanini pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-kie-kogito-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 332b7ffb4 Issue #560 - Introduce Global Configuration for Operator
section (#562)
332b7ffb4 is described below
commit 332b7ffb4900a62a5ce3bad42e62e2d2ed3148d8
Author: Ricardo Zanini <[email protected]>
AuthorDate: Mon Apr 1 16:23:42 2024 -0300
Issue #560 - Introduce Global Configuration for Operator section (#562)
---
serverlessworkflow/antora.yml | 1 +
serverlessworkflow/modules/ROOT/nav.adoc | 3 +-
.../modules/ROOT/pages/cloud/index.adoc | 9 ++
.../cloud/operator/build-and-deploy-workflows.adoc | 9 +-
.../cloud/operator/building-custom-images.adoc | 41 +---------
.../pages/cloud/operator/global-configuration.adoc | 95 ++++++++++++++++++++++
6 files changed, 116 insertions(+), 42 deletions(-)
diff --git a/serverlessworkflow/antora.yml b/serverlessworkflow/antora.yml
index fc79037ae..0df4f73ed 100644
--- a/serverlessworkflow/antora.yml
+++ b/serverlessworkflow/antora.yml
@@ -33,6 +33,7 @@ asciidoc:
product_name: SonataFlow
operator_name: SonataFlow Operator
operator_installation_namespace: sonataflow-operator-system
+ operator_controller_config: sonataflow-operator-controllers-config
quarkus_platform: io.quarkus.platform
kogito_sw_ga: kogito-quarkus-serverless-workflow
data_index_ref: Data Index
diff --git a/serverlessworkflow/modules/ROOT/nav.adoc
b/serverlessworkflow/modules/ROOT/nav.adoc
index d3e77ff8b..ac8e00001 100644
--- a/serverlessworkflow/modules/ROOT/nav.adoc
+++ b/serverlessworkflow/modules/ROOT/nav.adoc
@@ -70,9 +70,10 @@
* xref:cloud/index.adoc[Cloud]
** Operator
*** xref:cloud/operator/install-serverless-operator.adoc[Installation]
+*** xref:cloud/operator/global-configuration.adoc[Admin Configuration]
*** xref:cloud/operator/developing-workflows.adoc[Development Mode]
*** xref:cloud/operator/referencing-resource-files.adoc[Referencing Workflow
Resources]
-*** xref:cloud/operator/configuring-workflows.adoc[Configuration]
+*** xref:cloud/operator/configuring-workflows.adoc[Workflow Configuration]
*** xref:cloud/operator/build-and-deploy-workflows.adoc[Building and Deploying
Workflow Images]
*** xref:cloud/operator/supporting-services.adoc[Deploy Supporting Services]
*** xref:cloud/operator/workflow-status-conditions.adoc[Custom Resource Status]
diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/index.adoc
b/serverlessworkflow/modules/ROOT/pages/cloud/index.adoc
index 4780864ce..d1cf5c142 100644
--- a/serverlessworkflow/modules/ROOT/pages/cloud/index.adoc
+++ b/serverlessworkflow/modules/ROOT/pages/cloud/index.adoc
@@ -77,6 +77,15 @@ xref:cloud/operator/build-and-deploy-workflows.adoc[]
Learn how to build and deploy workflow services with {operator_name}
--
+
+[.card]
+--
+[.card-title]
+xref:cloud/operator/global-configuration.adoc[]
+[.card-description]
+Learn how to change global configuration options for the {operator_name}
+--
+
[.card]
--
[.card-title]
diff --git
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/build-and-deploy-workflows.adoc
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/build-and-deploy-workflows.adoc
index 077a76892..e0ff9b196 100644
---
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/build-and-deploy-workflows.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/build-and-deploy-workflows.adoc
@@ -49,6 +49,7 @@ By default, the operator will use the image distributed
upstream to build workfl
kubectl patch sonataflowplatform <name> --patch 'spec:\n build:\n
config:\n baseImage: <your new image full name with tag>' -n <your_namespace>
----
+[#customize-base-build]
=== Customize the base build Dockerfile
The operator uses the sonataflow-operator-builder-config `ConfigMap` in the
operator's installation namespace ({operator_installation_namespace}) to
configure and run the workflow build process.
@@ -59,7 +60,6 @@ You can change the `Dockerfile` entry in this `ConfigMap` to
tailor the Dockerfi
----
apiVersion: v1
data:
- DEFAULT_BUILDER_RESOURCE_NAME: Dockerfile
DEFAULT_WORKFLOW_EXTENSION: .sw.json
Dockerfile: "FROM quay.io/kiegroup/kogito-swf-builder-nightly:latest AS
builder\n\n#
variables that can be overridden by the builder\n# To add a Quarkus
extension
@@ -414,13 +414,14 @@ You don't need to do anything to build on OpenShift since
the operator will conf
In general, the operator will create a
link:{openshift_build_url}[`BuildConfig` to build] the workflow using the
mapped xref:cloud/operator/referencing-resource-files.adoc[resource files] and
your workflow definition. After the build is finished, the image will be pushed
to the internal OpenShift registry backed by an `ImageStream` object.
+[#changing-base-builder]
=== Changing the base builder image
If you are running on OpenShift, you have access to the Red Hat's supported
registry. You can change the default builder image by editing the
sonataflow-operator-builder-config `ConfigMap`.
[source,bash,subs="attributes+"]
----
-oc edit cm/sonataflow-operator-builder-config -n
{operator_installation_namespace}
+kubectl edit cm/sonataflow-operator-builder-config -n
{operator_installation_namespace}
----
In your editor, change the first line in the `Dockerfile` entry where it reads
`FROM quay.io/kiegroup/kogito-swf-builder-nightly:latest` to the desired image.
@@ -570,7 +571,7 @@ Ideally you should use this feature if there's a problem
with your workflow or t
== Additional resources
-* xref:cloud/operator/known-issues.adoc[]
-* xref:cloud/operator/developing-workflows.adoc[]
+* xref:cloud/operator/build-and-deploy-workflows.adoc[]
+* xref:cloud/operator/building-custom-images.adoc[]
include::../../../pages/_common-content/report-issue.adoc[]
diff --git
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/building-custom-images.adoc
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/building-custom-images.adoc
index ad2cdc8ba..f0b849349 100644
---
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/building-custom-images.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/building-custom-images.adoc
@@ -4,7 +4,7 @@
:description: Building custom development images for SonataFlow
:keywords: sonataflow, workflow, serverless, operator, kubernetes, minikube,
devmode
// Links:
-:rh_ubi8_url:
https://catalog.redhat.com/software/containers/ubi8/ubi-minimal/5c359a62bed8bd75a2c3fba8
+:rh_jdk17_url:
https://catalog.redhat.com/software/containers/ubi9/openjdk-17/61ee7c26ed74b2ffb22b07f6
// NOTE: this guide can be expanded in the future to include prod images,
hence the file name
// please change the title section and rearrange the others once it's
done
@@ -13,42 +13,9 @@ This document describes how to build a custom development
image to use in Sonata
== The development mode image structure
-The development image is based on the link:{rh_ubi8_url}[Red Hat UBI 8
minimal] container image. You can read its documentation for more detailed
information about that image's architecture.
+The development image is based on the link:{rh_jdk17_url}[Red Hat OpenJDK 17
UBI 9] container image. You can read its documentation for more detailed
information about that image's architecture.
-The table below lists the additional packages installed in the development
mode container image.
-
-.List of packages
-[cols="1,2"]
-|===
-|Package | Description
-
-|shadow-utils
-|The shadow-utils package includes the necessary programs for converting UNIX
password files to the shadow password format.
-
-|tar
-|
-
-|gzip
-|
-
-|unzip
-|
-
-|zip
-|
-
-|tzdata-java
-|
-
-|java-17-openjdk-devel
-|OpenJDK 17
-
-|apache-maven-3.9.3-bin.tar.gz
-|Apache Maven
-
-|===
-
-The next table lists the important paths in the container image's file system.
+The table bellow lists the important paths in the container image's file
system.
.Important file system paths
[cols="1,1"]
@@ -135,4 +102,4 @@ Finally, to use the new generated image with the dev
profile you can see: xref:c
* xref:cloud/operator/referencing-resource-files.adoc[]
* xref:cloud/operator/developing-workflows.adoc[]
-include::../../../pages/_common-content/report-issue.adoc[]
\ No newline at end of file
+include::../../../pages/_common-content/report-issue.adoc[]
diff --git
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/global-configuration.adoc
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/global-configuration.adoc
new file mode 100644
index 000000000..4bf338fd1
--- /dev/null
+++
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/global-configuration.adoc
@@ -0,0 +1,95 @@
+= Global Configuration Settings
+:compat-mode!:
+// Metadata:
+:description: Global Configuration {operator_name} for cluster admins
+:keywords: sonataflow, workflow, serverless, operator, kubernetes, minikube,
openshift, containers, configuration
+// links
+
+This document describes how to set global configuration options for the
{operator_name}.
+
+.Prerequisites
+* You have installed the operator in the target cluster. You can find more
information at the xref:cloud/operator/install-serverless-operator.adoc[] guide.
+
+== Modifying configuration options
+
+After installing the operator, you can access the ConfigMap named
`{operator_controller_config}` in the namespace
`{operator_installation_namespace}`.
+This configuration file governs the operator's behavior when creating new
resources in the cluster. Existing resources won't be changed after this
configuration.
+See the section <<config-changes>> for more information.
+
+You can freely edit any of the options in the key `controllers_cfg.yaml`
entry. The table bellow lists each possible entry.
+
+.Description of Global Configuration
+[cols="1,1,2"]
+|===
+|Configuration Key | Default Value | Description
+
+| `defaultPvcKanikoSize` | 1Gi | The default size of Kaniko PVC when using the
internal operator builder manager.
+| `healthFailureThresholdDevMode` | 50 | How much time (in seconds) to wait
for a devmode workflow to start. This information is used for the controller
manager to create new devmode containers and setup the healthcheck probes.
+| `kanikoDefaultWarmerImageTag` | gcr.io/kaniko-project/warmer:v1.9.0 |
Default image used internally by the Operator Managed Kaniko builder to create
the warmup pods.
+| `kanikoExecutorImageTag` | gcr.io/kaniko-project/executor:v1.9.0 | Default
image used internally by the Operator Managed Kaniko builder to create the
executor pods.
+| `jobsServicePostgreSQLImageTag` | empty | The Jobs Service image for
PostgreSQL to use, if empty the operator will use the default Apache Community
one based on the current operator's version.
+| `jobsServiceEphemeralImageTag` | empty | The Jobs Service image without
persistence to use, if empty the operator will use the default Apache Community
one based on the current operator's version.
+| `dataIndexPostgreSQLImageTag` | empty | The Data Index image for PostgreSQL
to use, if empty the operator will use the default Apache Community one based
on the current operator's version.
+| `dataIndexEphemeralTag` | empty | The Data Index image without persistence
to use, if empty the operator will use the default Apache Community one based
on the current operator's version.
+| `sonataFlowBaseBuilderImageTag` | empty | {product_name} base builder image
used in the internal Dockerfile to build workflow applications in preview
profile. If empty the operator will use the default Apache Community one based
on the current operator's version.
+| `sonataFlowDevModeImageTag` | empty | The image to use to deploy
{product_name} workflow images in devmode profile. If empty the operator will
use the default Apache Community one based on the current operator's version.
+
+|===
+
+To edit this file, update the ConfigMap
`sonataflow-operator-controllers-config` using your preferred tool such as
`kubectl`.
+
+[#config-changes]
+== Configuration Changes Impact
+
+When updating the global configuration, the changes will be taken impact
immediately for *newly* created resources only.
+For example, if you change `sonataFlowDevModeImageTag` property, given that
you already have a workflow deployed in _devmode_, the operator won't rollout a
new one with the new image configuration. Only new deployments will be affected.
+
+== A Note About the Base Builder Image
+
+As noted in
xref:cloud/operator/build-and-deploy-workflows.adoc#changing-base-builder[Changing
Base Builder] section, you can directly change the base builder image in the
Dockerfile used by the {operator_name}.
+
+Additionally, you can also change the base builder image in the
`SonataFlowPlatform` in the current namespace:
+
+.Example of SonataFlowPlatform with a custom base builder
+[source,yaml,subs="attributes+"]
+----
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlowPlatform
+metadata:
+ name: sonataflow-platform
+spec:
+ build:
+ config:
+ baseImage: dev.local/my-workflow-builder:1.0.0
+----
+
+And finally, you can also change this information directly in the global
confinguration ConfigMap
+
+.Example of ConfigMap global configuration with a custom base builder
+[source,yaml,subs="attributes+"]
+----
+apiVersion: v1
+data:
+ controllers_cfg.yaml: |
+ sonataFlowBaseBuilderImageTag: dev.local/my-workflow-builder:1.0.0
+kind: ConfigMap
+metadata:
+ name: sonataflow-operator-controllers-config
+ namespace: sonataflow-operator-system
+----
+
+The order of precedence is:
+
+1. The `SonataFlowPlatform` in the current context
+2. The global configuration entry
+3. The `FROM` clause in the Dockerfile in the operator's namespace
`sonataflow-operator-builder-config` ConfigMap
+
+In summary, the entry in `SonataFlowPlatform` will always override any other
value.
+
+== Additional resources
+
+* xref:cloud/operator/known-issues.adoc[]
+* xref:cloud/operator/developing-workflows.adoc[]
+* xref:cloud/operator/global-configuration.adoc[]
+
+include::../../../pages/_common-content/report-issue.adoc[]
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
