Skip to content

Latest commit

 

History

History
234 lines (167 loc) · 8.07 KB

CONTRIBUTING.md

File metadata and controls

234 lines (167 loc) · 8.07 KB
Raw

We love contributions!

How can I contribute?

There are many ways you can contribute to SonataFlow Operator, not only software development, as well as with the rest of Kogito community:

  • Contribute actively to development (see the section below)
  • Use it and report any feedback, improvement or bug you may find via Github, mailing list or chat.
  • Contribute by writing missing documentation or blog posts about the features around Kogito
  • Tweet, like and socialize Kogito in your preferred social network
  • Enjoy the talks that the contributors submit in various conferences around the world

Contributing to the SonataFlow Operator codebase

The main project is written in go. SonataFlow Operator is built on top of Kubernetes through Custom Resource Definitions.

  • Workflow
  • Platform
  • Build

This project aims to follow the Kubernetes Operator pattern

It uses Controllers which provides a reconcile function responsible for synchronizing resources untile the desired state is reached on the cluster

Contributing to the SonataFlow Operator

Prerequisites

The Operator's controllers and the configurations are generated using the Operator sdk, the tasks are executed using a Makefile.

More information about annotations can be found via the Kubebuilder Documentation

In order to build the project, you need to comply with the following requirements:

GNU Make: Used to define composite build actions. This should be already installed or available as a package (https://www.gnu.org/software/make/).

NOTE: Run make help for more information on all potential make targets

Getting Started

You’ll need a Kubernetes cluster to run against. You can use:

NOTE: Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster kubectl cluster-info shows).

IMPORTANT: Please make sure that your kubectl is version 1.24.0 or later since there's a bug performing validation on default attributes in Custom Resources.

Test It Out locally

You can launch the operator locally and bind to your cluster.

  1. Install the CRDs into the cluster:
make install
  1. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):
make run

NOTE: You can also run this in one step by running: make install run

NOTE: Run make help for more information on all potential make targets

More information can be found via the Kubebuilder Documentation

How-tos

Modifying the API definitions

If you are editing the API definitions, generate the manifests such as CRs or CRDs using:

make manifests

Building

make container-build

Deploy

make deploy

Undeploy

make undeploy

Change log level

By Default the log level is set to show only ERRORS with

- "--v=0"

inside the manager_auth_proxy_patch.yaml in the containers' section of kube-rbac-proxy and manager.

With the

make generate-all

whese values will be replicated on operator.yaml and on sonataflow-operator.clusterserviceversion.yaml containers' sections.

If you want to see the INFO msg replace v=0 with v=2 in the files during the development or in the deployment files on the cluster

The available levels are:

  • v=0 > Error
  • v=1 > Warning
  • v=2 >Info
  • v=3 > Debug

Running the operator on the cluster

See the section on README

Configuration

A configmap called sonataflow-operator-builder-config will be created under the sonataflow-operator-system namespace when the Operator will be installed, and it contains:

  • DEFAULT_BUILDER_RESOURCE = Dockerfile
  • DEFAULT_WORKFLOW_EXTENSION = .sw.json
  • Dockerfile = <dockerfile content>

Customize Builder Image

At the startup a Dockerfile is placed in a configmap. This Dockerfile uses a base image called kogito-swf-builder with:

  • openjdk 11+
  • maven 3.8.6+
  • a Quarkus project /home/kogito/serverless-workflow-project with those extensions:
    • quarkus-kubernetes
    • kogito-quarkus-serverless-workflow
    • kogito-addons-quarkus-knative-eventing
  • all the dependencies of Quarkus and the extensions stored in the /home/kogito/.m2 directory in the image.

There are, in the base image, some additional scripts in case of need to apply changes like this:

  • add other quarkus extensions in /home/kogito/launch/add-extension.sh
  • build the project after adding other files/java classes in /home/kogito/launch/build-app.sh
  • create a new project in /home/kogito/launch/create-app.sh

You can customize your final Image changing the Dockerfile in the configmap sonataflow-operator-builder-config accordingly to your specific needs.

Development status

General notes

Workflow CR

  • At the moment we are supporting only deployment of services on Kubernetes

Platform CR

  • The only tested features are the ones related to the docker Registry customization and so:
       apiVersion: sonataflow.org/v1alpha08
        kind: SonataFlowPlatform
        metadata:
            name: greeting-workflow-platform
        spec:
            platform:
                registry:
                    address: <docker registry repository> // the URI to access
                    secret: <name of the secret> // the secret where credentials are stored
                    insecure: true // if the container registry is insecure (ie, http only)
                    ca: <name of the config map> // the configmap which stores the Certificate Authority
                    organization: <name of the org> // the registry organization

Improvements

  • Introduce actions into Workflow and Build controller to improve code clarity
  • Add Trait to the Platform CR in order to be able to deploy on different context (i.e. KNative)
  • Test the Kaniko cache feature
  • Improve the workflow converters in order to support all the SonataFlow Workflow features

Tekton Pipeline to build and deploy the Operator

Setup a pipeline on a Openshift cluster.