Skip to main content
This guide provides a detailed explanation of deploying a Business Process Automation (jBPM/Kogito) application to Kubernetes, with step-by-step instructions and automation scripts.

Architecture Overview

The architecture consists of these core components:
  1. Process Service: A Quarkus application running jBPM/Kogito business processes
  2. PostgreSQL Database: Persistent storage for process instances, tasks, and audit data
  3. Management Console: Web UI for process instance monitoring and management
  4. Keycloak: Authentication and authorization server
Each component runs in its own pod but is connected through Kubernetes services and configured with proper environment variables.

Prerequisites

  • Kubernetes cluster (1.30+)
  • kubectl (version compatible with your cluster)
  • Private Docker registry or access to Docker Hub
  • Keycloak server (already running)
  • Maven 3.9.6+
  • JDK 17
  • Bash shell

Project Structure

The project consists of:
  • A jBPM/Kogito-based business process service built with Aletyx Enterprise Build of Kogito and Drools
  • PostgreSQL database for persistence
  • Management Console for process instance monitoring and task management

Configuration

Kubernetes Secret Configuration

The secrets provide secure access to your Docker registry and database credentials:
  • Registry Credentials Secret: Enables pods to pull images from your private registry
  • PostgreSQL Credentials Secret: Stores database credentials securely
The generic type creates a standard secret. Each --from-literal pair becomes a key-value entry in the secret.

Application Properties

The application.properties file configures the Quarkus application with all necessary settings:
  • HTTP Configuration: Sets up basic HTTP server properties and CORS
  • Database Connection: Configures the connection to PostgreSQL
  • Kogito-specific Settings: Configures process engine behavior
  • Authentication: Sets up Keycloak integration (even if disabled initially)
  • Kubernetes Deployment: Configures how the application is deployed
Key settings explained:

Building and Deploying your Aletyx Enterprise Build of Kogito and Drools Application

Project pom.xml Configuration

The Maven project configuration includes:
  • Property Definitions: Sets up version constants for dependencies
  • Dependency Management: Imports BOMs (Bill of Materials) for Quarkus and Kogito
  • Dependencies: Lists all required libraries for the application
  • Build Configuration: Sets up the build process
  • Profiles: Configures environment-specific settings (like Kubernetes)
The Kubernetes profile enables specific container image and deployment settings:

2. Build and Push the Application Image

Kubernetes YAML Manifests Explained

PostgreSQL Deployment

The PostgreSQL deployment consists of three parts:
  1. PersistentVolumeClaim: Allocates persistent storage for database files
  2. Deployment: Creates the PostgreSQL pod with proper configuration
  3. Service: Exposes the PostgreSQL port internally
Create a file named postgresql.yaml:
Apply the PostgreSQL configuration:

Main Aletyx Enterprise Build of Kogito and Drools Service Application Deployment

The Quarkus application deployment consists of:
  1. Deployment: Creates the application pod with environment variables
  2. Service: Exposes the application HTTP port
Key deployment features: Create a file named application.yaml - this will be the deployment for the Kogito Process Service:
Apply the application configuration:

Management Console Deployment

Create a file named management-console.yaml:

Ingress Configuration

The ingress resources configure external access to the applications:
  1. TLS Termination: Configures HTTPS with certificates
  2. Path Routing: Routes requests to the appropriate service
  3. Host-based Routing: Separates services by hostname
Create a file named ingress.yaml:
Apply the ingress configuration:

Keycloak Configuration

Keycloak provides authentication and authorization:
  1. Realm: Isolates users and applications
  2. Clients: Represents the applications that can authenticate
  3. Roles: Defines permissions for users
  4. Users: Defines users who can log in
The setup process includes:

Setting up the Keycloak Realm and Clients

Use these commands to interact with Keycloak:

Creating a Test User

Solution for Handling Replacements

To properly handle replacing resources during deployment instead of having to clean them first, you can use this approach in a deployment script:

Automated Deployment Script

Here’s a complete deployment script that addresses the replacement issue:

Accessing the Application

Once deployed, the following endpoints will be available:
  • Main Application: https://<service-name>.<domain-name>/
  • Swagger UI: https://<service-name>.<domain-name>/q/swagger-ui
  • GraphQL UI: https://<service-name>.<domain-name>/graphql-ui
  • Management Console: https://<service-name>-management-console.<domain-name>/

Maven Build Script

Here’s a script to automate the Maven build process:

Troubleshooting

Common Issues

