Self-Hosted Kubernetes Deployment Guide

This document describes the recommended technical process for deploying the Parallel Works ACTIVATE control plane into a customer-managed, self-hosted Kubernetes environment such as Red Hat OpenShift. The guide reflects a production-oriented deployment model and preserves flexibility for customer-specific infrastructure and security requirements. Parallel Works will provide validated Helm charts and Kubernetes manifests as part of the deployment engagement.

Deployment Topology

The following diagram illustrates the deployment architecture for ACTIVATE on Kubernetes:

Prerequisites and Assumptions

Before beginning the deployment, ensure the following requirements are met:

• Kubernetes Environment: A dedicated Kubernetes or OpenShift cluster for ACTIVATE
• Cluster Access: Cluster-admin privileges during installation
• Storage: Persistent storage class available for PVCs
• DNS: External DNS entry for the ACTIVATE ingress endpoint
• TLS Certificates: TLS certificates issued for the chosen domain
• Registry Access: Outbound access to the Parallel Works container registry

Supporting Services Provisioning

ACTIVATE relies on several supporting services for identity, metadata, billing, and secret management. These services are deployed into the cluster using Helm charts and Kubernetes manifests provided by Parallel Works.

PostgreSQL (Usage and Billing Data)

• Version: PostgreSQL 13.10.7
• Deployment: Kubernetes-managed service
• Baseline Resources: 2 vCPU, 6 GiB RAM
• Purpose: Usage metrics, billing, and activity tracking

MongoDB (User and Platform Metadata)

• Version: MongoDB 5.0.14
• Deployment: Replica set mode (required for sessions and transactions)
• Baseline Resources: 4 vCPU, 4 GiB RAM
• Purpose: User accounts, platform configuration, and metadata

HashiCorp Vault (Secrets Management)

• Edition: Vault Community Edition
• Deployment: In-cluster
• Baseline Resources: 1 vCPU, 2 GiB RAM
• Requirements:
  • Vault must be initialized and unsealed
  • Deployment engineers must have access to make a Vault token or have the root token available
• Purpose: Secure storage of credentials and sensitive configuration

Core Platform Deployment

The ACTIVATE control plane is deployed via Helm and a custom Kubernetes resource managed by the Parallel Works operator.

Namespace and Persistent Storage

• Create a dedicated namespace for the core platform, for example pw-system
• Provision a PersistentVolumeClaim of approximately 20 GiB with ReadWriteMany access mode
• This volume stores user-uploaded images and marketplace workflow assets

Kubernetes Secrets

Create Kubernetes secrets in the core platform namespace for the following:

• Container registry pull credentials (provided by Parallel Works)
• PostgreSQL credentials
• MongoDB credentials
• Vault token

Operator Installation

Add the Parallel Works Helm repository and install the operator:

helm repo add corerepo <repository-url>
helm upgrade --install parallelworks-operator corerepo/operator \
  --namespace pw-operator-system \
  --create-namespace

ACTIVATE Platform Custom Resource

Deploy the ACTIVATE platform by applying a ParallelWorks custom resource. This resource defines image versions, scaling defaults, ingress configuration, TLS, and database connectivity. Key configuration elements include:

• Platform image registry credentials
• Ingress hostname and TLS secret
• PostgreSQL endpoint and credential secret
• MongoDB replica set endpoints

Parallel Works will provide a validated YAML manifest customized for the customer environment. See Sample Configuration below for a YAML example.

Resulting Platform Namespace

Once applied, the operator provisions all ACTIVATE services into the designated core namespace (for example pw-system). This namespace hosts the control plane components and ingress services.

User Workspace Configuration

User workspaces are isolated into a separate namespace, for example pw-users.

• Each user is assigned a dedicated Kubernetes StatefulSet
• Each StatefulSet manages a single pod
• Pods are scaled up when the user is active and scaled down when idle
• Persistent Storage Options:
  • Per-user PersistentVolumeClaim, commonly 5 GiB
  • Or a shared NFS mount provisioned via PVC

Ingress and External Access

An ingress controller or external load balancer must be configured to expose port 443 to the ACTIVATE ingress service running in the core platform namespace.

• DNS should resolve the chosen domain to the ingress endpoint
• TLS termination is handled using the configured Kubernetes TLS secret

Initial Platform Access

After ingress is operational, access the ACTIVATE web interface via HTTPS on the configured domain.

The initial setup workflow allows you to:

1. Enter the ACTIVATE license key
2. Create the first platform administrator account

Once completed, the platform is ready for user onboarding and workspace provisioning.

Sample Configuration

Below is a sample ParallelWorks custom resource YAML configuration:

---
apiVersion: v1
kind: Namespace
metadata:
  name: pw-system
---
apiVersion: platform.parallelworks.com/v1alpha1
kind: ParallelWorks
metadata:
  name: customer
  namespace: pw-system
spec:
  image:
    registry: ghcr.io
    repositoryPrefix: parallelworks
    tag: v5.203
    pullPolicy: IfNotPresent
    pullSecrets:
      - name: image-pull-secret
  
  # Default scale for all services that don't specify their own replicas
  # Services default to enabled=true, so you only need to specify services
  # if you want to customize them or disable them
  defaultScale: 1

  # Host is the ingress hostname for the platform
  host: customer.parallel.works # can be your own domain

  # TLSSecretName for TLS certificate
  tlsSecretName: pw-tls-secret

  # Database configuration
  database:
    # PostgreSQL configuration
    postgres:
      endpoint: 'pw-pgsql-service.postgres.svc.cluster.local:5432'
      database: 'pworks'
      username: 'postgres'
      urlSecretRef:
        name: 'postgres-secret'
        key: 'password'

    # MongoDB configuration (no authentication configured)
    mongodb:
      replicaSetName: 'rs0'
      endpoints:
        - 'mongodb-0-external.mongo.svc.cluster.local:27017'
        - 'mongodb-1-external.mongo.svc.cluster.local:27017'
        - 'mongodb-2-external.mongo.svc.cluster.local:27017'

Customization

This is a sample configuration. Parallel Works will provide a validated and customized manifest tailored to your specific environment during the deployment engagement.

Next Steps

After completing the deployment:

1. Configure authentication providers (e.g. OAuth/LDAP)
2. Set up user groups and permissions
3. Configure compute resources and cloud providers
4. Import or create workflows in the marketplace

For additional assistance, please contact Parallel Works support or your deployment engineer.