# K3s {% hint style="info" %} #### K3s K3s is a lightweight, certified Kubernetes distribution designed for resource-constrained environments, edge computing, IoT devices, and development scenarios. Created by Rancher Labs (now part of SUSE), it packages everything needed to run Kubernetes into a single binary under 100MB. This makes K3s significantly lighter than standard Kubernetes while maintaining full compatibility with Kubernetes APIs and features. It requires minimal memory (512MB minimum) and offers simplified operations with reduced dependencies. K3s comes with built-in components like the Traefik ingress controller, local storage provisioner, and service load balancer. It's perfect for development, CI/CD, edge deployments, and ARM devices, yet remains production-ready with high availability capabilities. {% endhint %}

K3s & Pentaho Server Architecture

{% tabs %} {% tab title="K3s Core Components" %} {% hint style="info" %} #### K3s Core Components **Control Plane Components** The control plane includes the API Server (Kubernetes API endpoint for cluster management), Controller Manager (manages core control loops for replication, endpoints, and namespaces), and Scheduler (assigns pods to nodes based on resource availability). K3s can use either etcd or lightweight SQLite as the datastore for cluster state, making it more flexible than standard Kubernetes. **Node Components** Each node runs the Kubelet agent which manages pod lifecycle. Containerd is built-in as the container runtime for running containers. Kube-proxy manages network proxying and service networking across the cluster. **Built-in Add-ons** K3s includes Traefik Ingress Controller for routing external HTTP/HTTPS traffic to services. The Local Path Provisioner enables dynamic persistent volume provisioning using local storage. CoreDNS provides cluster DNS for service discovery. The Service Load Balancer manages LoadBalancer-type services without requiring external cloud provider integrations. **Networking** Flannel serves as the default CNI (Container Network Interface) plugin for pod networking. Network Policies control traffic flow between pods and services for enhanced security. {% endhint %}

K3s Components

{% endtab %} {% tab title="Pentaho Server Pod" %} {% hint style="info" %} #### Pentaho Server Pod * Runs Tomcat application server with Pentaho Server 11 * Built on Debian Trixie Slim with OpenJDK 21 JRE * Multi-stage Docker build for optimized image size * Exposed internally on port 8080 * Includes readiness and liveness probes for health monitoring * Resource limits configured for CPU and memory stability {% endhint %}

Pentaho Pod

{% endtab %} {% tab title="PostgreSQL Pod" %} {% hint style="info" %} Provides relational database backend for three critical databases: * **Jackrabbit** (jcr\_user): Java Content Repository storing all Pentaho content (reports, dashboards, data sources, transformations, jobs) * **Quartz** (pentaho\_user): Scheduler managing jobs, triggers, calendars, and execution history * **Hibernate** (hibuser): Security configuration, audit logging, user sessions, plus two specialized schemas: * **pentaho\_dilogs**: ETL execution logging with job logs, transformation metrics, and step performance data * **pentaho\_operations\_mart**: Dimensional data mart for platform analytics with dimension and fact tables * Data persisted through PersistentVolumeClaim to survive restarts * Automated initialization via ConfigMap-mounted SQL scripts {% endhint %}

PostgreSQL Pod

PostgreSQL Database Architecture

