From 332b7ffb4900a62a5ce3bad42e62e2d2ed3148d8 Mon Sep 17 00:00:00 2001 From: Ricardo Zanini <1538000+ricardozanini@users.noreply.github.com> Date: Mon, 1 Apr 2024 16:23:42 -0300 Subject: [PATCH] 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 ++ .../operator/build-and-deploy-workflows.adoc | 9 +- .../operator/building-custom-images.adoc | 41 +------- .../cloud/operator/global-configuration.adoc | 95 +++++++++++++++++++ 6 files changed, 116 insertions(+), 42 deletions(-) create mode 100644 serverlessworkflow/modules/ROOT/pages/cloud/operator/global-configuration.adoc 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 --patch 'spec:\n build:\n config:\n baseImage: ' -n ---- +[#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 <> 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