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 dd544327185f2f0d6a13464d1041a66e3d054ab0 Author: Ricardo Zanini <[email protected]> AuthorDate: Tue Apr 1 18:56:43 2025 -0300 Fix #709 - Adding Maven Mirror configuration guide to docs (#710) * Fix #709 - Adding Maven Mirror configuration guide to docs Signed-off-by: Ricardo Zanini <[email protected]> * Fixing IMPORTANT code block Signed-off-by: Ricardo Zanini <[email protected]> * Adding missing information to restart a build; replace envs to env Signed-off-by: Ricardo Zanini <[email protected]> --------- Signed-off-by: Ricardo Zanini <[email protected]> --- serverlessworkflow/modules/ROOT/nav.adoc | 18 +-- .../modules/ROOT/pages/cloud/config-maven.adoc | 126 +++++++++++++++++++++ .../cloud/operator/build-and-deploy-workflows.adoc | 6 + .../pages/cloud/operator/developing-workflows.adoc | 8 +- 4 files changed, 146 insertions(+), 12 deletions(-) diff --git a/serverlessworkflow/modules/ROOT/nav.adoc b/serverlessworkflow/modules/ROOT/nav.adoc index d705e0ede..2410b7922 100644 --- a/serverlessworkflow/modules/ROOT/nav.adoc +++ b/serverlessworkflow/modules/ROOT/nav.adoc @@ -47,17 +47,20 @@ * xref:cloud/index.adoc[Cloud] ** xref:cloud/custom-ingress-authz.adoc[Securing Workflows] ** xref:cloud/deploying-sonataflow-management-console-on-kubernetes.adoc[Deploying Management Console on Kubernetes] +** xref:cloud/config-maven.adoc[Configuring Maven] ** 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[Workflow Configuration] -*** xref:cloud/operator/build-and-deploy-workflows.adoc[Building and Deploying Workflow Images] +*** Deployment Model +**** xref:cloud/operator/developing-workflows.adoc[Development Profile] +**** xref:cloud/operator/build-and-deploy-workflows.adoc[Preview Profile] +**** xref:cloud/operator/building-custom-images.adoc[Building Custom Dev Images] +**** 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] +**** xref:cloud/operator/add-custom-ca-to-a-workflow-pod.adoc[Add Custom CA to Workflow Pod] +**** xref:cloud/operator/workflow-status-conditions.adoc[Custom Resource Status] *** xref:cloud/operator/supporting-services.adoc[Deploy Supporting Services] -*** xref:cloud/operator/workflow-status-conditions.adoc[Custom Resource Status] -*** xref:cloud/operator/building-custom-images.adoc[Building Custom Images] -*** xref:cloud/operator/customize-podspec.adoc[Custom Workflow PodSpec] *** xref:cloud/operator/service-discovery.adoc[Service Discovery] *** xref:cloud/operator/using-persistence.adoc[Workflow Persistence] *** xref:cloud/operator/configuring-workflow-eventing-system.adoc[Workflow Eventing System] @@ -65,7 +68,6 @@ **** xref:cloud/operator/monitoring-workflows.adoc[Workflow Monitoring] **** xref:cloud/operator/sonataflow-metrics.adoc[Prometheus Metrics for Workflows] *** xref:cloud/operator/known-issues.adoc[Roadmap and Known Issues] -*** xref:cloud/operator/add-custom-ca-to-a-workflow-pod.adoc[Add Custom CA to Workflow Pod] * Service Orchestration ** xref:service-orchestration/orchestration-of-openapi-based-services.adoc[OpenAPI] *** xref:service-orchestration/configuring-openapi-services-endpoints.adoc[Advanced Configuration] diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/config-maven.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/config-maven.adoc new file mode 100644 index 000000000..8cce2d326 --- /dev/null +++ b/serverlessworkflow/modules/ROOT/pages/cloud/config-maven.adoc @@ -0,0 +1,126 @@ +// Note: This section can grow over time to add more Maven-related configuration and guides += Adding a custom Maven Mirror to {product_name} images +:compat-mode!: +// Metadata: +:description: Adding a custom maven mirror to images +:keywords: maven, mirror, central, sonatype +// links +:maven_mirror_guide: https://maven.apache.org/guides/mini/guide-mirror-settings.html + +This document describes how to configure the internal Maven settings on {product_name} images so that the maven process can access a custom mirror registry. + +By default either the {product_name} Builder and Devmode images have all the required Java libraries to run. In some scenarios, such as adding a custom Quarkus Extension, the internal system will require to +access the Maven Central registry. + +In case you are running under restricted network access, you may point the container to access an internal mirror instead. See more information about this procedure on the link:{maven_mirror_guide}[Guide to Mirror Settings] on the Maven documentation. + +== Configuring the Maven Mirror on the Operator + +=== Adding a Maven Mirror when building workflows + +You may edit either the `SonataFlowBuild` or `SonataFlowPlatform` custom resources and add the variable `MAVEN_MIRROR_URL`. + +.Maven Mirror configuration example on SonataFlowBuild +[source,yaml,subs="attributes+"] +---- +apiVersion: sonataflow.org/v1alpha08 +kind: SonataFlowBuild +metadata: + name: my-workflow + annotations: + sonataflow.org/restartBuild: true <1> +spec: + # supreessed for brevity + envs: + - name: MAVEN_MIRROR_URL <2> + value: http://my.company.registry.local +---- + +1. Annotation to force the existing build to trigger a new execution +2. The environment variable required to configure the maven URL + +Changing the `SonataFlowBuild` it will only impact the given workflow instance it represents. In this case, a workflow instance in the same namespace with the name `my-workflow`. + +For more information about restarting the build see xref:cloud/operator/build-and-deploy-workflows.adoc#restarting-build[Restarting a Build]. + +To change the Maven mirror for all build instances for the `preview` profile, you have to change the given `SonataFlowPlatform` within the same namespace. + +.Maven Mirror configuration example on SonataFlowPlatform +[source,yaml,subs="attributes+"] +---- +apiVersion: sonataflow.org/v1alpha08 +kind: SonataFlowPlatform +metadata: + name: my-platform +spec: + build: + template: + envs: + - name: MAVEN_MIRROR_URL <1> + value: http://my.company.registry.local +---- + +1. The environment variable required to configure the maven URL + +When a workflow builder instance runs, it will use this information to configure the internal Maven settings file to use this URL as the default mirror to external locations, such as the Maven Central repository. + +For more information about building workflows with the operator see xref:cloud/operator/build-and-deploy-workflows.adoc[]. + +=== Adding a Maven Mirror when deploying on Development Mode + +When deploying workflows in `devmode`, you may also add the Maven Mirror to the `SonataFlow` custom resource. + +.Maven Mirror configuration example on SonataFlow +[source,yaml,subs="attributes+"] +---- +apiVersion: sonataflow.org/v1alpha08 +kind: SonataFlow +metadata: + name: greeting + annotations: + sonataflow.org/description: Greeting example on k8s! + sonataflow.org/version: 0.0.1 + sonataflow.org/profile: dev +spec: + podTemplate: + container: + env: + - name: MAVEN_MIRROR_URL <1> + value: http://my.company.registry.local + flow: #supreessed for brevity +---- + +1. The environment variable required to configure the maven URL + +[IMPORTANT] +==== +Only workflows deployed with `dev` profile can use Maven Mirrors. Other deployment models only execute compiled code which won't need to connect to a Maven registry to run. +==== + +To know more about running workflows in development mode, see xref:cloud/operator/developing-workflows.adoc[]. + +== Configuring the Maven Mirror on a custom image + +When building workflows in an external system using the {product_name} Builder image, you may set this environment variable preferrebly in your build context. Alternatively, you may also set it in your custom container file. + +.Custom Container File with Maven Mirror set as an environment variable +[source,Dockerfile,subs="attributes+"] +---- +FROM {sonataflow_builder_imagename}:{operator_version} AS builder + +# Content supressed for brevity + +# The Maven Mirror URL set as an env var during the build process. +ENV MAVEN_MIRROR_URL=http://my.company.registry.local +---- + +.Custom Container File with Maven Mirror set as an argument +[source,Dockerfile,subs="attributes+"] +---- +FROM {sonataflow_builder_imagename}:{operator_version} AS builder + +# Content supressed for brevity + +# The Maven Mirror URL will be passed as an argument to the build process. +ARG MAVEN_MIRROR_URL +---- 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 da974dc5f..62beefb2a 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 @@ -18,6 +18,11 @@ This document describes how to build and deploy your workflow on a cluster using the link:{kogito_serverless_operator_url}[{operator_name}]. +[TIP] +==== +The {operator_name} supports three distinct deployment models known as profiles: `devmode`, `preview`, and `gitops`. This document describes the `preview` profile. +==== + 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. [IMPORTANT] @@ -552,6 +557,7 @@ If everything is working, you should receive a response like this: {"id":"b5fbfaa3-b125-4e6c-9311-fe5a3577efdd","workflowdata":{"name":"John","language":"English","greeting":"Hello from JSON Workflow, "}} ---- +[[restarting-build]] == Restarting a build If you require to restart the build for some reason, you can add or edit the annotation `sonataflow.org/restartBuild: true` in the `SonataFlowBuild` instance. diff --git a/serverlessworkflow/modules/ROOT/pages/cloud/operator/developing-workflows.adoc b/serverlessworkflow/modules/ROOT/pages/cloud/operator/developing-workflows.adoc index f232d49c0..ec0dfca39 100644 --- a/serverlessworkflow/modules/ROOT/pages/cloud/operator/developing-workflows.adoc +++ b/serverlessworkflow/modules/ROOT/pages/cloud/operator/developing-workflows.adoc @@ -9,13 +9,13 @@ This document describes how you can develop your Workflows directly on Kubernetes with the {operator_name}. -Workflows in the development profile are not tailored for production environments. To build and deploy an immutable Workflow with the operator, see xref:cloud/operator/build-and-deploy-workflows.adoc[]. - -[IMPORTANT] +[TIP] ==== -{operator_name} is under active development with features yet to be implemented. Please see xref:cloud/operator/known-issues.adoc[]. +The {operator_name} supports three distinct deployment models known as profiles: `devmode`, `preview`, and `gitops`. This document describes the `devmode` profile. ==== +Workflows in the development profile are not tailored for production environments. To build and deploy an immutable Workflow with the operator, see xref:cloud/operator/build-and-deploy-workflows.adoc[]. + .Prerequisites * You have set up your environment according to the xref:getting-started/preparing-environment.adoc#proc-minimal-local-environment-setup[minimal environment setup] guide. * You have the cluster instance up and running. See xref:getting-started/preparing-environment.adoc#proc-starting-cluster-fo-local-development[starting the cluster for local development] guide. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