Pentaho Server requires three separate databases, each serving a distinct purpose:
DatabaseOwnerPurpose & Contents
jackrabbitjcr_userJava Content Repository (JCR) - Stores all Pentaho content including reports, dashboards, data sources, analysis schemas, and user files. This is the primary content storage for the Pentaho repository.
quartzpentaho_userQuartz Scheduler - Manages all scheduled jobs, triggers, and calendars. Contains tables for job definitions (QRTZ6_JOB_DETAILS), triggers (QRTZ6_TRIGGERS), execution history, and cluster coordination locks.
hibernatehibuserHibernate Repository - Hosts security configuration, audit logging, user session data, and contains two additional schemas: pentaho_dilogs (ETL execution logging) and pentaho_operations_mart (analytics data mart).
{% hint style="info" %} The hibernate database contains specialized schemas for operational monitoring: **pentaho\_dilogs**: Captures detailed ETL execution information including job logs, transformation logs, step performance metrics, and error records. Essential for debugging data integration workflows and monitoring pipeline health. **pentaho\_operations\_mart**: A dimensional data mart for analytics on Pentaho usage. Contains dimension tables (DIM\_DATE, DIM\_TIME, DIM\_EXECUTOR) and fact tables (FACT\_EXECUTION, FACT\_STEP\_EXECUTION) for analyzing platform utilization, performance trends, and user activity. For production deployments, implement regular backups of the repository-data Docker volume. The jackrabbit database is the most critical as it contains all user content. Consider using pg\_dump for logical backups or volume snapshots for full recovery options. {% endhint %} {% endtab %} {% tab title="Network" %} {% hint style="info" %} #### Netwoking **Internal Communication:** * Both pods run within the `pentaho` namespace * ClusterIP services provide stable internal DNS names * PostgreSQL accessible at `postgresql.pentaho.svc.cluster.local:5432` * Pentaho Server accessible at `pentaho-server.pentaho.svc.cluster.local:8080` **External Access:** * Traefik Ingress Controller routes external traffic to Pentaho Server * Configurable hostname and path-based routing * Optional TLS/SSL termination support {% endhint %} Tomcat manages connection pools defined in context.xml. Each pool serves a specific purpose:
Pool NameConnection TargetUsed For
jdbc/Hibernaterepository:5432/hibernateSecurity, Users, Roles
jdbc/Quartzrepository:5432/quartzJob Scheduling
jdbc/jackrabbitrepository:5432/jackrabbitContent Repository
jdbc/Auditrepository:5432/hibernateAudit Logging
jdbc/live_logging_inforepository:5432/hibernateETL Runtime Logs
jdbc/PDI_Operations_Martrepository:5432/hibernateOperations Analytics
{% endtab %} {% tab title="Storage ConfigMaps" %} {% hint style="info" %} #### Storage **PersistentVolumeClaims (PVCs):** * `postgres-pvc`: PostgreSQL data directory (`/var/lib/postgresql/data`) * `pentaho-pvc`: Pentaho solutions and data directories **Storage Class:** * Uses K3s's built-in `local-path` storage provisioner * Provisions volumes on node's local filesystem * Automatic volume creation and binding **ConfigMaps:** * Database initialization scripts (5 SQL files) * Pentaho configuration settings (JVM parameters, Tomcat settings) **Secrets:** * PostgreSQL credentials (postgres\_password, pentaho\_user, pentaho\_password) * JDBC connection strings * Base64-encoded for security {% endhint %} {% endtab %} {% endtabs %} {% hint style="danger" %} Before you begin the K3s deployment, ensure you have completed the Setup: [Pentaho Containers](/pentaho-11-installation-en/setup/pentaho-containers.md) {% endhint %} Run through the following steps to deploy Pentaho Server on a single-node K3s with PostgreSQL 15 repository. {% tabs %} {% tab title="1. Prepare Environment " %} {% hint style="info" %} #### Prepare Environment The "Prepare Environment" section outlines the initial setup steps required before deploying Pentaho Server 11 on K3s: * copying the deployment assets to your home directory, * staging the Pentaho Server Enterprise Edition ZIP file, verifying the file is in place, * confirming K3s is properly installed and running {% endhint %} {% hint style="danger" %} Ensure you have downloaded: `pentaho-server-ee-11.0.0.0-237.zip` {% endhint %} 1. Create directory & copy over assets. ```bash cd cd ~/Workshop--Installation/Pentaho-Containers/K3s/Pentaho-K3s-PostgreSQL/scripts chmod +x ./install-to-home.sh ``` 2. Copy over the pentaho-server-ee-11.0.0.0-237.zip /docker/stagedArtefacts directory. {% hint style="info" %} If you have deployed an Archive Pentaho Server then copy from: `/opt/pentaho/software/pentaho-server-ee-version` Otherwise download package from the [Pentaho Customer Portal](https://support.pentaho.com/hc/en-us). {% endhint %} ```bash cd cd ~/Pentaho-K3s-PostgreSQL/docker-build/stagedArtifacts cp /opt/pentaho/software/server/pentaho-server-ee-11.0.0.0-237.zip . ``` 3. Verify that the file. ```bash cd cd ~/Pentaho-K3s-PostgreSQL/docker-build/stagedArtifacts ls -al ``` 4. Verify the K3s installation. ```sh cd cd ~/Pentaho-K3s-PostgreSQL/scripts ./verify-k3s.sh ``` ```sh # Normal verification (what you'd run most of the time) ./scripts/verify-k3s.sh # Detailed output for debugging ./scripts/verify-k3s.sh --verbose # Silent mode for scripts/automation ./scripts/verify-k3s.sh --quiet # Get help ./scripts/verify-k3s.sh --help ```

verify-k3s.sh

