Deploying your Serverless Workflow application on Minikube

This document describes how to deploy your workflow application using a local Kubernetes cluster, such as Minikube, along with a procedure to run the Knative platform.

For more information about Minikube and related system requirements, see Getting started with Minikube documentation.

Prerequisites

To deploy your workflow application on Minikube, you need to install Knative on Minikube. However, first you need to ensure that Minikube is installed correctly.

You can check the Minikube installation by entering the following commands in a command terminal:

Verify Minikube version
minikube version
Verify Knative CLI version
kn version
Verify kubectl CLI version
kubectl version

If kubectl is not installed, then Minikube handles it when you execute the following command:

kubectl is available using Minikube
alias kubectl="minikube kubectl --"

Installing Knative on Minikube

Once you verify the Minikube and Knative CLI installation, you can install Knative on Minikube.

Prerequisites
Procedure
  1. Open a command terminal and install Knative on Minikube.

  2. Configure Knative on Minikube.

    Knative CLI offers quickstart plug-in, which provides the required configurations. For information about installing the quickstart plug-in, see Install Knative using quickstart.

  3. After configuring the plug-in, execute the following command to configure a Minikube profile:

    Configure a Minikube profile
    kn quickstart minikube

    The previous command configures a Minikube profile called knative. After creating a Minikube profile, all Minikube commands use the created profile.

  4. To list the available Minikube profiles, enter the following command:

    List the available Minikube profiles
    minikube profile list
  5. Enter the following command to open the Minikube web console on the knative profile:

    Open Minikube web console
    minikube dashboard --profile knative

    The previous command opens the Kubernetes Management console in your browser. If the console is not opened, you can go to the URL that is returned.

To follow the manual process of installing Knative on Minikube, see Knative tutorial on Minikube.

Deploying your workflow application on Minikube

Once you install Knative on Minikube, you can initiate the process of deploying your workflow application on Minikube.

Prerequisites
Procedure
  1. In a command terminal, enter the following command to configure Docker to use the in-cluster Docker daemon:

    Configure Docker to use in-cluster Docker Daemon
    eval $(minikube -p minikube docker-env --profile knative)
  2. Build your application to store it in the Minikube registry.

    If your workflow application container image is built before configuring Docker to use the in-cluster Docker daemon, then you might need to build the image again so that the image is available in the Minikube registry.

    If you are building native container images, ensure that you use the following system property to use Minikube Docker Daemon:

    System property to build container images
    -Dquarkus.native.remote-container-build=true

    You might be required to tag the container images using one of the following registry:

    • ko.local

    • dev.local

    For more information, see How to use locally built docker image.

    In that case, use the -Dquarkus.container-image.registry=some_of_the_values_above property to enable Knative fetch the container images from Minikube Docker Daemon.

    If you do not use the values, you might need to set the imagePullPolicy to Never or IfNotPresent, otherwise, Minikube pulls the images from a remote registry. This behavior can be avoided by tagging the image using previously listed domains.

  3. In a separate command terminal window, start the Minikube tunnel using the Knative profile to prepare the environment:

    Start Minikube tunnel using Knative profile
    minikube tunnel --profile knative

    The previous command starts in a loop. Therefore, this command must be running throughout the process mentioned in this document. On Mac and Windows, you might be required to provide the user password.

    Example tunnel output
    Status:
    	machine: knative
    	pid: 124859
    	route: 10.96.0.0/12 -> 192.168.58.2
    	minikube: Running
    	services: [kourier]
        errors:
    		minikube: no errors
    		router: no errors
    		loadbalancer emulator: no errors
  4. After starting the Minikube tunnel, create serverless-workflow-greeting-quarkus namespace using the following command:

    Create namespace
    kubectl create namespace serverless-workflow-greeting-quarkus
  5. Set the context to the newly created namespace using the following command:

    Set context to a namespace
    kubectl config set-context --current --namespace=serverless-workflow-greeting-quarkus

    After setting the context, all Minikube commands use the created namespace. You can use the following command to verify the current namespace:

    Verify the current namespace
    kubectl config view --minify -o jsonpath='{..namespace}'
  6. Deploy your workflow application using the Minikube registry.

    The next step is to deploy your workflow application to execute it. You can see the further sections for different procedures to deploy your workflow application.

    You can use the native image due to the faster startup.
    For more information about installing the workflow application, see Building workflow images using Quarkus CLI document.

