An Etlworks managed cluster runs the full Etlworks application and ETL engine in each application pod. It adds application capacity within your Cluster license and coordinates safe removal of pods when demand falls.
You supply an existing Kubernetes cluster. The Etlworks installer deploys the application and the components required by the selected installation profile. You do not build container images, install Tomcat on the worker hosts or run a separate native Etlworks installation on every machine.
For native Linux/Windows installation, regular fixed clusters and general host maintenance, see Running Etlworks on-premise: installation, upgrade, maintenance.
In this article
- Deployment options and current scope
- What the installer deploys
- Before you start
- Prepare self-managed Kubernetes
- Prepare AWS, Azure or Google Cloud Kubernetes
- Download the installer and Cluster license
- Verify and extract your downloads
- Configure the installation
- Install and check progress
- Open Etlworks and finish setup
- Understand pod and node scaling
- Resume an interrupted installation
- View pods and Tomcat logs
- Troubleshooting
- After installation
Deployment options and current scope
The installation procedure in this article applies to the local-nfs-v1 profile supplied in the managed release archive, for Linux AMD64 or ARM64 worker nodes. This is the current local/evaluation profile, with provisioned PostgreSQL, Redis, shared NFS storage and HAProxy. Its bundled infrastructure is not an HA database or production storage architecture.
You can operate Kubernetes yourself on physical servers or VMs, or use a hosted service such as Amazon EKS, Azure AKS or Google Kubernetes Engine (GKE). Those services have different networking, storage and node-maintenance behavior. The current local profile is not a ready-made EKS, AKS or GKE installation profile. Contact Etlworks to confirm an appropriate supported profile before installing on a hosted cluster or planning production use.
The cloud preparation section explains what your platform administrator needs to arrange. It does not authorize replacing a provider's networking or storage with the local profile's components.
What the installer deploys
Users, APIs and Integration Agents
|
HTTPS / HAProxy
|
Etlworks application pods
[application + ETL engine]
|
PostgreSQL / Redis / shared app data
KEDA + HPA ---> desired application pod count
|
Lifecycle adapter
creates / safely drains pods
cert-manager ---> internal certificates and trust
Kubernetes -----> pod placement and process recovery
Node autoscaler (if configured by your administrator) ---> machines| Component | Purpose |
|---|---|
| Application members | Each runs the full app, Tomcat and embedded ETL engine. The license controls starting count, pod size and maximum capacity. |
| Lifecycle adapter | A separate controller that creates members and waits for application and traffic drain before planned removal. |
| KEDA and Kubernetes HPA | Evaluate the configured demand/metrics policy and request an application member count. |
| HAProxy | Provides the selected profile's application traffic entry point and participates in planned traffic withdrawal. |
| PostgreSQL | Holds application metadata and shared application records. |
| Redis | Holds coordination and other application state. |
| Shared application storage | Stores persistent application data used across members, including shared RAG/artifact data where configured. |
| cert-manager and credential components | Issue, deliver and renew internal component certificates. Normal installation does not require you to manually create each component certificate. |
These components consume resources in addition to your licensed application pods. Two licensed application pods do not mean the namespace will contain only two pods. The installer process on your workstation exits after its work; the adapter stays in the cluster to manage the application lifecycle.
Before you start
Installation workstation
Use a Linux or macOS administration workstation with access to the Kubernetes API and these tools:
- Java 25.
- Python 3.12 or newer.
- kubectl, compatible with the selected cluster.
- Helm 3.
- ZIP extraction and SHA-256 verification tools.
- Your cloud provider's authentication CLI/plugin, if your kubeconfig requires it.
The release also contains a PowerShell launcher. Its command parsing is tested; live Windows-workstation cluster installation is not currently qualified by this profile. Use the qualified workstation path unless your release states otherwise.
You do not need a local Tomcat service or a Docker socket for the installation client. Docker may be used to provide a local test Kubernetes cluster; that is a separate platform-preparation step.
Kubernetes access and permissions
Obtain a kubeconfig and identify the exact context for the target cluster. The installer uses that explicit context; it does not switch your active context. Use a dedicated installation namespace and cluster name, and do not point a fresh installation at an existing Etlworks environment's data.
The installation identity needs platform permissions to create the selected profile's CRDs, admission policies, storage and certificate resources, as well as namespaced application resources. Have your Kubernetes administrator perform the installation or supply an appropriately authorized identity. Runtime service accounts use more limited permissions; no human kubeconfig is deployed into app pods.
Cluster capacity
The Cluster license supplies the starting application pod count and resource profile. You do not enter a second starting count or CPU/RAM size in install.json. Choose a trial size your workers can run, or obtain the agreed licensed capacity from Etlworks for your installation.
Each selected pod must fit on one eligible worker using that node's allocatable resources after Kubernetes/system overhead and other workloads. Unused RAM across several smaller nodes cannot be combined to fit one larger pod. Leave additional capacity for PostgreSQL, Redis, proxy, controller, metrics, certificates and storage. For two-pod operation, allow room for both pods; upgrades may require separately licensed receiving/surge capacity.
For example, an 8 GiB/2 CPU trial starts one such application pod and permits up to two. A worker with exactly 8 GiB of physical RAM generally has less than 8 GiB allocatable and is not a sufficient sizing assumption for that pod and its overhead.
Network and persistent state
Prepare:
- A hostname that users, API clients and Integration Agents can resolve and reach.
- DNS and a planned HTTPS access path. The local profile does not create public DNS records or a cloud load balancer for you.
- Registry access for the release's pinned application, adapter and platform images. Public managed images are on Docker Hub and the lifecycle adapter repository.
- Outbound HTTPS to the Etlworks download/licensing services as required by the selected license mode, plus connectivity to your flow sources and destinations.
- Retained storage and enough disk for application data, database growth, logs and backups. Store independent recovery copies outside the cluster's storage failure domain.
The local profile's NFS data path is not encrypted storage traffic. Its application and control TLS connections do not make every storage hop encrypted. Use an isolated trusted evaluation network; production storage/network controls require the corresponding supported deployment profile.
Prepare self-managed Kubernetes
Prepare the Kubernetes cluster before running the Etlworks installer. Cluster creation, operating system installation, worker joins and machine provisioning belong to your platform administration workflow.
The current release profile pins this platform stack:
| Item | Current profile |
|---|---|
| Kubernetes | 1.34.x server; release inventory baseline 1.34.0 |
| Worker OS/CPU | Linux, matching the downloaded AMD64 or ARM64 release |
| Network policy | Calico 3.33.0, with at least two ready Calico instances |
| cert-manager | 1.21.3 |
| NFS CSI | 4.13.6, with the profile's ownership settings |
| KEDA | 2.17.2 |
| Member identity storage | Compatible local-path provisioner with the required private-directory ownership |
| Shared application data | Profile-managed NFSv4.1 storage |
| PostgreSQL / Redis | Provisioned by this installation profile |
Use the inventory shipped with your release as the source for versions. Do not install arbitrary latest component versions or edit release.json to bypass a compatibility check.
For this local profile, prepare at least two ready Linux nodes and identify the storage workers. Ensure that workers can use NFSv4.1 and that the local storage provisioner is available. The installer can install absent pinned Calico, cert-manager, NFS CSI and KEDA assets; it does not bootstrap a missing local-path storage provisioner or turn an arbitrary existing cluster into the qualified platform. Existing shared components must be compatible before installation.
The profile creates retained local storage tied to the selected worker names and shared NFS claims. Local backing paths use /var/local/etlworks-NAMESPACE/. Ensure the underlying worker disks are durable and have sufficient space. The installer can create required local paths; path creation does not supply durable disks or make a disposable worker filesystem persistent. Do not use old data directories as a fresh-install shortcut.
PostgreSQL, Redis and the NFS server are single instances in this profile and are bound to local worker storage. Application pods can scale, but losing their storage worker can still make the application unavailable. Retained PVCs are not backups, and deleting a kind cluster or its worker containers can destroy the local data underneath them.
The installer reuses compatible installed components and does not silently upgrade them. On a shared cluster, have the administrator review platform changes first. --reuse-platform-only prevents the installer from installing missing platform prerequisites, but requires the profile's prerequisites and ownership preparation to have already been completed; it does not bypass compatibility checks.
Inspect access, nodes and storage classes before proceeding:
kubectl --kubeconfig /absolute/path/kubeconfig config get-contexts
kubectl --kubeconfig /absolute/path/kubeconfig --context CONTEXT get nodes -o wide
kubectl --kubeconfig /absolute/path/kubeconfig --context CONTEXT get storageclass
kubectl --kubeconfig /absolute/path/kubeconfig --context CONTEXT get csidriverReplace uppercase placeholders and example absolute paths throughout this guide with your actual values. Do not run the installation against an unverified context.
Prepare AWS, Azure or Google Cloud Kubernetes
Hosted Kubernetes manages some platform responsibilities for you, but an Etlworks installation still needs an agreed application deployment profile. Obtain that profile from Etlworks before running the local-profile installer against a hosted cluster. There is currently no --cloud aws, --cloud azure or --cloud gcp installation option.
Provider preparation checklist
| Platform | Your platform administrator prepares | Confirm with Etlworks before installation |
|---|---|---|
| Amazon EKS | Cluster/API access, Linux worker/node-pool capacity, IAM access, CSI storage, DNS/HTTPS entry and node-scaling policy. | The release's EKS networking/storage profile, persistent-state behavior and safe node disruption settings. |
| Azure AKS | Cluster/API access, Linux node-pool capacity, Azure identity/RBAC, storage, DNS/HTTPS entry and node-scaling policy. | The release's AKS profile and compatibility with an existing Azure-managed KEDA installation. |
| Google GKE | Cluster/API access, Linux node-pool capacity, Google Cloud IAM, storage, DNS/HTTPS entry and node-scaling policy. | The release's GKE profile and whether the chosen cluster mode permits its required workload, storage and admission resources. |
Provider authentication tools retrieve credentials; they do not install Etlworks. Follow the provider's current cluster-access instructions:
After obtaining credentials, use the explicit kubeconfig/context inspection commands above. Private Kubernetes APIs may require VPN or a workstation inside the private network.
Networking, storage and KEDA
Keep provider-managed CNI, CSI and add-ons under their normal platform ownership. Do not install Calico over a cloud provider's network to make a local-profile check pass. A production design needs retained database/Redis state and shared filesystem behavior compatible with Etlworks, including permissions, locks, visibility and recovery. A volume offering ReadWriteMany alone does not prove those semantics, and an object-storage mount is not automatically an equivalent application filesystem.
Some AKS configurations provide KEDA as a managed add-on. Use one compatible KEDA installation and one intended HPA policy owner; do not install a second KEDA stack or another HPA on the Etlworks workload. Azure's add-on availability does not by itself establish compatibility with this release's installer/profile. See KEDA on AKS.
Machines and node scaling
Node size, number, pool limits and cloud quotas are configured outside Etlworks. Provider node autoscalers can add machines when pods cannot be scheduled. Examples are EKS node autoscaling, AKS Cluster Autoscaler and GKE cluster autoscaling.
Node removal is a separate concern from application pod scale-in. Nonempty-node consolidation, upgrades and maintenance must respect Etlworks drain requirements. Do not enable arbitrary forced eviction, short shutdown deadlines or Spot/preemptible loss as a substitute for planned application drain. The safe baseline is additional node provisioning and removal of genuinely empty eligible nodes; other disruption paths require a supported integration. Cloud autoscalers may have finite eviction timeouts, so a PDB alone is not an unlimited-drain guarantee.
An autoscaler cannot move data off the local profile's worker disk. A cloud VM hosting self-managed Kubernetes also remains a local-disk failure domain unless the storage architecture has been deliberately changed and qualified.
Download the installer and Cluster license
You need two separate packages:
| Download | Contains | Does not contain |
|---|---|---|
| Managed installer/release ZIP | Installation client, charts, pinned platform assets, release descriptor and guides. References the exact images to pull. | Your license, kubeconfig or passwords. |
| Cluster license and setup ZIP | Signed environment, licensed capacity, starting configuration, execution authorization and public verification keys. | The installer, issuer private keys, cluster credentials or initial administrator password. |
The managed installation uses an environment-level Cluster license. A regular per-node .lic file or an Integration Agent .alic file is not a replacement for these signed Cluster setup files.
New 14-day Kubernetes trial
- Open the installer request page.
- Enter your name, company and work email.
- Select Managed Kubernetes cluster — 14-day Cluster trial.
-
Choose a pod size that fits your workers:
RAM per application pod CPU cores per pod Starting pods Maximum pods 8 GiB 2 1 2 16 GiB 4 1 2 32 GiB 8 1 2 64 GiB 16 1 2 128 GiB 32 1 2 - Complete reCAPTCHA and submit the request.
- Open the private email link within its one-hour validity period. Select the Linux AMD64 or ARM64 installer for your target Kubernetes workers, and download the Cluster license/setup files too. Retain the displayed SHA-256.
The trial is prepared when the private link is first successfully redeemed. Its 14-day term is fixed; repeat requests do not restart it. Existing customers receive a separate evaluation environment, not an automatic change to their production license. Repeating a request with a different size does not silently resize the trial; contact support to change an existing trial's size.
These trial policies use fixed-term offline execution authorization. They do not require a separate online renewal credential. Internet access may still be needed to download the release and pull images; offline authorization is not an air-gap installation package.
If the Kubernetes option is unavailable, installer-only downloads may still be available on the tools page. Contact support for trial licensing; a regular trial license cannot be converted simply by renaming its files.
Installer only, with an existing Cluster license
Open Installer & CLI tools and use the Kubernetes download option for AMD64 or ARM64. This path does not request a trial and does not include a license. Downloading tools does not install or upgrade your application.
Use the Cluster setup ZIP supplied by your Etlworks licensing administrator for the intended environment. If you have a private customer download link, it can provide both the selected release and that environment's setup files. Private links are credentials: do not share them publicly.
Existing paid/customer environment
Ask the licensing administrator to supply current Cluster license/setup files for the environment. In the licensing portal, the environment's Cluster License editor shows completed steps and the remaining action. The steps are Environment, Capacity, Starting pods, License policy and Downloads. Once the saved state is ready, use Download Cluster license and setup files and the matching installer.
Those portal actions are for the licensing administrator; the person operating the Kubernetes installer does not need license-server administrator access. Online authorization can additionally require a separately supplied renewal credential and its supported installation procedure. The setup ZIP does not contain that credential. Do not assume downloading the setup files creates or rotates it; confirm the complete license-mode prerequisites with Etlworks.
Downloading files does not change a running deployment. License-driven starting capacity is separate from the operational elasticity policy used after installation.
Verify and extract your downloads
Use a separate working directory. Keep the release files unchanged and keep all private installation inputs outside the extracted release.
Compare the installer's SHA-256 with the value supplied through your trusted Etlworks download page/channel before extraction:
# Linux
sha256sum RELEASE.zip
# macOS
shasum -a 256 RELEASE.zipReplace RELEASE.zip with your actual installer filename. Do not use a checksum copied from an unrelated release or architecture.
mkdir etlworks-release
unzip RELEASE.zip -d etlworks-release
cd etlworks-release
python3 deployment/installer/release_archive.py verify --root .
mkdir -p ../etlworks-private
chmod 700 ../etlworks-privateExtract the separate setup ZIP into ../etlworks-private, not into the release directory. Substitute its downloaded filename:
unzip /absolute/downloads/CLUSTER-SETUP.zip -d ../etlworks-private
chmod 600 ../etlworks-private/*.jsonThe setup package contains:
| Filename | Purpose |
|---|---|
| installation-bundle.json | Signed environment binding, capacity and starting configuration. |
| license-authorization.json | Signed execution authorization and its matching grant. |
| environment-public.der | Environment identity verification key. |
| capacity-public.der | Capacity/authorization verification key. |
| bootstrap-public.der | Starting-configuration verification key. |
| README.txt | Package instructions and public-key fingerprints. |
Obtain public keys through the trusted Etlworks channel and verify fingerprints with Etlworks when required by your security policy. Public keys do not issue licenses. Never request or copy the license server's private signing keys into your cluster.
The release verifier checks inventory consistency. Do not add your kubeconfig, install.json, password, logs or backups to the release directory, or mix files from different releases. Retain the original archives and expected checksums.
Configure the installation
Copy the configuration example supplied with your release:
cp deployment/installer/example.json ../etlworks-private/install.json
chmod 600 ../etlworks-private/install.jsonEdit it using absolute paths for your workstation. The following shows the current local profile's input shape; replace the example values with your own:
{
"schemaVersion": 1,
"kubeconfig": "/absolute/etlworks-private/kubeconfig",
"context": "YOUR_CONTEXT",
"namespace": "etlworks-local",
"clusterName": "etlworks",
"releaseDescriptor": "/absolute/etlworks-release/release.json",
"bundle": "/absolute/etlworks-private/installation-bundle.json",
"authorization": "/absolute/etlworks-private/license-authorization.json",
"identityKey": "/absolute/etlworks-private/environment-public.der",
"capacityKey": "/absolute/etlworks-private/capacity-public.der",
"bootstrapKey": "/absolute/etlworks-private/bootstrap-public.der",
"hostname": "etlworks.example.com",
"administrator": {
"email": "owner@example.com",
"passwordFile": "/absolute/etlworks-private/initial-password"
},
"storage": {
"workerA": "YOUR_FIRST_STORAGE_WORKER",
"workerB": "YOUR_SECOND_STORAGE_WORKER"
},
"postgres": { "mode": "provisioned" },
"redis": { "mode": "provisioned" }
}| Setting | How to choose it |
|---|---|
| kubeconfig, context | Exact credentials/context for the intended cluster. |
| namespace, clusterName | Stable installation names. Use lowercase letters, numbers and hyphens; choose before installation. |
| releaseDescriptor | The release.json at the root of the verified extracted release. |
| bundle, authorization | The matching signed setup files for this environment. |
| identityKey, capacityKey, bootstrapKey | The trusted public verifier files from the setup package. |
| hostname | DNS hostname only, without https://, port or URL path. It must match your chosen access path/certificate. |
| administrator.email | Email for the initial administrator account. |
| administrator.passwordFile | Protected file containing only the initial password. Omit this setting to use a hidden interactive prompt in a suitable terminal. |
| storage.workerA, storage.workerB | Actual Linux node names from kubectl get nodes, matching the release CPU architecture. These are storage bindings, not a guarantee of application pod placement. |
| postgres, redis | Keep mode: provisioned for this customer profile. External endpoints are not a supported option of this installer profile. |
Create the password file with a local editor/password manager and protect it:
chmod 600 ../etlworks-private/initial-password
chmod 600 ../etlworks-private/kubeconfigThe initial password must be 8–32 characters, include a letter and a digit, and use only letters, digits, _, !, @, or #. Do not put a password literal in install.json or a shell command. SMTP is not needed to create the initial account.
Do not add sizing keys such as replicas, CPU, RAM or heap to install.json. The installer verifies the signed starting configuration and rejects unsupported fields. The current profile expects the license's local resource profile; contact Etlworks if the supplied license/profile does not match your release.
If registry authentication is needed, the configuration can refer to existing namespace-local image-pull Secret names through imagePullSecrets. Arrange their creation with the platform administrator; never put registry passwords in this JSON. Public images do not require a private repository credential, although registry rate limits and network policy can still affect pulls.
Install and check progress
Run from the verified release root. Review preflight output first:
sh deployment/installer/etlworks-kubernetes.sh preflight \
--config ../etlworks-private/install.json --jsonPreflight validates inputs, signatures, tools, cluster version and selected nodes. It is not proof that every storage, certificate, image pull or runtime startup step will succeed. Resolve reported prerequisites before proceeding.
Start installation:
sh deployment/installer/etlworks-kubernetes.sh install \
--config ../etlworks-private/install.json --wait 20m --jsonThe installer records the installation intent, prepares compatible platform dependencies, retained storage and credentials, starts the provisioned infrastructure, bootstraps the first application member, completes administrator onboarding and reconciles the licensed starting fleet. Short-lived bootstrap Jobs are expected; application pods and the adapter remain running afterward.
Check progress with the same configuration:
sh deployment/installer/etlworks-kubernetes.sh status \
--config ../etlworks-private/install.json --jsonInspect state, phase, reason, counts and signedInitial. Do not equate a Running pod or a completed Helm command with successful Etlworks installation. Wait for confirmed installation/admitting capacity and successful onboarding.
| Exit code | Meaning |
|---|---|
| 0 | The command completed; for installation, the initial fleet was confirmed. Read the command's reported state. |
| 2 | Progress is safely pending; inspect status and resume the same installation. |
| 3 | Installation is blocked; resolve the reported condition. |
| 1 | Invalid input or an unconfirmed/error condition; inspect the error before retrying. |
The --wait 20m value limits the client's wait, not the lifetime of running executions or the authority of a blocked operation.
The regular host CLI can delegate to this same client if you already have it:
ETLWORKS_MANAGED_HOME=/absolute/etlworks-release \
./etlworks-cli.sh kubernetes status \
--config /absolute/etlworks-private/install.json --jsonThe standalone release launcher is sufficient; installing the native host CLI or native Etlworks stack is not a prerequisite.
Open Etlworks and finish setup
Use the configured HTTPS hostname after installation reports readiness. Ensure DNS/client routing and certificate trust are correct for that hostname. A status URL does not mean the installer configured your public DNS or ingress.
For local evaluation, forward the proxy Service. Keep the command running:
kubectl --kubeconfig /absolute/etlworks-private/kubeconfig --context CONTEXT \
-n NAMESPACE port-forward service/CLUSTER_NAME-proxy 8443:443For this access path, map the configured hostname to 127.0.0.1 on your workstation and open https://CONFIGURED_HOSTNAME:8443/. Use your operating system's approved hosts/DNS and certificate-trust procedure. The local frontend certificate is signed by the installation's internal CA; obtain and verify that public CA certificate with the administrator. In this profile it is available as ca.crt in the etlworks-infra-trust Secret; an authorized administrator can export only that public field. Do not export the entire Secret, its private keys or application credentials. Keep TLS verification enabled.
Port forwarding is a workstation access method, not a public ingress or HA endpoint. Other users and Integration Agents need a stable reachable address.
Sign in using the administratorLogin reported by installation status (normally admin for a fresh installation) and the password you supplied. The installer completes its one-time account setup before exposing normal traffic; it does not ask you to use the native installer default password. Resume does not reset a password changed after successful onboarding.
Finish the application configuration:
- Confirm application/engine version and health, then run a representative test flow.
- Set Settings → General → Home URL to the stable URL users and Integration Agents will actually reach, including a nondefault port if applicable. Every Agent host/container must be able to resolve and connect to it.
- Configure email settings for later invitations, password recovery and notifications.
- Review Settings → Elastic cluster, the license bounds and operational policy. Keep minimum/warm capacity and resource thresholds within the license.
- Enable appropriate metrics/alerts, retained logs and independent backups before relying on the installation for important workloads.
Do not copy a regular cluster's HAProxy URL into ETL Engine Proxy URL as an installation step. Managed member routing and its local app/embedded-engine path are supplied by the managed deployment. Change networking settings only through the documented profile or with Etlworks guidance.
Understand pod and node scaling
The Cluster license sets hard capacity limits, allowed pod sizes and the starting fleet. The operational policy governs demand-based behavior within those bounds. CPU, container RAM and JVM heap are separate observations; pod RAM includes more than heap. Heap usage alone is not total container memory.
KEDA/HPA requests a desired application count. The lifecycle adapter creates members or drains selected members safely. HPA does not directly delete a busy application pod. Ordinary executions finish; only healthy continuous executions with current relocation eligibility may be stopped/replaced for planned movement. The adapter waits for actual work termination and required handoff/traffic barriers. Actual count can therefore remain above desired count while a drain is blocked.
A trial starts one pod even though it permits two. A maximum is a ceiling, not a request to create that many pods. Two nodes do not guarantee one application pod on each node. Kubernetes placement depends on resource availability and the release's placement rules. Extra pods can receive new executions; they do not split an already-running indivisible flow across machines.
Node count and machine size remain platform-admin settings. A fixed self-managed cluster can still scale Etlworks pods within its available capacity. Node autoscaling is optional and can be configured on hosted clusters or other infrastructure with a supported node provisioner. More desired pods do not automatically produce machines on a cluster without such a provisioner.
An unavailable/crashed pod may be replaced by Kubernetes as a process-recovery action. This is not permission to automatically replay its business executions.
Resume an interrupted installation
If the terminal disconnects, the workstation restarts or the client wait expires, retain the same release directory, configuration, license inputs, namespace and cluster. First inspect status, then resume:
sh deployment/installer/etlworks-kubernetes.sh status \
--config ../etlworks-private/install.json --json
sh deployment/installer/etlworks-kubernetes.sh resume \
--config ../etlworks-private/install.json --wait 20m --jsonThe installation's retained intent and receipts are in Kubernetes, not only on your workstation. Resume reconciles the same operation rather than blindly starting a second fleet or resetting administrator credentials. A concurrent or interrupted installer lease may need to expire before another client can proceed.
If blocked, fix the reported dependency and resume. Do not delete Secrets, installation receipts, member operations, PVCs or the namespace to clear a hold. Do not change cluster/context, storage worker bindings, hostname or release as a resume shortcut. Missing or changed identities require investigation/recovery. There is no automatic uninstall/reset/force command that safely discards uncertain installation state.
If signed inputs expired, obtain current setup files and follow the reported licensing/recovery path. Once a first pod is allocated, arbitrary replacement of its bootstrap files is not an accepted renewal mechanism.
View pods and Tomcat logs
Use the release client:
sh deployment/installer/etlworks-kubernetes.sh pods \
--config ../etlworks-private/install.json
sh deployment/installer/etlworks-kubernetes.sh logs \
--config ../etlworks-private/install.json --pod APP_POD --tail 200 --follow
sh deployment/installer/etlworks-kubernetes.sh logs \
--config ../etlworks-private/install.json --pod APP_POD --previous
sh deployment/installer/etlworks-kubernetes.sh logs \
--config ../etlworks-private/install.json --pod CONTROLLER_POD \
--container controller --tail 200 --followThe application container is app-engine; the controller container is controller. The pod listing includes infrastructure/Jobs as well as application members. Ctrl+C ends log following. --previous selects a previous container instance within an existing pod; it does not retrieve deleted-pod history.
Direct kubectl is also available:
kubectl --kubeconfig /absolute/etlworks-private/kubeconfig --context CONTEXT \
-n NAMESPACE get pods -o wide
kubectl --kubeconfig /absolute/etlworks-private/kubeconfig --context CONTEXT \
-n NAMESPACE logs APP_POD -c app-engine --tail=200 --follow
kubectl --kubeconfig /absolute/etlworks-private/kubeconfig --context CONTEXT \
-n NAMESPACE describe pod APP_POD
kubectl --kubeconfig /absolute/etlworks-private/kubeconfig --context CONTEXT \
-n NAMESPACE get events --sort-by=.metadata.creationTimestampThese commands require Kubernetes permissions for the relevant observations/logs, not an Etlworks application login. A log-follow session stays with the named pod; select its replacement explicitly. Arrange central logging to retain logs after pod deletion.
Create a bounded, read-only support snapshot outside the release directory:
sh deployment/installer/etlworks-kubernetes.sh diagnostics \
--config ../etlworks-private/install.json \
--output ../etlworks-private/support.zipThis is a public-status diagnostic bundle, not a full backup or an unrestricted log/Secret export. Supply relevant logs separately through the protected support channel. Do not attach kubeconfigs, private keys, passwords or signed private download links to public tickets.
Troubleshooting
| Symptom | Check and next action |
|---|---|
| No Kubernetes trial option | Trial availability and installer availability are separate. Check the request/tools pages and contact Etlworks if trial licensing is unavailable. |
| Email/private link expired | Request a replacement link. A replacement for the same trial does not restart its 14-day term. |
| Existing trial rejects a different size | Choose the original size or contact support to change that trial. Do not create identities to restart the trial. |
| Download says setup is held/not ready | The licensing administrator should follow the portal's next incomplete/expired step, save the starting configuration against current capacity and issue matching authorization as directed. Downloading the installer alone does not fix a license hold. |
| Checksum/inventory mismatch | Stop; obtain the correct archive/checksum. Do not edit release.json or mix extracted releases. Keep private inputs outside the release root. |
| JAVA_25_REQUIRED / HOST_TOOL_REQUIRED | Verify Java 25, Python, kubectl and Helm on the installation workstation, including PATH/JAVA_HOME. |
| KUBERNETES_PROFILE_UNSUPPORTED / UNSUPPORTED_RELEASE_PROFILE | Verify the actual release profile and Kubernetes version. Do not change version strings to bypass the check. |
| LOCAL_STORAGE_PROFILE_REQUIRED / network-policy profile error | The selected cluster lacks the required local provisioner or compatible Calico setup. Ask the platform administrator to prepare the supported profile; do not overwrite a hosted cluster's CNI. |
| Pod Pending / insufficient CPU or memory | Inspect describe pod, allocatable resources, taints, architecture and placement. A larger license does not add machines. Each pod must fit on one eligible node. |
| Pending PVC or volume/mount error | Inspect PVC/PV bindings, CSI availability, storage worker identity and NFS reachability/permissions. Retain existing volumes and data while investigating. |
| ImagePullBackOff | Check registry access, architecture, exact digest and any image-pull Secret references. Do not substitute latest. |
| Certificate/webhook pending | Inspect cert-manager readiness and certificate events. Wait/resume when dependencies settle; do not regenerate retained signing/trust state manually. |
| Browser TLS/DNS error | Verify hostname resolution, proxy access and the approved public CA trust. Port forwarding does not configure DNS. Keep verification enabled. |
| Installer exits pending / wait ends | Check status and resume the same operation. A timeout does not prove failure or authorize a new install. |
| Known Secret/receipt/UID missing or changed | Preserve the current state and contact support; do not recreate identity records to force progress. |
| Desired count differs from actual count | Inspect pending placement, licensing and drain blockers. Long-running ordinary work can legitimately prevent scale-in. |
| A connection closes during a long flow | Check timeouts and keepalives at every frontend/LB/network hop, not only HAProxy. Connection loss is not proof the engine stopped; check execution state before retrying. |
| Login password-change request errors after setup | Configure SMTP and verify whether the password already changed before repeating an ambiguous request. Initial onboarding itself does not require SMTP. |
For support, provide release identity, profile/architecture, installation state and reason, relevant pod events/logs, and the bounded diagnostics ZIP. Share sensitive material only through an approved protected channel.
After installation
Keep the verified release, protected configuration, current license/setup files and independent backups available for maintenance. Do not modify application workloads directly to perform upgrades or force a scale-in.
Managed application upgrades use Settings → Elastic cluster → Managed cluster upgrades for a SuperAdmin, or the release client's update commands with Kubernetes permissions. The UI/backend submits a durable managed operation; it does not execute a native host CLI. Use a supported registered source/target release pair and review its plan. Native host upgrade instructions do not apply to the managed pods. Application schema migration remains app-driven under the upgrade protocol; swapping back an image is not database rollback.
The supplied release includes operations and recovery instructions. Use those for supported backup/restore and maintenance. Backups cover database state, the dedicated Redis database's complete logical contents, shared app data and protected installation/credential information. Keep independent copies outside local NFS; the local backup export shares its server's failure domain. A restore can finish held for explicit reconciliation/cutover rather than automatically resuming flows. Migration to or from a regular installation requires the explicit supported migration workflow and source isolation.
Upgrading the app does not automatically upgrade Kubernetes, cert-manager, KEDA, the lifecycle adapter, PostgreSQL/Redis server binaries or the storage platform. Coordinate those platform changes separately with the administrator and Etlworks.
For assistance, contact Etlworks support.