5. Pentaho Server requires a valid license. The `.env` file contains a LICENSE\_URL pointing to the Flexera license server. Ensure your license entitlements are active before deployment. {% hint style="warning" %} Without a valid license, Pentaho Server will start but many features will be disabled. Verify your license status before proceeding with production deployments. {% endhint %} **Key Differences**
AspectDocker DeploymentK3s Deployment
OrchestrationDocker ComposeKubernetes (K3s)
Configuration.env file + docker-compose.ymlKubernetes manifests (YAML)
SecretsDocker secrets or VaultKubernetes Secrets
NetworkingDocker bridge networkK3s cluster network + Traefik Ingress
StorageDocker volumesPersistentVolumeClaims (PVCs)
ScalingManual (docker compose up --scale)Declarative (replicas in deployment)
Health ChecksDocker HEALTHCHECKKubernetes readiness/liveness probes
Init ScriptsVolume mount to /docker-entrypoint-initdb.dConfigMap mounted to PostgreSQL pod
{% endtab %} {% tab title="2. Preflight Tasks" %} {% hint style="info" %} #### Pre-flight Taks The Pre-flight Tasks section outlines the essential preparation steps needed before deploying Pentaho Server 11 in K3s containers. **Configure Environment Variables** Edit the `.env.example` file within the `docker-build/` directory with your deployment-specific settings. This includes Pentaho version identifier and Docker image name/tag. Configure PostgreSQL database credentials and connection parameters. Set JVM memory allocation with minimum heap (default 4GB) and maximum heap (default 8GB). Add your Enterprise Edition license server URL if applicable. Configure build options including image edition (EE/CE), plugin detection, and registry push settings. Once configured, copy this template to `.env` for use by the build process. **softwareOverride Directory** The `softwareOverride/` directory within `docker-build/` provides a mechanism for customizing Pentaho configurations. These customizations get baked into the Docker image during the build process. Files are organized in numbered directories and processed in alphabetical order. The **1\_drivers/** directory contains the PostgreSQL JDBC driver (included by default), and you can place additional JDBC drivers here. The **2\_repository/** directory holds database connection configurations for Jackrabbit (JCR), Quartz (scheduler), and Hibernate repositories. The **3\_security/** directory is empty in this K3s deployment since there's no Vault integration. The **4\_others/** directory contains modified Tomcat scripts (startup.sh, setenv.sh), server.xml, and other application-level configurations. You can optionally upgrade the PostgreSQL JDBC driver by downloading from Maven Central or copying from the workshop's database drivers collection. Place the updated driver in `softwareOverride/1_drivers/tomcat/lib/`. {% endhint %} *** **Configure .env** 1. Edit the .env.template ```bash cd cd ~/Pentaho-Server-PostgreSQL nano .env.template ``` 2. Enter the following details:
VariableDefaultDescription
PENTAHO_VERSION11.0.0.0-237Pentaho Server version
EDITIONeeEnterprise version
INCLUDE_DEMO1Include demo data
IMAGE_TAGpentaho/pentaho-server:11.0.0.0-237Docker image tag
PENTAHO_MIN_MEMORY4096mJVM minimum heap size
PENTAHO_MAX_MEMORY8192mJVM maximum heap size
PENTAHO_DI_JAVA_OPTIONS"-Dfile.encoding=utf8 -Djava.awt.headless=true"
PENTAHO_IMAGE_NAMEpentaho/pentaho-serverDocker image name
TZAmerica/NYTime Zone of server
DB_TYPEpostgres
DB_HOSTpostgres
DB_PORT5432PostgreSQL HTTP port
PUSH_TO REGISTRYfalsePushes direct to K3s Regsitry
LOAD_INTO_K3StrueLoads directly to K3s
RUN TESTStrue
LICENSE_URL(empty)EE license server URL
3. Save: ``` CTRL + o Enter CTRL + x ``` 4. Create .env ```bash cd cd ~/Pentaho-Server-PostgreSQL cp .env.template .env ``` *** **softwareOverride** {% hint style="info" %} The `softwareOverride/` directory provides a powerful mechanism to customize Pentaho Server without modifying the core installation. Files are copied into the Pentaho installation during container startup, processed in alphabetical order by directory name. {% endhint %} ```` ``` softwareOverride/ ├── 1_drivers/ # JDBC drivers and data connectors │ ├── tomcat/lib/ │ │ └── postgresql-42.x.x.jar # PostgreSQL JDBC driver (included) │ └── pentaho-solutions/drivers/ # Big data drivers (.kar files) ├── 2_repository/ # Database repository configuration │ ├── pentaho-solutions/system/ │ │ ├── hibernate/hibernate-settings.xml │ │ ├── jackrabbit/repository.xml │ │ └── scheduler-plugin/quartz/quartz.properties │ └── tomcat/webapps/pentaho/META-INF/context.xml ├── 3_security/ # Authentication and authorization │ └── pentaho-solutions/system/ │ ├── applicationContext-spring-security-hibernate.properties │ └── applicationContext-spring-security-memory.xml ├── 4_others/ # Tomcat, defaults, and miscellaneous │ ├── pentaho-solutions/system/ │ │ ├── defaultUser.spring.properties │ │ ├── pentaho.xml │ │ └── security.properties │ └── tomcat/ │ ├── bin/startup.sh │ └── webapps/pentaho/WEB-INF/web.xml └── 99_exchange/ # User data exchange (not auto-processed) ``` ```` The PostgreSQL JDBC driver is included in the Pentaho distribution. If you need to upgrade: 1. Download from [Maven Central](https://repo1.maven.org/maven2/org/postgresql/postgresql/) 2. Place in `softwareOverride/1_drivers/tomcat/lib/` Or Copy from Workshop--Installation/'Database Drivers'/ ```bash cd cd ~/Workshop--Installation/'Database Drivers' cp postgresql-42.7.8.jar ~/Pentaho-Server-PostgreSQL/softwareOverride/1_drivers/tomcat/lib ``` {% endtab %} {% tab title="3. Build & Push Image" %} {% hint style="info" %} #### Build & Push Pentaho Image The build.sh script is an automated build wrapper that: * Validates prerequisites - Checks Docker is installed * Checks for required files - Verifies Pentaho ZIP exists in stagedArtifacts/ * Detects plugins automatically - Finds PAZ, PIR, PDD plugins * Confirms build - Shows what will be built and asks for confirmation * Runs docker build - Executes the build with proper arguments * Shows image info - Displays image size and details after build * Optional: Tests image - Runs basic container test (you can skip this) * Optional: Pushes to registry - Pushes to Docker registry (only with -p flag) This is the **recommended approach** for building Pentaho Docker images. It uses a single `.env` file to configure everything - similar to the Docker Compose deployment. {% endhint %} You can modify the build with the following options:
Option (short)Option (Long)Description
-v--version VERSIONPentaho version (default: 11.0.0.0-237)
-t--tag TAGDocker image tag (default: pentaho/pentaho-server:VERSION)
-e--edition EDITIONee or ce (default: ee)
-d--demoInclude demo content (default: no)
-p--pushPush to registry after build
-h--helpPush to registry after build
1. Build & Push the Pentaho Server Image directly into K3s Registry. ```bash # Build with defaults based on .env cd cd ~/Pentaho-K3s-PostgreSQL/docker-build ./build.sh ```

Build & Push Pentaho Server image

{% hint style="info" %} **1. Docker Image Build:** The deployment uses a custom-built Pentaho Server container image: ``` docker-build/ ├── Dockerfile (multi-stage build) ├── build.sh (automated build script) ├── stagedArtifacts/ (Pentaho Server ZIP) └── softwareOverride/ (configuration overlays) ├── 1_drivers/ (PostgreSQL JDBC driver) ├── 2_repository/ (database configs) ├── 3_security/ (authentication) └── 4_others/ (Tomcat customizations) ``` The `build.sh` script: * Validates prerequisites and required files * Detects plugins automatically (PAZ, PIR, PDD) * Executes multi-stage Docker build * Optionally pushes to K3s image store **2. Configuration Management:** * `.env` file contains deployment-specific settings (versions, credentials, JVM memory) * `softwareOverride/` directory provides configuration overlays processed in numbered order * PostgreSQL JDBC driver included by default, with option to upgrade * Custom Tomcat scripts for container startup optimization {% endhint %} {% endtab %} {% tab title="4. Helm Charts" %} {% hint style="info" %} #### Helm Charts Helm is the package manager for Kubernetes, often referred to as "apt/yum for Kubernetes." It simplifies the deployment and management of Kubernetes applications by: **Packaging**: Bundling related Kubernetes resources together **Templating**: Parameterizing manifests for reusability across environments **Versioning**: Managing application versions and upgrades **Release Management**: Tracking deployments and enabling rollbacks {% endhint %}

Helm Charts

{% tabs %} {% tab title="1. Directories" %} {% hint style="info" %} #### Directory Layout Below is an explanation of the pentaho directory responsible for a Helm deployment. {% endhint %} ``` pentaho/ # Chart root directory ├── Chart.yaml # Chart metadata (name, version, description) ├── values.yaml # Default configuration values ├── templates/ # Kubernetes manifest templates │ ├── _helpers.tpl # Template helper functions (not rendered) │ ├── NOTES.txt # Post-installation instructions │ ├── namespace.yaml # Namespace creation │ ├── secret.yaml # Sensitive data (passwords, keys) │ ├── configmap-*.yaml # Configuration data │ ├── pvc.yaml # Persistent volume claims │ ├── *-deployment.yaml # Pod deployments │ ├── *-service.yaml # Service definitions │ └── ingress.yaml # Ingress routing rules └── files/ # Non-template files (SQL scripts, configs) └── db_init/ # PostgreSQL initialization scripts ``` **Chart.yaml** {% hint style="info" %} This file defines the chart's identity, version, and metadata used by Helm. It serves as the "package definition" for the Helm chart, similar to package.json (npm) or Chart.lock (Helm dependencies). Role: Chart.yaml tells Helm what this chart is, what version it is, what application it deploys, and provides searchable metadata for chart repositories. Helm uses this file to track chart versions, manage dependencies, and display information when users search for or install charts. {% endhint %} **values.yaml** {% hint style="info" %} In a K3s (lightweight Kubernetes) deployment, the `values.yaml` file serves as the central configuration file for Helm charts. It defines default parameters and settings that customize how an application or service is deployed to the cluster - things like replica counts, image versions, resource limits, service types, ingress rules, environment variables, and persistent storage configurations. When you run `helm install` or `helm upgrade`, Helm merges the values from this file with the chart's templates to generate the final Kubernetes manifests. You can override specific values at deploy time using `--set` flags or by supplying a custom values file with `-f`, making it a flexible mechanism for managing environment-specific configurations (e.g., dev vs. production) without modifying the underlying chart templates. {% endhint %} *** **templates**
YAMLDescription
namespace.yamlCreates an isolated Kubernetes namespace to contain all Pentaho resources
secret.yamlStores sensitive database credentials (passwords) encrypted in Kubernetes
config-*.yamlConfigures Pentaho environment variables (JVM memory, database settings, paths, timezone) Contains SQL scripts to initialize PostgreSQL databases (jackrabbit, quartz, hibernate) on first startup
pvc.yamlRequests persistent storage volumes for PostgreSQL data and optional Pentaho data/solutions
*-deployment.yamlDeploys Pentaho Business Analytics Server with init container, health probes, and resource limits. Deploys PostgreSQL 15 database server with automatic initialization and persistent storage
*-service.yamlRoutes external HTTP/HTTPS traffic to Pentaho Server via Traefik ingress controller. Exposes PostgreSQL port 5432 as a stable DNS endpoint for Pentaho to connect to.
ingress.yamlRoutes external HTTP/HTTPS traffic to Pentaho Server via Traefik ingress controller
{% endtab %} {% tab title="2. Deploy" %} {% hint style="info" %} #### Deploy The architecture consists of two main pods running within a dedicated Pentaho namespace: a Pentaho Server pod (Tomcat on Debian with OpenJDK 21) and a PostgreSQL pod hosting three essential databases - Jackrabbit for content storage, Quartz for job scheduling, and Hibernate for security and audit logging. {% endhint %} {% hint style="danger" %} Before you proceed, ensure you have completed Steps 1 - 3. You should have a Pentaho Server image + PostgreSQL 15 repository images pushed to the K3s repository. {% endhint %} 1. Quick check. ```bash # Check Helm version (requires 3.0+) helm version # Check Kubernetes cluster kubectl cluster-info kubectl get nodes # Check available storage classes kubectl get storageclass ``` 2. Check The Pentaho Image is available. ```bash # Verify sudo k3s ctr images ls | grep pentaho ```

Pentaho Server image in K3s repository

*** {% hint style="info" %} #### Default Deployment The deployment workflow progresses through four stages: * preparing the environment by staging the Pentaho Enterprise Edition package and verifying K3s. * configuring environment variables and software overrides during pre-flight tasks. * building and pushing a custom Docker image into the K3s container runtime. * finally deploying the full stack using either Helm charts or an automated `deploy.sh` script that orchestrates namespace creation, secrets, ConfigMaps, persistent storage, and Traefik ingress routing. Also covers the Helm chart structure, a suite of helper scripts for backup, health checks, resource monitoring, and deployment validation, along with multiple access methods including port-forwarding, hostname-based ingress, and direct node IP. {% endhint %} 1. Install using Helm charts. ```bash cd cd ~/Pentaho-K3s-PostgreSQL/helm-chart helm install pentaho ./pentaho ```

Deploy Pentaho Server - Helm Chart

{% endtab %} {% endtabs %} {% endtab %} {% tab title="Helper Scripts" %} {% hint style="info" %} #### Helper Scripts The K3s Pentaho deployment includes a collection of helper scripts in the `scripts/` directory for day-to-day operations and maintenance: * **backup-postgres.sh:** Creates timestamped, compressed dumps of all Pentaho databases (Jackrabbit, Quartz, Hibernate) using `pg_dump` executed inside the PostgreSQL pod. * **restore-postgres.sh:** Restores Pentaho databases from backup files, useful for disaster recovery, environment cloning, or migrating data between clusters. * **health-check.sh:** Performs a quick runtime health check covering pod readiness, service availability, database connectivity, and a live HTTP test against the Pentaho login page. * **validate-deployment.sh:** Runs a comprehensive audit across six categories: namespace, pods, services, PersistentVolumeClaims, ConfigMaps, and ingress configuration. * **monitor-resources.sh:** Tracks CPU and memory usage across all Pentaho pods using `kubectl top` to help identify resource constraints or optimization opportunities. * **monitor-postgres.sh:** Monitors PostgreSQL-specific metrics including connection counts, active queries, table sizes, and overall database health. * **verify-k3s.sh:** Validates the underlying K3s infrastructure (node status, storage classes, Traefik ingress, and core components) before attempting a Pentaho deployment. * **Makefile:** Provides convenience commands such as `make health`, `make status`, `make logs`, `make port-forward`, and `make destroy` for streamlined cluster management. {% endhint %} {% tabs %} {% tab title="1. Directories" %} {% hint style="info" %} #### Directory Layout This K3s deployment configuration provides several important capabilities: * Completely self-contained Kubernetes deployment on lightweight K3s * Automated database initialization with PostgreSQL SQL scripts * Kubernetes-native health checks and startup ordering * Persistent volume claims for database and Pentaho content * Docker image build process with multi-stage optimization * Resource limits (CPU/memory) for stability * Production-ready Kubernetes manifest templates * PostgreSQL JDBC driver included * Easy backup and restore procedures via utility scripts * Ingress configuration for Traefik routing {% endhint %} *** **Root Directory Files** ``` Pentaho-K3s-PostgreSQL/ ├── deploy.sh # Main deployment script ├── destroy.sh # Cleanup script ├── Makefile # Quick commands (make help) ├── README.md # This file ├── DEPLOYMENT.md # Detailed deployment guide ├── K3s-INSTALLATION.md # K3s setup instructions ``` {% hint style="info" %} **Documentation Files:** **README.md** - The main entry point documentation providing project overview, quick start instructions, prerequisites, and general usage information for the K3s deployment workshop. **DEPLOYMENT.md** - Detailed deployment guide covering the complete K3s deployment workflow, including pre-requisites, step-by-step instructions, and post-deployment verification procedures. **K3s-INSTALLATION.md** - K3s setup and installation instructions covering system preparation, K3s installation, networking configuration, and storage class setup required before deploying Pentaho. **Orchestration & Deployment:** **deploy.sh** - Automated deployment script that orchestrates the complete K3s deployment workflow including namespace creation, secret generation, manifest application, and service readiness checks. **destroy.sh** - Cleanup script that safely removes all K3s resources including deployments, services, persistent volume claims, and namespaces, useful for redeployment or teardown scenarios. **Makefile** - Contains convenience command targets for common K3s operations like deploying, destroying, checking status, and viewing logs. Users can run `make help` to see all available commands. {% endhint %} *** **docker-build** ``` ├── docker-build/ # Docker image build │ ├── build.sh # Build script │ ├── Dockerfile # Image definition │ ├── README.md # Complete build documentation │ ├── QUICK-START.md # Quick build guide │ ├── ENV-CONFIGURATION.md # .env configuration guide │ ├── .env.example # Configuration template │ ├── test-compose.yml # Local Docker testing │ ├── entrypoint/ # Container startup scripts │ │ ├── docker-entrypoint.sh │ │ └── start-pentaho-docker.sh │ ├── softwareOverride/ # Config overlays (baked into image) │ │ ├── 1_drivers/ # PostgreSQL JDBC driver │ │ ├── 2_repository/ # Database configs │ │ │ └── README.md │ │ ├── 3_security/ # (empty - no Vault) │ │ └── 4_others/ # Modified Tomcat scripts │ │ └── README.md │ └── stagedArtifacts/ # Place Pentaho ZIP here │ └── README.md ``` {% hint style="info" %} The **docker-build/** directory contains all components needed to build the Pentaho Server container image that will be deployed to K3s: **Documentation Files:** **README.md** - Complete build documentation covering the Docker image build process, multi-stage build architecture, configuration options, troubleshooting, and best practices for building Pentaho Server images for K3s deployment. **QUICK-START.md** - Quick build guide providing step-by-step instructions for users who want to quickly build and test the Pentaho image without reading the complete documentation. Includes common build commands and typical workflows. **ENV-CONFIGURATION.md** - Comprehensive configuration reference guide for the `.env.example` file, detailing all available environment variables, their purposes, default values, and how they affect the Docker build process and resulting image. **Build & Configuration Files:** **build.sh** - Automated build wrapper script that validates prerequisites, checks for required files (Pentaho ZIP in `stagedArtifacts/`), detects plugins automatically (PAZ, PIR, PDD), confirms the build with the user, executes `docker build`, shows image info after build, and optionally pushes to a registry with the `-p` flag. **.env.example** - Configuration template file containing all available environment variables for the Docker build process. Users copy this to `.env` and customize values for their specific deployment needs including Pentaho version, image tags, and build options. **Dockerfile** - Multi-stage build definition using `debian:trixie-slim` as the base image with OpenJDK 21 JRE. Creates optimized images by separating the build environment from the runtime environment, reducing final image size while maintaining all necessary Pentaho components. The multi-stage approach minimizes security vulnerabilities and improves build efficiency. **test-compose.yml** - Local Docker Compose testing environment that allows you to test the built Docker image locally before deploying to K3s. This is useful for validating configuration changes, testing custom plugins, or debugging startup issues without the overhead of a full K3s deployment. **Container Startup Scripts:** **entrypoint/** - Directory containing container initialization and startup scripts: * **docker-entrypoint.sh** - Primary container startup script that executes when the container starts. Handles environment variable processing, configuration file customization from `softwareOverride/`, database connection validation, health checks, and orchestrates the Pentaho Server startup sequence. * **start-pentaho-docker.sh** - Pentaho-specific startup script that manages Tomcat initialization, JVM configuration, memory settings, and starts the Pentaho Server services. This script is called by `docker-entrypoint.sh` after environment preparation is complete. **Configuration Overlays:** **softwareOverride/** - Configuration overlays directory that gets baked into the Docker image during the build process. Files are organized in numbered directories and processed in alphabetical order to ensure proper application sequence: * **1\_drivers/** - PostgreSQL JDBC driver (included by default) for database connectivity. Additional JDBC drivers or data connectors can be placed here. * **2\_repository/** - Database connection configurations for all Pentaho repositories including Jackrabbit (JCR), Quartz (scheduler), and Hibernate (security/audit). Contains a **README.md** explaining the repository configuration files and their purposes. * **3\_security/** - Empty in this K3s deployment since HashiCorp Vault integration is not used. In production environments, this would contain authentication, authorization, and security configuration files. * **4\_others/** - Modified Tomcat scripts (startup.sh, setenv.sh), server.xml, web.xml, and other application-level configurations. Contains a **README.md** documenting the custom Tomcat modifications and their purposes. **Staged Artifacts:** **stagedArtifacts/** - Staging directory where users place the Pentaho Server installation package (`pentaho-server-ee-11.0.0.0-237.zip`) before building the Docker image. Contains a **README.md** with instructions on where to obtain the Pentaho package and how to stage it properly. {% endhint %} *** **db\_init\_postgres** ``` ├── db_init_postgres/ # PostgreSQL init SQL scripts │ ├── 1_create_jcr_postgresql.sql │ ├── 2_create_quartz_postgresql.sql │ ├── 3_create_repository_postgresql.sql │ ├── 4_pentaho_logging_postgresql.sql │ └── 5_pentaho_mart_postgresql.sql ``` {% hint style="info" %} The **db\_init\_postgres/** directory contains PostgreSQL initialization scripts that create all required Pentaho repository databases. These scripts are mounted into the PostgreSQL container and execute automatically on first startup: **1\_create\_jcr\_postgresql.sql** - Creates the **Jackrabbit Content Repository (JCR)** database. The JCR stores all Pentaho content including reports, dashboards, data sources, analysis schemas, transformations, jobs, and user files. This is the primary content management system for the Pentaho repository. **2\_create\_quartz\_postgresql.sql** - Sets up the **Quartz Scheduler** database. Quartz manages all scheduled jobs, triggers, and calendars within Pentaho Server, including report generation schedules, ETL job executions, and other automated processes. Contains critical tables like `QRTZ6_JOB_DETAILS`, `QRTZ6_TRIGGERS`, and execution history. **3\_create\_repository\_postgresql.sql** - Creates the **Hibernate Repository** database. This stores user authentication data, authorization information, roles, permissions, and other security-related information managed by Pentaho's security subsystem. **4\_pentaho\_logging\_postgresql.sql** - Establishes the **pentaho\_dilogs** schema within the Hibernate database for audit and Data Integration (DI) logging. Captures detailed ETL execution information including job logs, transformation logs, step performance metrics, and error records. Essential for debugging data integration workflows and monitoring pipeline health. **5\_pentaho\_mart\_postgresql.sql** - Creates the **pentaho\_operations\_mart** schema within the Hibernate database. This dimensional data mart stores operational analytics about Pentaho Server usage, including dimension tables (`DIM_DATE`, `DIM_TIME`, `DIM_EXECUTOR`) and fact tables (`FACT_EXECUTION`, `FACT_STEP_EXECUTION`) for analyzing platform utilization, performance trends, and user activity patterns. {% endhint %} *** **manifests** ``` ├── manifests/ # Kubernetes manifests │ ├── namespace.yaml # Pentaho namespace │ ├── configmaps/ │ │ ├── pentaho-config.yaml │ │ └── postgres-init-scripts.yaml │ ├── pentaho/ │ │ ├── deployment.yaml │ │ └── service.yaml │ ├── postgres/ │ │ ├── deployment.yaml │ │ └── service.yaml │ ├── secrets/ │ │ └── secrets.yaml # (gitignored) │ ├── storage/ │ │ └── pvc.yaml │ └── ingress/ │ └── ingress.yaml ``` {% hint style="info" %} The **manifests/** directory contains all Kubernetes resource definitions organized by functional area. These YAML files define the declarative state of your K3s deployment: **namespace.yaml** - Creates the dedicated `pentaho` namespace to isolate all Pentaho-related resources from other K3s workloads, providing logical separation and resource organization. **configmaps/** - ConfigMap resources for non-sensitive configuration data: * **pentaho-config.yaml** - Pentaho Server configuration settings like JVM parameters, Tomcat settings, and application properties * **postgres-init-scripts.yaml** - ConfigMap containing the five PostgreSQL initialization scripts from `db_init_postgres/` directory, mounted into the PostgreSQL pod **pentaho/** - Pentaho Server Kubernetes resources: * **deployment.yaml** - Defines the Pentaho Server deployment including container specifications, resource requests/limits, environment variables, volume mounts, readiness/liveness probes, and replica count * **service.yaml** - ClusterIP service exposing Pentaho Server on port 8080 within the cluster, providing stable internal DNS and load balancing **postgres/** - PostgreSQL database Kubernetes resources: * **deployment.yaml** - Defines the PostgreSQL 15 deployment with container specifications, persistent volume claims for data storage, initialization script mounting, and database configuration * **service.yaml** - ClusterIP service exposing PostgreSQL on port 5432 within the cluster for Pentaho Server database connections **secrets/** - Sensitive credential storage: * **secrets.yaml** - Kubernetes Secret resource containing base64-encoded credentials for PostgreSQL (`postgres_password`, `pentaho_user`, `pentaho_password`) and JDBC connection strings. **This file is gitignored for security.** **storage/** - Persistent storage definitions: * **pvc.yaml** - PersistentVolumeClaim definitions for both PostgreSQL data (`postgres-pvc`) and Pentaho solutions/data (`pentaho-pvc`), using K3s's local-path storage class for persistent data across pod restarts **ingress/** - External access configuration: * **ingress.yaml** - Traefik Ingress resource defining external HTTP/HTTPS routing rules to expose Pentaho Server outside the K3s cluster, including hostname, path routing, and TLS configuration if applicable {% endhint %} *** **scripts** ``` └── scripts/ # Utility scripts ├── backup-postgres.sh # Database backup ├── restore-postgres.sh # Database restore ├── health-check.sh # Health check ├── monitor-resources.sh # Resource monitoring ├── monitor-postgres.sh # PostgreSQL monitoring ├── validate-deployment.sh # Deployment validation └── verify-k3s.sh # K3s verification ``` {% hint style="info" %} The **scripts/** directory contains operational and maintenance utilities for managing the K3s Pentaho deployment: **Database Management:** **backup-postgres.sh** - Automated PostgreSQL backup utility that creates compressed dumps of all Pentaho databases (jackrabbit, quartz, hibernate) using `kubectl exec` to run `pg_dump` inside the PostgreSQL pod. Backups are timestamped and compressed with gzip for efficient storage. **restore-postgres.sh** - Database restoration utility to recover Pentaho databases from backup files. Useful for disaster recovery, environment cloning, or migrating data between K3s clusters. Handles decompression and restoration via `kubectl exec` and `psql`. **Monitoring & Validation:** **health-check.sh** - Health check script that verifies both PostgreSQL and Pentaho Server are running and responding correctly. Checks pod status, readiness probes, and performs basic connectivity tests. **monitor-resources.sh** - Resource monitoring utility that tracks CPU, memory, and storage usage across all Pentaho pods using `kubectl top` and resource metrics, helping identify resource constraints or optimization opportunities. **monitor-postgres.sh** - PostgreSQL-specific monitoring script that checks database connection counts, active queries, table sizes, and database health metrics via SQL queries executed in the PostgreSQL pod. **validate-deployment.sh** - Comprehensive deployment validation script that confirms all K3s resources are properly created, pods are running, services are accessible, persistent volumes are bound, and the entire deployment is operational. **verify-k3s.sh** - K3s infrastructure verification script that checks K3s installation, node status, storage classes, Traefik ingress controller, and core K3s components before attempting Pentaho deployment. {% endhint %} *** **Key Differences: K3s vs Docker**
AspectDocker DeploymentK3s Deployment
OrchestrationDocker ComposeKubernetes (K3s)
Configuration.env file + docker-compose.ymlKubernetes manifests (YAML)
SecretsDocker secrets or VaultKubernetes Secrets
NetworkingDocker bridge networkK3s cluster network + Traefik Ingress
StorageDocker volumesPersistentVolumeClaims (PVCs)
ScalingManual (docker compose up --scale)Declarative (replicas in deployment)
Health ChecksDocker HEALTHCHECKKubernetes readiness/liveness probes
Init ScriptsVolume mount to /docker-entrypoint-initdb.dConfigMap mounted to PostgreSQL pod
{% endtab %} {% tab title="2. Deploy" %} {% hint style="info" %} #### Deployment execution The `deploy.sh` script automates the entire workflow: * Verifies K3s is running * Creates namespace * Applies all manifests in correct order * Monitors pod startup * Validates service readiness * Provides deployment summary with access URLs **1. Namespace Creation:** ```bash kubectl create namespace pentaho ``` Creates isolated logical environment for all Pentaho resources. **2. Secret Generation:** ```bash kubectl apply -f manifests/secrets/secrets.yaml ``` Stores PostgreSQL credentials and JDBC connection strings as Kubernetes Secrets. **3. Storage Provisioning:** ```bash kubectl apply -f manifests/storage/pvc.yaml ``` Creates PersistentVolumeClaims for PostgreSQL data and Pentaho content. **4. ConfigMap Creation:** ```bash kubectl apply -f manifests/configmaps/ ``` Mounts PostgreSQL initialization scripts and Pentaho configuration. **5. PostgreSQL Deployment:** ```bash kubectl apply -f manifests/postgres/ ``` Deploys PostgreSQL pod with: * Mounted init scripts (automatic database creation on first startup) * Persistent volume for data * Health checks and resource limits * ClusterIP service for internal connectivity **6. Pentaho Server Deployment:** ```bash kubectl apply -f manifests/pentaho/ ``` Deploys Pentaho pod with: * Custom Docker image * Environment variables from ConfigMap and Secrets * Volume mounts for solutions/data * Readiness/liveness probes * ClusterIP service **7. Ingress Configuration:** ```bash kubectl apply -f manifests/ingress/ingress.yaml ``` Configures Traefik routing for external access. {% endhint %} 1. Run the deploy.sh ```sh cd cd ~/Pentaho-K3s-PostgreSQL ./deploy.sh ```

Deploy Pentaho Server

{% hint style="info" %} This unified script handles the complete deployment process for Pentaho Server on K3s, including: * Docker image import into K3s container runtime * Kubernetes resource creation (namespace, secrets, configmaps, storage) * PostgreSQL database deployment * Pentaho Server deployment * Ingress configuration * Health checks and status reporting ``` Usage: ./deploy.sh # Fresh deployment with image import ./deploy.sh --skip-import # Deploy without importing image ./deploy.sh --update-only # Only update existing deployment ./deploy.sh --clean # Remove old images before deploying ``` Prerequisites: * K3s installed and running * Docker image built: pentaho/pentaho-server:11.0.0.0-237 * kubectl configured to access K3s cluster * sudo access for K3s containerd operations {% endhint %} *** **Quick Commands with Makefile** ```bash make help # Show all available commands make full-deploy # Build, import, and deploy (complete workflow) make health # Run health check make status # Show deployment status make logs # View Pentaho logs make port-forward # Access Pentaho at localhost:8080 make destroy # Remove deployment ``` *** There's also bunch of scripts that will help validate the deployment: {% tabs %} {% tab title="Validate Deployment" %} {% hint style="info" %} Comprehensive post-deployment validation script that verifies all components of the Pentaho K3s deployment are properly configured and running correctly. What It Checks (6 Categories) **Namespace** * Verifies pentaho namespace exists **Pods** * PostgreSQL pod is Running * Pentaho Server pod is Running * Shows current status if not running **Services** * PostgreSQL service exists * Pentaho Server service exists **PersistentVolumeClaims (3 PVCs)** * postgres-data-pvc (10Gi) - Database files * pentaho-data-pvc (10Gi) - Pentaho * data pentaho-solutions-pvc (5Gi) - Solutions repository * All must be in "Bound" status **ConfigMaps** * pentaho-config - Environment variables * postgres-init - Database initialization scripts **Ingress** * pentaho-ingress - Traefik routing configuration **Database Connectivity Tests** * Connects to PostgreSQL pod * Tests all 3 Pentaho databases: \* jackrabbit - JCR content repository \* quartz - Job scheduler \* hibernate - Configuration repository * Runs SELECT 1 query on each {% endhint %} 1. Run the following `validate-deployment.sh` script. ```sh cd cd ~/Pentaho-K3s-PostgreSQL/scripts ./validate-deployment.sh ```

Validate deployment

{% endtab %} {% tab title="Health Check" %} {% hint style="info" %} #### Health Check Quick health check script for running Pentaho deployment - faster and lighter than full validation, focused on runtime health status. Namespace * Verifies pentaho namespace exists * Exits immediately if namespace missing (critical) Pod Readiness * PostgreSQL pod is ready (not just running) * Pentaho Server pod is ready * Checks `containerStatuses[0].ready status` Services * PostgreSQL service exists * Pentaho Server service exists Database Connectivity * PostgreSQL is responding to queries All 3 databases exist: \* jackrabbit \* quartz \* hibernate * Uses `psql -lqt` to list databases Web Application Health * Live HTTP test to Pentaho login page * Uses port-forward to access service * Expects HTTP 200 response * Tests: ; Resource Usage * Shows CPU/memory usage via `kubectl top pods` * Gracefully handles missing metrics-server {% endhint %} ```sh cd cd ~/Pentaho-K3s-PostgreSQL/scripts ./health-check.sh ```

Health Check

{% endtab %} {% tab title="Monitor Resources" %} {% hint style="info" %} #### Monitor Resources x {% endhint %} ```sh cd cd ~/Pentaho-K3s-PostgreSQL/scripts ./validate-deployment.sh ```
{% endtab %} {% tab title="Pentaho Server" %} {% hint style="info" %} #### Accessing Pentaho Server {% endhint %} **Port Forward (Recommended for Testing/Development)** The simplest method using kubectl to forward a local port to the Pentaho service: ```bash kubectl port-forward -n pentaho svc/pentaho-server 8080:8080 ``` **Access URL:** `http://localhost:8080/pentaho` You can also use an alternate port if 8080 is busy: ```bash kubectl port-forward -n pentaho svc/pentaho-server 9080:8080 # Then access: http://localhost:9080/pentaho ``` *** **Ingress with Hostname (pentaho.local)** Uses K3s's built-in Traefik ingress controller with DNS-style access: **Setup:** ```bash echo "10.0.0.1 pentaho.local" | sudo tee -a /etc/hosts ``` *(Replace 10.0.0.1 with your actual node IP)* **Access URL:** `http://pentaho.local/pentaho` *** **Ingress via Direct Node IP (No DNS Required)** Access directly through any cluster node's IP address without configuring /etc/hosts: **Access URL:** `http:///pentaho` This works because the ingress includes a path-based rule that doesn't require a hostname. *** **Makefile Convenience Command** The project includes a Makefile shortcut: ```bash make port-forward ``` This automatically sets up port forwarding to localhost:8080. *** **Default Credentials** | Username | Password | | -------- | -------- | | admin | password | ⚠️ Change these for production deployments! *** **Quick Reference** | Method | Best For | URL | | ------------------- | ------------------- | ------------------------------- | | Port Forward | Development/Testing | `http://localhost:8080/pentaho` | | Ingress (hostname) | Production with DNS | `http://pentaho.local/pentaho` | | Ingress (direct IP) | Testing without DNS | `http:///pentaho` | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | | {% endtab %} | | | | {% endtabs %} | | | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://academy.pentaho.com/pentaho-11-installation-en/installation/containers/k3s.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.