In the following procedures, you can find two examples of deploying your workflow application, including:

  • Using Knative CLI (kn)

  • Using kubectl command-line tool

Deploying your workflow application using Knative CLI

Once you have installed your workflow application into the Minikube registry, you can use the command-line tools, such as Knative CLI or kubectl to initiate the deployment process.

Prerequisites
Procedure
  1. In a command terminal, execute the following command to deploy your workflow application using Knative CLI:

    Example of deploying workflow application using Knative CLI
    kn service create hello \
        --image=dev.local/kogito/serverless-workflow-greeting-quarkus:1.0 \
        --pull-policy=IfNotPresent \
        --port 8080
    Example output
    Creating service 'hello' in namespace 'serverless-workflow-greeting-quarkus':
    
      0.066s The Route is still working to reflect the latest desired specification.
      0.099s ...
      0.322s Configuration "hello" is waiting for a Revision to become ready.
      4.885s ...
      5.061s Ingress has not yet been reconciled.
      5.322s Waiting for load balancer to be ready
      5.460s Ready to serve.
    
    Service 'hello' created to latest revision 'hello-00001' is available at URL:
    http://hello.serverless-workflow-greeting-quarkus.10.103.94.37.sslip.io
  2. Use the URL in the output to send request to your workflow application.

    Example request
    curl -X POST -H 'Content-Type:application/json' -H 'Accept:application/json' -d '{"workflowdata" : {"name": "John", "language": "English"}}' http://hello.serverless-workflow-greeting-quarkus.10.103.94.37.sslip.io/jsongreet
    Example response
    {"id":"0f77abce-837e-4bd2-b4f1-a0e5e0265fcb","workflowdata":{"name":"John","language":"English","greeting":"Hello from JSON Workflow, "}}

Deploying your workflow application using kubectl

You can also use kubectl command-line interface and plain Kubernetes objects to deploy your workflow application.
And, instead of creating knative yaml|json descriptors, you can leverage the Quarkus Kubernetes extension and Kogito Knative add-on to generate the descriptors.

Prerequisites
  • Workflow application is installed.

  • kubectl command-line tool is installed.

  • (Optional) Quarkus CLI is installed
    For more information about installing the Quarkus CLI, see Installing the Quarkus CLI.

