multiflexi-executor

Execute MultiFlexi jobs (one-shot or as a long-running daemon).

MultiFlexi

multiflexi-executor is part of the MultiFlexi suite. See the full list of ready-to-run applications within the MultiFlexi platform on the application list page.

Requirements

• PHP 8.2+ (daemon parallel mode requires the pcntl extension)
• Composer
• A configured MultiFlexi database (shared across the suite)

Installation (development)

composer install

Configuration (.env)

Place a .env file at the repository root. The executor reads configuration via Ease\Shared.

Common keys:

• DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD
• APP_DEBUG=true|false
• MULTIFLEXI_DAEMONIZE=true|false
• MULTIFLEXI_CYCLE_PAUSE=10 # seconds between polling cycles when daemonized
• RESULT_FILE=php://stdout # default output destination for one-shot runs
• ZABBIX_SERVER, ZABBIX_HOST # enable LogToZabbix if available

Notes:

• src/executor.php and src/daemon.php expect vendor/autoload.php and .env one directory above. Run them from src/ so relative paths resolve.
• Parallel execution requires the pcntl extension. On Debian-based systems install the package matching your PHP version (e.g., php8.3-pcntl).

Usage

One-shot execution (run a single RunTemplate)

From repo root:

cd src && php -q -f executor.php -- -r <RUNTEMPLATE_ID> [-o <output_path>] [-e <env_file>]

Flags:

• -r, --runtemplate: RunTemplate ID to execute
• -o, --output: destination for captured output (defaults to stdout or RESULT_FILE)
• -e, --environment: path to .env (defaults to ../.env)

Daemon (polls DB and executes due jobs)

From repo root:

cd src && php -q -f daemon.php

Behavior:

• Controlled by .env. When MULTIFLEXI_DAEMONIZE=true, the process runs continuously and sleeps MULTIFLEXI_CYCLE_PAUSE seconds between cycles.
• Parallel execution: if pcntl is available, due jobs are executed in parallel using forks. Limit concurrency with MULTIFLEXI_MAX_PARALLEL (set 0 for unlimited).

Examples:

# Run daemon with up to 4 concurrent jobs
MULTIFLEXI_MAX_PARALLEL=4 php -q -f src/daemon.php

# Unlimited parallelism (default when 0 or unset)
php -q -f src/daemon.php

Useful Make targets

make vendor                     # install dependencies
make static-code-analysis       # phpstan
make static-code-analysis-baseline
make cs                         # coding standards (php-cs-fixer)
make autoload                   # composer update
make tests                      # run PHPUnit tests
make buildimage                 # build container image
make buildx                     # multi-arch build & push
make drun                       # run container (requires .env)

Testing

Run all tests:

make tests

Run a single test file or filtered tests:

vendor/bin/phpunit path/to/TestFile.php
vendor/bin/phpunit --filter "TestNameOrRegex"

Scheduling example (via CLI)

The repo includes an integration-oriented script under tests/ that schedules a RunTemplate using multiflexi-cli:

multiflexi-cli runtemplate schedule --id 1 --format json

Kubernetes Executor

The Kubernetes executor (MultiFlexi\Executor\Kubernetes) runs jobs as one-shot pods in a Kubernetes cluster using kubectl run --attach.

How it works

1. Config derivation: The executor reconstructs Kubernetes config from existing DB fields — no dedicated kubernetes JSON column is needed:
   • helmchart column → Helm chart URI (OCI or repo reference)
   • name column → Helm release name (lowercased, DNS-1123 safe)
   • artifacts column → artifact output paths for kubectl cp
   • Sensible defaults for namespace (multiflexi), timeout (300s), etc.
2. Helm pre-deploy: On first run, if the application is not yet deployed, the executor runs helm upgrade --install using the chart from the helmchart DB field.
3. Job execution: Creates an ephemeral pod via kubectl run with --restart=Never --attach, passing environment variables via --env flags.
4. Artifact collection: After pod completion, copies artifacts from the pod via kubectl cp and stores them in the MultiFlexi FileStore.
5. Log capture: storeLogs() fetches pod output via kubectl logs after job completion.

Requirements

• kubectl binary in PATH
• helm binary in PATH (for Helm pre-deployment)
• Valid kubeconfig at ~/.kube/config or $KUBECONFIG
• Applications must have ociimage set (container image reference)
• Applications should have helmchart set to a valid Helm chart URI for first-time deployment

File-path environment variables

File-path config fields from the executor host are skipped for Kubernetes jobs — host paths are not available inside the pod. A warning is logged for each skipped field.

Azure Container Instances Executor

The Azure executor (MultiFlexi\Executor\Azure) runs jobs as one-shot containers in Azure Container Instances (ACI).

How it works

1. Container creation: Creates a container group via az container create --restart-policy Never (one-shot).
2. Environment variables: Passes env vars via --environment-variables. Sensitive vars (containing PASSWORD, SECRET, TOKEN, KEY) are routed to --secure-environment-variables.
3. Status polling: Polls az container show every 10 seconds until the container reaches a terminal state (up to 1 hour).
4. Log collection: Fetches output via az container logs after completion.
5. Cleanup: Deletes the container group via az container delete.

Requirements

• Azure CLI (az) in PATH, authenticated (az login)
• AZURE_RESOURCE_GROUP environment variable set (required)
• Applications must have ociimage set

Configuration (environment variables)

• AZURE_RESOURCE_GROUP — Azure resource group (required)
• AZURE_LOCATION — Azure region (default: westeurope)
• AZURE_CPU — CPU cores per container (default: 1)
• AZURE_MEMORY — Memory in GB per container (default: 1.5)