Here’s a comprehensive guide to troubleshooting common issues:

1. Image Pull Errors

Symptoms: Pods remain in ImagePullBackOff or ErrImagePull state Solutions:
  • Verify registry credentials:
  • Confirm image path and tag are correct:
  • Try pulling the image manually:

2. Database Connection Issues

Symptoms: Application logs show connection errors to PostgreSQL Solutions:
  • Verify PostgreSQL pod is running:
  • Check PostgreSQL logs:
  • Test database connection from a temporary pod:

3. Keycloak Authentication Problems

Symptoms: Unable to log in to Management Console Solutions:
  • Verify Keycloak is accessible:
  • Check client configuration:
  • Update client redirectURIs if needed:

4. Ingress/TLS Issues

Symptoms: Unable to access applications via HTTPS or certificate warnings Solutions:
  • Check ingress resource:
  • Verify certificate status:
  • Check cert-manager logs:
  • Ensure DNS records are pointing to the correct IP:

5. Application Startup Issues

Symptoms: Application pod crashes or fails to start Solutions:
  • Check pod logs:
  • Verify environment variables:
  • Check for database migration errors:
  • Ensure all required services are accessible:

Replacing Resources Instead of Recreating

To avoid having to delete resources before deploying, use the --server-side flag with kubectl apply:
For deployments specifically, you can use:

Monitoring

Setting Up Prometheus and Grafana

  1. Install Prometheus and Grafana using Helm:
  1. Configure ServiceMonitor for your application:
  1. Access Grafana and import jBPM/Kogito dashboards.

Scaling and High Availability

Coming soon

Horizontal Pod Autoscaling

yaml apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: {SERVICENAME}hpanamespace:\{SERVICE_NAME\}-hpa namespace: {NAMESPACE} spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: ${SERVICE_NAME} minReplicas: 2 maxReplicas: 5 metrics:
  • type: Resource resource: name: cpu target: type: Utilization averageUtilization: 80

CI/CD Integration

Complete GitHub Actions Workflow

For a complete CI/CD pipeline, here’s a GitHub Actions workflow that builds and deploys the application:

Security Considerations VALIDATION

Network Policies

Restrict network access between pods: apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: {SERVICENAME}networkpolicynamespace:\{SERVICE_NAME\}-network-policy namespace: {NAMESPACE} spec: podSelector: matchLabels: app: ${SERVICE_NAME} policyTypes:
  • Ingress
  • Egress ingress:
  • from:
    • podSelector: matchLabels: app.kubernetes.io/part-of: ${SERVICE_NAME}-app ports:
    • protocol: TCP port: 8080 egress:
  • to:
    • podSelector: matchLabels: app: ${SERVICE_NAME}-postgresql ports:
    • protocol: TCP port: 5432
  • to:
    • ipBlock: cidr: 0.0.0.0/0 except:
      • 10.0.0.0/8
      • 172.16.0.0/12
      • 192.168.0.0/16 ports:
    • protocol: TCP port: 443

Secure Secrets Management

For production, use a dedicated secrets management solution:
  • HashiCorp Vault
  • Azure Key Vault
  • AWS Secrets Manager
  • Kubernetes External Secrets Operator
Example with External Secrets: yaml apiVersion: external-secrets.io/v1beta1 kind: ExternalSecret metadata: name: {SERVICENAME}dbcredentialsnamespace:\{SERVICE_NAME\}-db-credentials namespace: {NAMESPACE} spec: refreshInterval: “15m” secretStoreRef: name: vault-backend kind: ClusterSecretStore target: name: postgresql-credentials data:
  • secretKey: database-user remoteRef: key: ${SERVICE_NAME}/database property: username
  • secretKey: database-password remoteRef: key: ${SERVICE_NAME}/database property: password

Conclusion

This comprehensive guide provides detailed instructions for deploying a jBPM/Kogito Business Process Automation application to Kubernetes. The automated scripts simplify the deployment process, and the detailed explanations help you understand what’s happening behind the scenes. For production deployments, consider these additional best practices:
  • Implement comprehensive monitoring with Prometheus and Grafana
  • Set up proper backup and disaster recovery procedures for the database
  • Implement network policies to restrict traffic between components
  • Set up proper log aggregation with tools like ELK or Loki
By following this guide, you’ll have a robust, scalable, and maintainable Business Process Automation platform running on Kubernetes using Aletyx Enterprise Build of Kogito and Drools!

Additional Resources