Procedure
  1. Add the Quarkus extensions to generate knative yaml|json descriptors.

    To use the Quarkus Kubernetes extension and Kogito Knative add-on, ensure that the following dependencies are available in pom.xml file and Gradle:

    • pom.xml

    • Gradle

    <dependency>
      <groupId>org.kie.kogito</groupId>
      <artifactId>kogito-addons-quarkus-knative-eventing</artifactId>
    </dependency>
    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-kubernetes</artifactId>
    </dependency>
    quarkus-kubernetes 'io.quarkus:quarkus-kubernetes:2.7.6.Final'
    quarkus-kubernetes 'org.kie.kogito:kogito-addons-quarkus-knative-eventing:1.27.0.Final'
  2. To generate the knative yaml|json descriptors, set the following properties in the application.properties file of your workflow application:

    System properties to generate knative descriptors
    quarkus.kubernetes.deployment-target=knative
    quarkus.knative.name=greeting-quarkus-kubectl
  3. Build your workflow application.

    Once you have built your application, you can find the generated descriptors files in the target/kubernetes directory:

    • knative.json

    • knative.yml

    Following is an example of the generated files:

    Knative descriptor example for a workflow application
    ---
    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      annotations:
        app.quarkus.io/commit-id: 06c3fe8e2dfc42e2211cbcc41224f5a3d6bd1f26
        app.quarkus.io/build-timestamp: 2022-06-23 - 23:53:38 +0000
      labels:
        app.kubernetes.io/name: greeting-quarkus-kubectl
      name: greeting-quarkus-kubectl
    spec:
      template:
        metadata:
          labels:
            app.kubernetes.io/name: greeting-quarkus-kubectl
        spec:
          containerConcurrency: 0
          containers:
            - image: dev.local/kogito/serverless-workflow-greeting-quarkus:1.0-native
              livenessProbe:
                failureThreshold: 3
                httpGet:
                  path: /q/health/live
                  port: null
                  scheme: HTTP
                initialDelaySeconds: 0
                periodSeconds: 30
                successThreshold: 1
                timeoutSeconds: 10
              name: greeting-quarkus-kubectl
              ports:
                - containerPort: 8080
                  name: http1
                  protocol: TCP
              readinessProbe:
                failureThreshold: 3
                httpGet:
                  path: /q/health/ready
                  port: null
                  scheme: HTTP
                initialDelaySeconds: 0
                periodSeconds: 30
                successThreshold: 1
                timeoutSeconds: 10

    Once the files are generated, you might be required to add the imagePullPolicy manually before deploying the workflow application.

    Some of the system properties are not working properly due to a bug in decorate API. For more information about the bug, see Quarkus issue.

    There is a small bug on the 'Decorate API' where some system properties are not taking effect, for more information take a look at this Quarkus issue. After the file generation, you might be required to add the imagePullPolicy manually before deploying it.

  4. Enter the following command to deploy the workflow application using kubectl:

    Deploy the workflow application using kubectl
    kubectl apply -f target/kubernetes/knative.yml
  5. Verify if the workflow application is deployed correctly using the following command:

    • On kubectl

    • On Knative CLI

    kubectl get services.serving.knative.dev greeting-quarkus-kubectl
    kn service list
    Example output
    NAME                       URL                                                                                          LATESTCREATED                    LATESTREADY                      READY   REASON
    greeting-quarkus-kubectl   http://greeting-quarkus-kubectl.serverless-workflow-greeting-quarkus.10.103.94.37.sslip.io   greeting-quarkus-kubectl-00001   greeting-quarkus-kubectl-00001   True
  6. Access the workflow application using the listed URL in the output.

    Access workflow application
    curl -X POST -H 'Content-Type:application/json' -H 'Accept:application/json' -d '{"workflowdata" : {"name": "John", "language": "English"}}' http://greeting-quarkus-kubectl.serverless-workflow-greeting-quarkus.10.103.94.37.sslip.io/jsongreet

Deploying your workflow application using Quarkus CLI

Prerequisites
Procedure
  1. Add the Quarkus extensions to deploy the knative service

    You can simply add the kubernetes and the Kogito knative extension to your project with the Quarkus CLI:

    Add kubernetes and Kogito knative extensions to the project with Quarkus CLI
    quarkus extension add kubernetes
    quarkus extension add kogito-addons-quarkus-knative-eventing
  2. To deploy your workflow application using Quarkus CLI, set the following system properties in application.properties file:

    Required system properties
    quarkus.knative.name=greeting-quarkus-cli (1)
    quarkus.kubernetes.deployment-target=knative (2)
    quarkus.kubernetes.deploy=true (3)
    quarkus.container-image.push=false (4)
    1 Property for the Knative resource name
    2 Property to set whether or not deploy on an active Kubernetes cluster
    3 Property to whether or not push images when using Minikube’s remove Docker daemon to avoid image validation

    This functionality works with Quarkus 2.10.2.Final or later. For more information, see link.

  3. Verify if your workflow application is deployed correctly:

    • On kubectl

    • On Knative CLI

    kubectl get services.serving.knative.dev greeting-quarkus-cli
    kn service list greeting-quarkus-cli
    Example output
    NAME                   URL                                                                                      LATEST                       AGE    CONDITIONS   READY   REASON
    greeting-quarkus-cli   http://greeting-quarkus-cli.serverless-workflow-greeting-quarkus.10.103.94.37.sslip.io   greeting-quarkus-cli-00001   7m6s   3 OK / 3     True
  4. You can access your workflow application using the listed URL in the output.

    Access your workflow application
    curl -X POST -H 'Content-Type:application/json' -H 'Accept:application/json' -d '{"workflowdata" : {"name": "John", "language": "English"}}' http://greeting-quarkus-cli.serverless-workflow-greeting-quarkus.10.103.94.37.sslip.io/jsongreet.37.sslip.io/jsongreet

Found an issue?

If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!