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]>
apache · Mar 14, 2024 · 3af6492 · 3af6492
1 parent cfa237a
commit 3af6492
Show file tree

Hide file tree

Showing 2 changed files with 68 additions and 9 deletions.
diff --git a/...rlessworkflow/modules/ROOT/pages/cloud/operator/build-and-deploy-workflows.adoc b/...rlessworkflow/modules/ROOT/pages/cloud/operator/build-and-deploy-workflows.adoc
@@ -20,27 +20,27 @@ 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
 
 [#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
@@ -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,17 +83,76 @@ 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.
 
 === Setting a custom image in devmode
 
 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.