This is an automated email from the ASF dual-hosted git repository.
dhanak 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 3af649272 Add a note about profiles and configuration properties (#576)
3af649272 is described below
commit 3af6492727d1ce1517dcf0428760880ded8a8b50
Author: Ricardo Zanini <[email protected]>
AuthorDate: Thu Mar 14 10:37:24 2024 -0300
Add a note about profiles and configuration properties (#576)
* Add a note about profiles and configuration properties
Signed-off-by: Ricardo Zanini <[email protected]>
* Adjust writing to make it more clear
Signed-off-by: Ricardo Zanini <[email protected]>
* Adjust line highlight
Signed-off-by: Ricardo Zanini <[email protected]>
---------
Signed-off-by: Ricardo Zanini <[email protected]>
---
.../cloud/operator/build-and-deploy-workflows.adoc | 10 ++--
.../pages/cloud/operator/customize-podspec.adoc | 67 ++++++++++++++++++++--
2 files changed, 68 insertions(+), 9 deletions(-)
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 86244e13c..820a42ca4 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
@@ -20,13 +20,13 @@ This document describes how to build and deploy your
workflow on a cluster using
Every time you need to change the workflow definition the system will
(re)build a new immutable version of the workflow. If you're still in
development phase, please see the
xref:cloud/operator/developing-workflows.adoc[] guide.
-Follow the <<building-kubernetes, Kubernetes>> or <<building-openshift,
OpenShift>> sections of this document based on the cluster you wish to build
your workflows on.
-
[IMPORTANT]
====
-{operator_name} is under active development with features yet to be
implemented. Please see xref:cloud/operator/known-issues.adoc[].
+The build system implemented by the {operator_name} is not suitable for
complex production use cases. Consider using an external tool to build your
application such as Tekton and ArgoCD. The resulting image can then be deployed
with `SonataFlow` custom resource. See more at
xref:cloud/operator/customize-podspec.adoc#custom-image-default-container[Setting
a custom image in the default container] section in the
xref:cloud/operator/customize-podspec.adoc#custom-image-default-container[]
guide.
====
+Follow the <<building-kubernetes, Kubernetes>> or <<building-openshift,
OpenShift>> sections of this document based on the cluster you wish to build
your workflows on.
+
.Prerequisites
* A Workflow definition.
* The {operator_name} installed. See
xref:cloud/operator/install-serverless-operator.adoc[] guide
@@ -34,13 +34,13 @@ Follow the <<building-kubernetes, Kubernetes>> or
<<building-openshift, OpenShif
[#configure-build-system]
== Configuring the build system
-The operator can build workflows on Kubernetes or OpenShift. On Kubernetes, it
uses link:{kaniko_url}[Kaniko] and on OpenShift a
link:{openshift_build_url}[standard BuildConfig]. The operator build system is
not tailored for advanced use cases and you can do only a few customizations.
+The operator can build workflows on Kubernetes or OpenShift. On Kubernetes, it
uses link:{kaniko_url}[Kaniko] and on OpenShift a
link:{openshift_build_url}[standard BuildConfig]. The operator build system is
not tailored for advanced production use cases and you can do only a few
customizations.
=== Using another Workflow base builder image
If your scenario has strict policies for image usage, such as security or
hardening constraints, you can replace the default image used by the operator
to build the final workflow container image. Alternatively, you might want to
test a nightly build with a bug fix or a custom image containing your
customizations.
-By default, the operator will use the image distributed upstream to run the
workflows in the development profile. You can change this image by editing the
`SonataFlowPlatform` custom resource in the namespace where you deployed your
workflows:
+By default, the operator will use the image distributed upstream to build
workflows. You can change this image by editing the `SonataFlowPlatform` custom
resource in the namespace where you deployed your workflows:
.Patching the current SonataFlowPlatform with the new builder image
[source,bash,subs="attributes+"]
diff --git
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/customize-podspec.adoc
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/customize-podspec.adoc
index 87892969f..7ec73c4b3 100644
---
a/serverlessworkflow/modules/ROOT/pages/cloud/operator/customize-podspec.adoc
+++
b/serverlessworkflow/modules/ROOT/pages/cloud/operator/customize-podspec.adoc
@@ -64,7 +64,7 @@ Besides customizing the default container, you can add more
`containers`, `initC
| workflow-properties
| `ConfigMap`
| `/deployments/config/application.properties`,
`/deployments/config/application-prod.properties`
-| prod
+| preview
| workflow-properties
| `ConfigMap`
@@ -83,7 +83,66 @@ Besides customizing the default container, you can add more
`containers`, `initC
In dev profile, all the SonataFlow `.spec.resources` objects are mounted in
the `resources` projected volume listed in this table. Do not mount anything
else in this path.
====
-== Setting a custom image in the default container
+[#operator-profiles]
+== About {operator_name} Profiles
+
+Profiles are a way to change the runtime and deployment behavior of workflows.
You can change the `SonataFlow` custom resource profile using `annotations`.
For example:
+
+.Example of a SonataFlow CR with a profile annotation
+[source,yaml,subs="attributes+"]
+----
+apiVersion: sonataflow.org/v1alpha08
+kind: SonataFlow
+metadata:
+ name: simple
+ annotations:
+ sonataflow.org/profile: preview <1>
+ sonataflow.org/version: 0.0.1
+spec:
+ flow:
+ start: HelloWorld
+ states:
+ - name: HelloWorld
+ type: inject
+ data:
+ message: Hello World
+ end: true
+----
+
+<1> Preview profile defined in the `sonataflow.org/profile` annotation. This
is the default profile.
+
+The {operator_name} supports three different profiles:
+
+1. `dev`: The workflow will be deployed as a mutable container that will react
upon any changes on the `SonataFlow` custom resource immediatelly. Ideal for
scenarios where the flow definition is under active development and testing in
the cluster context. See xref:cloud/operator/developing-workflows.adoc[].
+2. `preview`: The operator will rely on an internal build system to build an
immutable container based on the flow definition. Every change to the
`SonataFlow` will kick a new build. Use this profile to evaluate the workflow
behavior in the cluster or if you have a simple use case where you don't need
any complex build customizations. See
xref:cloud/operator/build-and-deploy-workflows.adoc[]
+// TODO: missing tekton/argocd guide
https://issues.redhat.com/browse/KOGITO-7278
+3. `gitops`: Ideal for production use cases. This profile is automatically
defined by the operator when the `SonataFlow` CR is deployed with a custom
`.spec.podTemplate.container.image`. In this scenario, the user is responsible
to build the workflow application and provide the image to the operator.
+
+There's a correlation on the operator profile and the internal runtime
workflow Quarkus application. See the table below.
+
+.Correlation of the operator and Quarkus profiles
+[cols="1,1,2"]
+|===
+|Operator Profile | Quarkus Profile | Description
+
+| dev
+| dev
+| Suitable for testing only. The configuration file managed by the operator is
`application-dev.properties`
+
+| preview
+| prod
+| Suitable for quick evaluation and use of the internal builder system. The
configuration file managed by the operator is `application-prod.properties`
+
+| gitops
+| prod
+| Workflow image externally built by another system. The configuration file
managed by the operator is `application-prod.properties`
+
+|===
+
+For more information about configuring workflows see
xref:cloud/operator/configuring-workflows.adoc[].
+
+[#custom-image-default-container]
+=== Setting a custom image in the default container
When setting the attribute `.spec.podTemplate.container.image` the operator
understands that the workflow already have an image built and the user is
responsible for the build and image maintainence. That means that the operator
won't try to upgrade this image in the future or do any reconciliation changes
to it.
@@ -91,9 +150,9 @@ When setting the attribute
`.spec.podTemplate.container.image` the operator unde
In xref:cloud/operator/developing-workflows.adoc[development profile], it's
expected that the image is based on the default
`quay.io/kiegroup/kogito-swf-devmode:latest`.
-=== Setting a custom image in production
+=== Setting a custom image in preview
-When xref:cloud/operator/build-and-deploy-workflows.adoc[deploying in
production], you can opt in to have the operator to handle the build process
for you. However, in more complex scenarios it's expected that the user owns
and controls the build process. For this reason, when overriding the image the
operator won't build the workflow. The operator will try to deploy the workflow
using the given image.
+When xref:cloud/operator/build-and-deploy-workflows.adoc[building workflows],
you can opt in to have the operator to handle the build process for you.
However, in more complex scenarios it's expected that the user owns and
controls the build process. For this reason, when overriding the image the
operator won't build the workflow. The operator will try to deploy the workflow
using the given image.
In this scenario, the `.spec.resources` attribute is ignored since it's only
used during the build process in the production profile.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
