This is an automated email from the ASF dual-hosted git repository. dhanak pushed a commit to branch 10.1.x in repository https://gitbox.apache.org/repos/asf/incubator-kie-kogito-docs.git
commit 20f6f6738d9ddada5ec39fec477c3238676df2e6 Author: Ricardo Zanini <[email protected]> AuthorDate: Tue May 13 04:05:49 2025 -0300 Fix #720 - Add gitops profile section; summarize deployment model (#721) * Fix #720 - Add gitops profile section; summarize deployment model Signed-off-by: Ricardo Zanini <[email protected]> * Update serverlessworkflow/modules/ROOT/pages/cloud/operator/gitops-profile.adoc Co-authored-by: Dominik Hanák <[email protected]> * Added Walter's comments Co-authored-by: Walter Medvedeo <[email protected]> * Add markers in the code snippet. Co-authored-by: Walter Medvedeo <[email protected]> * Refactor customize-podspec to remove deployment profile details Signed-off-by: Ricardo Zanini <[email protected]> * Fix metadata domain name Signed-off-by: Ricardo Zanini <[email protected]> * Incorporate dominik's review Co-authored-by: Dominik Hanák <[email protected]> * Fix newlines Signed-off-by: Ricardo Zanini <[email protected]> --------- Signed-off-by: Ricardo Zanini <[email protected]> Co-authored-by: Dominik Hanák <[email protected]> Co-authored-by: Walter Medvedeo <[email protected]> --- serverlessworkflow/modules/ROOT/nav.adoc | 5 +- .../pages/cloud/operator/customize-podspec.adoc | 205 +++++++-------------- .../pages/cloud/operator/deployment-profile.adoc | 149 +++++++++++++++ .../ROOT/pages/cloud/operator/gitops-profile.adoc | 140 ++++++++++++++ 4 files changed, 357 insertions(+), 142 deletions(-) diff --git a/serverlessworkflow/modules/ROOT/nav.adoc b/serverlessworkflow/modules/ROOT/nav.adoc index 2410b7922..e8179d647 100644 --- a/serverlessworkflow/modules/ROOT/nav.adoc +++ b/serverlessworkflow/modules/ROOT/nav.adoc @@ -51,10 +51,11 @@ ** Operator *** xref:cloud/operator/install-serverless-operator.adoc[Installation] *** xref:cloud/operator/global-configuration.adoc[Admin Configuration] -*** Deployment Model +*** xref:cloud/operator/deployment-profile.adoc[Deployment Profiles] **** xref:cloud/operator/developing-workflows.adoc[Development Profile] +***** xref:cloud/operator/building-custom-images.adoc[Building Custom Dev Images] **** xref:cloud/operator/build-and-deploy-workflows.adoc[Preview Profile] -**** xref:cloud/operator/building-custom-images.adoc[Building Custom Dev Images] +**** xref:cloud/operator/gitops-profile.adoc[GitOps Profile] **** xref:cloud/operator/configuring-workflows.adoc[Workflow Configuration] **** xref:cloud/operator/referencing-resource-files.adoc[Referencing Workflow Resources] **** xref:cloud/operator/customize-podspec.adoc[Custom Workflow PodSpec] diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/customize-podspec.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/customize-podspec.adoc index 568dfa600..a403c774c 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/operator/customize-podspec.adoc +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/customize-podspec.adoc @@ -11,100 +11,92 @@ :knative_serving_initcontainer: https://knative.dev/docs/serving/configuration/feature-flags/#kubernetes-init-containers :kubernetes_init_containers: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/ -This document describes how to customize the pod specification definition in the `SonataFlow` custom resource. +This document describes how to customize the pod specification (`PodSpec`) in a SonataFlow custom resource to meet runtime requirements in Kubernetes and OpenShift, such as adding volumes, setting resource limits, or using a custom container image. -Sometimes you may have a specific requirement to deploy containers on Kubernetes or OpenShift such as setting link:{k8s_resources_limits_url}[Resource Limits]. +If you're looking to understand how the operator builds and manages workflow lifecycles (e.g., live updates or immutable builds), refer to xref:cloud/operator/deployment-profile.adoc[Deployment Profiles]. -{operator_name} enables custom link:{k8s_podspec_api_url}[PodSpec] definitions when deploying a `SonataFlow` instance by setting the `.spec.podTemplate` attribute. For example: +== Overview + +The `.spec.podTemplate` attribute allows you to define a custom link:{k8s_podspec_api_url}[PodSpec] for the deployed workflow instance. This enables fine-grained control over how the workflow runs inside the container. + +Use `.spec.podTemplate.container` to customize the default workflow container (named `workflow`). This field is not part of the standard PodSpec, but was introduced by the operator to simplify configuration. + +== Example: Setting Resource Limits -.Setting PodSpec Resources Limits example [source,yaml,subs="attributes+"] ---- -apiVersion: sonataflow.org/v1alpha08 -kind: SonataFlow -metadata: - name: simple - annotations: - sonataflow.org/description: Simple example on k8s! - sonataflow.org/version: 0.0.1 spec: - podTemplate: <1> - container: <2> - resources: <3> + podTemplate: + container: + resources: limits: cpu: "250m" memory: "128Mi" - flow: - start: HelloWorld - states: - - name: HelloWorld - type: inject - data: - message: Hello World - end: true ---- -<1> The `PodSpec` template definition -<2> The default workflow service container -<3> Resources configuration +== Customizing the Workflow Container + +You can customize the workflow container via `.spec.podTemplate.container` with fields like: + +- `resources` +- `image` +- `env` +- `command` and `args` + +Avoid using the main `containers` array to redefine the `workflow` container — the operator will ignore conflicting names. -The `.spec.podTemplate` attribute has the majority of fields defined in the default link:{k8s_podspec_api_url}[Kubernetes PodSpec API]. The same Kubernetes API validation rules applies to these fields. +== Adding Additional Containers and Volumes -The `.spec.podTemplate.container` is a special attribute that you won't find in the default Kubernetes API. The reason is to avoid misconfiguration when users require to change the specific container where the workflow application is deployed. +You may add: + +- `containers` (sidecars) +- `initContainers` +- `volumes` +- `volumeMounts` (on sidecars or initContainers) + +[IMPORTANT] +==== +You cannot override volumes or mount paths controlled by the operator. See <<customization-exceptions>>. +==== +[[deployment-model]] == Deployment Model -By default, the {operator_name} deploys a `SonataFlow` instance in a regular Kubernetes Deployment object. Although it's possible to change this behavior and deploy the workflow instance as a link:{knative_serving_service_url}[Knative Serving Service] instead. +By default, the SonataFlow Operator deploys workflow instances using a standard Kubernetes `Deployment`. You can opt into using a serverless model via Knative Serving. -To change the deployment to Knative, set the `.spec.podTemplate.deploymentModel` attribute to `knative`. For example: +To enable Knative deployment: -.Setting PodSpec Resources Limits example -[source,yaml,subs="attributes+"] +[source,yaml] ---- -apiVersion: sonataflow.org/v1alpha08 -kind: SonataFlow -metadata: - name: simple - annotations: - sonataflow.org/description: Simple example on k8s! - sonataflow.org/version: 0.0.1 - sonataflow.org/version: preview spec: - podTemplate: + podTemplate: deploymentModel: knative <1> - flow: - start: HelloWorld - states: - - name: HelloWorld - type: inject - data: - message: Hello World - end: true ---- -<1> The `deploymentModel` attribute +<1> Valid values: `kubernetes` (default), `knative` -After changing the deployment model to `knative`, the `SonataFlow` instance will be deployed as a Knative Serving Service. +After enabling this option, the workflow will be deployed as a Knative `Service`. [IMPORTANT] ==== -It's not possible to deploy a `SonataFlow` instance as a Knative Service in dev profile. In this profile, this attribute is ignored by the operator. +The `deploymentModel: knative` is only honored in the `preview` and `gitops` profiles. It is ignored when using the `dev` profile. ==== -Note that not every use case leverage a Knative deployment. Long-running workflow instances, for example, that calls services that might take too long to respond, might not be an ideal deployment model. Opt to use Knative deployments for workflows that won't take too long to run. - -The exception are workflows that have callback states. In this case, you must configure xref:cloud/operator/using-persistence.adoc[persistence]. This is required because once the workflow waits for the event to resume the execution, Knative will kill the pod. Since the workflow has persistence, it will resume the execution once it receives the callback event. +Use Knative when: +- You need scale-to-zero or autoscaling based on HTTP traffic. +- The workflow is short-lived or event-driven. +- You have persistence enabled for workflows with callbacks or long waits. -Knative **does not support** link:{kubernetes_init_containers}[`initContainers`] by default. If your workflow requires it, you must first enable the extension in the Knative installation. See more information on the link:{knative_serving_initcontainer}[Knative documentation]. +See: +- xref:cloud/operator/deployment-profile.adoc[Deployment Profiles] +- xref:cloud/operator/using-persistence.adoc[] +- link:{knative_serving_initcontainer}[Knative InitContainer support] +[#customization-exceptions] == Customization Exceptions -Besides customizing the default container, you can add more `containers`, `initContainers`, or `volumes` to the pod. There are a few exceptions listed below: +Some paths and volumes are managed by the operator and **must not be overridden**: -1. The `containers` array can't have a container named `workflow`. If you set a container with this name, it will be ignored by the operator. Instead, use `.spec.podTemplate.container` to modify the workflow container. -2. There are a few file system paths controlled by the operator within the container where it mounts important files. These volumes can't be overrided, it will be ignored by the operatror. See the table below: -+ -.List of immutable volumes [cols="1,1,2,1"] |=== |Volume | Type | Path | Profile @@ -116,7 +108,7 @@ Besides customizing the default container, you can add more `containers`, `initC | workflow-properties | `ConfigMap` -| `$\{PROJECT_ROOT\}/src/main/resources/application.properties`, `$\{PROJECT_ROOT\}/src/main/resources/application-dev.properties` +| `$\{PROJECT_ROOT\}/src/main/resources/application.properties`, `application-dev.properties` | dev | resources @@ -128,98 +120,31 @@ Besides customizing the default container, you can add more `containers`, `initC [IMPORTANT] ==== -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. +In the `dev` profile, all `.spec.resources` are mounted in the `resources` projected volume. Avoid mounting anything else at that path. ==== -[#operator-profiles] -== About {operator_name} Profiles +== Using a Custom Image -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: +You may override the workflow container image using: -.Example of a SonataFlow CR with a profile annotation -[source,yaml,subs="attributes+"] +[source,yaml] ---- -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 + podTemplate: + container: + image: quay.io/myorg/myworkflow:latest ---- -<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` +When this is set, the operator assumes you're using the **gitops** deployment profile and won't attempt to build or update the image automatically. -| 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 `{sonataflow_devmode_imagename}:{operator_version}`. - -=== Setting a custom image in preview - -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. - -[IMPORTANT] -==== -xref:cloud/operator/known-issues.adoc[In the roadmap] you will find that we plan to consider the `.spec.resources` attribute when the image is specified in the default container. -==== - -It's advised that the SonataFlow `.spec.flow` definition and the workflow built within the image corresponds to the same workflow. If these definitions don't match you may experience poor management and configuration. The {operator_name} uses the `.spec.flow` attribute to configure the application, service discovery, and service binding with other deployments within the topology. - -[IMPORTANT] -==== -xref:cloud/operator/known-issues.adoc[It's on the roadmap] to add integrity check to the built images provided to the operator by customizing the default container. -==== +For more information, see xref:cloud/operator/deployment-profile.adoc#custom-image-default-container[]. -== Additional resources +== Additional Resources +* xref:cloud/operator/deployment-profile.adoc[] * xref:cloud/operator/developing-workflows.adoc[] * xref:cloud/operator/build-and-deploy-workflows.adoc[] * xref:cloud/operator/building-custom-images.adoc[] +* xref:cloud/operator/using-persistence.adoc[] include::../../../pages/_common-content/report-issue.adoc[] \ No newline at end of file diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/deployment-profile.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/deployment-profile.adoc new file mode 100644 index 000000000..a7664a009 --- /dev/null +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/deployment-profile.adoc @@ -0,0 +1,149 @@ += Deployment Profiles +:compat-mode!: +// Metadata: +:description: Overview of deployment profiles for SonataFlow workflows +:keywords: sonataflow, workflow, serverless, operator, kubernetes, gitops, devmode, preview + +This document introduces the three deployment profiles supported by the {product_name} Operator—`dev`, `preview`, and `gitops`. These profiles influence how the operator builds and manages workflow deployments, especially regarding image lifecycle, live updates, and reconciliation behavior. + +[NOTE] +==== +Deployment *profiles* define how the workflow is built and managed by the operator. + +If you're looking to customize how the workflow is deployed as a Kubernetes Deployment or a Knative Service, see xref:cloud/operator/customize-podspec.adoc#deployment-model[Deployment Model]. +==== + +[#gitops-profile] +== GitOps Profile + +The `gitops` profile provides full control over workflow images. In this model, you build your workflow container externally (e.g., CI/CD pipeline) and specify the image in the SonataFlow custom resource: + +[source,yaml] +---- +spec: + podTemplate: + container: + image: quay.io/acme/myworkflow:latest +---- + +When this field is set, the operator automatically assumes the `gitops` profile and will not build or mutate the image. + +Use this profile when: + +* You want full control over the build process +* You need to satisfy production requirements like auditability, security, and compliance +* You're integrating SonataFlow into existing GitOps-based workflows (e.g., ArgoCD, Tekton) + +xref:cloud/operator/gitops-profile.adoc[Read more about the GitOps Profile]. + +[#preview-profile] +== Preview Profile + +The `preview` profile lets the operator handle workflow builds using an internal build pipeline. Any changes to the `.spec.flow` will trigger a rebuild and a new immutable container image. + +This profile is ideal for: + +* Pre-production staging and demonstration environments +* Quick validation of workflow logic without managing the build pipeline + +Key characteristics: + +* The operator uses `application-prod.properties` +* Images are automatically built and managed +* Supports setting `deploymentModel: knative` (see xref:cloud/operator/customize-podspec.adoc#deployment-model[Deployment Models]) + +xref:cloud/operator/build-and-deploy-workflows.adoc[Read more about the Preview Profile]. + +[#dev-profile] +== Development Profile + +The `dev` profile supports rapid iteration and live updates directly from the cluster. Changes to the custom resource take effect almost immediately without triggering a new container image build. + +This profile is ideal for: + +* Live development and testing of workflows +* Quick iterations without a build process +* Extending workflows using the base developer image + +Key characteristics: + +* Uses `application-dev.properties` +* Automatically reloads the flow without rebuilding the container +* The image must be based on `{sonataflow_devmode_imagename}:{operator_version}` + +xref:cloud/operator/developing-workflows.adoc[Read more about the Development Profile]. + +[#choosing-profile] +== Choosing the Right Profile + +[cols="1,1", options="header"] +|=== +|Use Case |Profile + +|Full control of build and deployment +|`gitops` + +|Internal automated build and deploy +|`preview` + +|Fast iteration during development +|`dev` +|=== + + +== Switching Between Profiles + +To select a deployment profile, annotate your SonataFlow custom resource: + +[source,yaml] +---- +metadata: + annotations: + sonataflow.org/profile: preview +---- + +Valid values: `dev`, `preview`, `gitops`. + +NOTE: Setting `.spec.podTemplate.container.image` will override this annotation and automatically activate the `gitops` profile. + +== Profile Implications for Customization + +Your selected profile impacts how the operator treats certain configuration aspects: + +[cols="1,1,1,1,1", options="header"] +|=== +|Profile |Image Build |Reconciliation |`.spec.resources` |Supports Knative + +|`dev` +|Live reload +|Auto-updates +|Mounted in dev volume +|❌ Ignored + +|`preview` +|Internal build +|Rebuilt on change +|Used during build +|✅ + +|`gitops` +|User-supplied +|No rebuild +|Ignored +|✅ +|=== + + +[NOTE] +==== +For pod-level customization, including using `initContainers`, setting resource limits, and configuring deployment model (`knative` vs. `kubernetes`), see xref:cloud/operator/customize-podspec.adoc[]. +==== + +== Related Topics + +* xref:cloud/operator/customize-podspec.adoc[Customize the PodSpec Definition] +* 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/gitops-profile.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/gitops-profile.adoc new file mode 100644 index 000000000..d770dfed9 --- /dev/null +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/gitops-profile.adoc @@ -0,0 +1,140 @@ += GitOps Profile +:compat-mode!: +// Metadata: +:description: Using GitOps profile for deploying SonataFlow workflows in production environments +:keywords: sonataflow, workflow, serverless, operator, kubernetes, gitops, cicd +// Links: +:rh_jdk17_url: https://catalog.redhat.com/software/containers/ubi9/openjdk-17/61ee7c26ed74b2ffb22b07f6 + +This document describes how to use the GitOps profile for deploying {product_name} workflows in production environments. + +== Recommended for Production + +Using the GitOps profile is recommended for production environments. It provides complete control over workflow image builds, enabling compliance, security, and seamless integration into your existing CI/CD pipelines. + +== Workflow Image Structure + +The GitOps profile uses container images based on the link:{rh_jdk17_url}[Red Hat OpenJDK 17 UBI 9] runtime. You can review its documentation for detailed information about the image architecture. + +The table below highlights important paths in the container image file system. + +.Important file system paths +[cols="1,1"] +|=== +|Path | Description + +|`/deployments` +|Application deployment directory containing Quarkus application components + +|`/deployments/lib` +|Directory for application libraries + +|`/deployments/app` +|Directory for application-specific resources + +|`/deployments/quarkus` +|Quarkus-specific configuration files + +|=== + +== Building Workflow Container Images + +Below is an example Dockerfile illustrating how to build a container image using the GitOps profile. + +.Example Dockerfile +[source,dockerfile,subs="attributes+"] +---- +FROM {sonataflow_builder_imagename}:{operator_version} AS builder <1> + +ARG QUARKUS_EXTENSIONS +ARG QUARKUS_ADD_EXTENSION_ARGS +ARG MAVEN_ARGS_APPEND + +COPY --chown=1001 . ./resources <2> + +RUN /home/kogito/launch/build-app.sh ./resources <3> + +FROM registry.access.redhat.com/ubi9/openjdk-17-runtime:latest <4> + +ENV LANG='en_US.UTF-8' LANGUAGE='en_US:en' + +COPY --from=builder --chown=185 /home/kogito/serverless-workflow-project/target/quarkus-app/lib/ /deployments/lib/ <5> +COPY --from=builder --chown=185 /home/kogito/serverless-workflow-project/target/quarkus-app/*.jar /deployments/ +COPY --from=builder --chown=185 /home/kogito/serverless-workflow-project/target/quarkus-app/app/ /deployments/app/ +COPY --from=builder --chown=185 /home/kogito/serverless-workflow-project/target/quarkus-app/quarkus/ /deployments/quarkus/ + +EXPOSE 8080 +USER 185 +ENV AB_JOLOKIA_OFF="" +ENV JAVA_OPTS="-Dquarkus.http.host=0.0.0.0 -Djava.util.logging.manager=org.jboss.logmanager.LogManager" +ENV JAVA_APP_JAR="/deployments/quarkus-run.jar" +---- + +<1> Base builder image +<2> Copy workflow resources +<3> Build the workflow application +<4> Base runtime image +<5> Copy built application components to deployment directories + +.Procedure +. Ensure that your current directory contains the `Dockerfile` and `workflow.sw.yaml` you want to build. +[source,bash] ++ +---- +ls +# Example Output +workflow.sw.yaml Dockerfile +---- +. Execute the container build, by running following command: +[source,bash] ++ +---- +docker build -t your-registry/my-workflow . +---- + +== Pushing to Container Registry + +Push the built container image to your registry: + +[source,shell] +---- +docker push your-registry/my-workflow:tag +---- + +== Deploying the Workflow + +Configure your SonataFlow Custom Resource to use the built container image: + +[source,yaml] +---- +apiVersion: sonataflow.org/v1alpha08 +kind: SonataFlow +metadata: + annotations: + sonataflow.org/profile: gitops + name: my-workflow +spec: + flow: # Your workflow as in the *.sw.json or *.sw.yaml file that was used to build the image + podTemplate: + container: + image: your-registry/my-workflow:tag +---- + +Apply your custom resource to deploy: + +[source,shell] +---- +kubectl apply -f my-workflow.yaml +---- + +[IMPORTANT] +==== +Ensure that the `.spec.flow` definition matches the workflow definition used when building the application, as the {product_name} operator matches the flow definition with the provided workflow files during deployment. +==== + +== Additional resources + +* xref:cloud/operator/referencing-resource-files.adoc[] +* xref:cloud/operator/customize-podspec.adoc[] + +include::../../../pages/_common-content/report-issue.adoc[] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
